Release preparation commands

tagpr.command and tagpr.postVersionCommand automate project-specific file changes in the release pull request. Use them for work that should be reviewed and committed before the release tag is created, such as regenerating metadata, synchronizing version declarations, or updating dependency files.

These commands prepare the release pull request. They do not run after the release is tagged and are not intended for publishing packages or deploying applications. Use the action’s tag output for those tasks.

Execution order

When tagpr creates or updates a release pull request, it performs the relevant work in this order:

1. Determine the current and proposed next versions.
2. Run tagpr.command.
3. Update every configured version file.
4. Run tagpr.postVersionCommand.
5. Create the release-note configuration when needed.
6. Generate and update the changelog when enabled.
7. Commit the resulting changes to the release pull request branch.

Both hooks run again whenever tagpr refreshes the release pull request after the release branch advances. Commands should therefore be deterministic and safe to run repeatedly.

Choose the appropriate hook

Use tagpr.command when the script should run before tagpr changes version files:

[tagpr]
    command = go generate ./...

Use tagpr.postVersionCommand when the script needs to read the proposed version from the already-updated version files:

[tagpr]
    postVersionCommand = ./scripts/update-release-metadata

Both hooks know the proposed version through environment variables, so a pre-version command can still generate next-version content without reading a version file.

Version environment variables

tagpr adds these variables to the command environment:

In a monorepo, these values do not include tagpr.tagPrefix. For example, a release whose full tag is tools/v1.3.0 receives TAGPR_NEXT_VERSION=v1.3.0.

Example script:

#!/bin/sh
set -eu

printf '%s\n' "$TAGPR_NEXT_VERSION" > generated/release-version.txt
git add generated/release-version.txt

Working directory and paths

Commands run from tagpr’s working directory. The GitHub Action runs tagpr from GITHUB_WORKSPACE, so commands normally run from the repository root even when the selected .tagpr file is in a subdirectory.

For a monorepo configuration at tools/.tagpr, include the project path in the command:

# tools/.tagpr
[tagpr]
    command = ./tools/scripts/prepare-release
    postVersionCommand = go run ./tools/cmd/update-metadata

Files included in the release pull request

Changes to tracked files are detected and included in the release pull request. If a command creates a new untracked file, the command must stage it with git add so tagpr can include it.

Keep generated output inside the repository and avoid making unrelated working-tree changes. The command may modify or delete more than one file.

Command output and failures

Standard output and standard error are streamed to the tagpr log.

If either command exits with a non-zero status, tagpr records the failure and emits a GitHub Actions error annotation containing the configuration key, command, exit status, and standard error. It still runs the remaining release preparation steps. In particular, a failed tagpr.command does not prevent version files from being updated, tagpr.postVersionCommand from running, or the release pull request from being created or updated.

After the release pull request processing finishes, tagpr returns the recorded command failure and exits with a non-zero status. If both commands fail, or later tagpr processing also fails, the errors are reported together. The GitHub Actions step is therefore marked as failed even when the release pull request was successfully created or updated; inspect the annotation and command output before merging it.

Release after tagging

Do not use these hooks to upload packages based on a tag that does not exist yet. To run the release flow only after tagpr creates the tag, use the action’s tag output as described in Tagging and release .