Skip to content
Tagging and release

Tagging and release

tagpr treats the version tag as the starting point of the release flow. After tagging, a project can build and package artifacts, publish packages and GitHub Release assets, or deploy applications.

The tag identifies the exact source and version being released. tagpr exposes that tag as an output for downstream steps, or the tag push can trigger a separate release workflow.

Note

When a repository enables immutable releases and a downstream operation adds GitHub Release assets, publish the release only after every asset is attached. See Coordinating Immutable Releases for the tagpr.release = draft and tagpr.release = false coordination patterns.

Signed tags

tagpr respects Git’s standard tag.gpgSign configuration. When it is true, tagpr creates a signed annotated tag with the message Release <tag>. When it is false or unset, tagpr creates the same lightweight tag as before.

Configure the signing format, key, agent, certificate, and Git identity before running tagpr. tagpr does not import or manage signing keys. For example, after configuring GPG, SSH, or X.509 signing:

- name: Enable signed tags
  run: git config --global tag.gpgSign true

If signing is enabled but Git cannot create the signature, tagpr fails without pushing the tag.

For keyless signing in GitHub Actions, Chainguard’s setup-gitsign action configures Git to use the workflow’s OIDC identity:

permissions:
  contents: write
  pull-requests: write
  issues: read
  id-token: write

steps:
- uses: actions/checkout@v6
  with:
    persist-credentials: false
- uses: chainguard-dev/actions/setup-gitsign@805da2efdffdc42b8afd8880e575a48b471ef544 # v1.6.37
- uses: Songmu/tagpr@v1
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

setup-gitsign enables tag.gpgSign itself, so no additional Git configuration is required. It uses short-lived Sigstore certificates instead of a long-lived signing key. GitHub does not currently display gitsign commit or tag signatures as Verified; use gitsign verify-tag when verification is required.

GITHUB_TOKEN constraints

The repository’s GITHUB_TOKEN is the simplest credential to use with tagpr because GitHub creates it automatically for each workflow run. However, events created with GITHUB_TOKEN do not normally start another workflow run . This affects tagpr in two places:

  • a tag created by tagpr does not trigger a workflow configured with on.push.tags;
  • pull_request workflows for a release pull request created or updated by tagpr are created in an approval-pending state, but do not run until a user with write access approves them .

There are two ways to start the release flow automatically after tagpr creates a tag:

LayoutAdvantageTradeoff
Run release steps in the tagpr workflowUses GITHUB_TOKEN without additional credentialsRelease PR workflows require approval, and release steps share tagpr’s workflow permissions and environment
Trigger a separate release workflowSeparates release responsibilities and lets tag and release PR workflows run automaticallyRequires a token that can trigger workflows

Run the release in the same workflow

The tag output is non-empty after successful tag creation or recovery. Use it as the condition for release steps in the same workflow. Successful retries can return an existing matching tag and run these steps again, so make them safe to retry:

- uses: actions/checkout@v6
  with:
    persist-credentials: false
- id: tagpr
  uses: Songmu/tagpr@v1
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Publish
  if: steps.tagpr.outputs.tag != ''
  uses: ./.github/actions/release
  with:
    tag: ${{ steps.tagpr.outputs.tag }}
    token: ${{ secrets.GITHUB_TOKEN }}

This layout does not need a GitHub App or personal access token. Keeping the release logic in a script or local composite action limits the coupling even though tagpr and the project-specific release steps share a workflow. See Songmu/ecschedule’s tagpr workflow for a complete example.

Other available outputs are:

  • pull_request: JSON describing the release pull request;
  • base_tag: the previous tag used as the comparison base, or an empty value for the first release.

Test and approve before tagging

Note

Experimental: plan and apply modes and the plan JSON format may change in future releases.

By default, tagpr creates the tag as soon as it detects a merged release pull request. Use plan and apply modes when the exact merged commit must pass additional tests or wait for a protected-environment approval before tagging.

plan mode creates or updates the release pull request normally. Once it detects a merged release pull request, it emits a single plan JSON output without creating a tag. If it only creates or updates the pull request, the plan output is empty. The JSON contains:

  • tag: the proposed version tag;
  • commit_sha: the exact merged release commit to test and tag;
  • base_tag: the previous release tag, or an empty string for the first release;
  • pull_request_number: the merged release pull request number;
  • release_notes_boundary_sha: the end boundary used to generate release notes.

The final job passes the JSON unchanged to apply mode using the plan input. tagpr then verifies the plan against repository state before creating the tag. The target may cease to be the release branch head while approval is pending, but it must still be an ancestor of the configured release branch.

After applying the plan, use the existing tag, pull_request, and base_tag outputs for subsequent release steps. Before applying it, use fromJSON(...).commit_sha to check out the commit to test.

name: tagpr
on:
  push:
    branches:
    - main
  workflow_dispatch:

# Keep the active approval run and collapse later main pushes into one pending run.
concurrency:
  group: tagpr-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

permissions:
  contents: write
  pull-requests: write
  issues: read

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      plan: ${{ steps.plan.outputs.plan }}
    steps:
    - name: Generate token
      id: app-token
      uses: actions/create-github-app-token@v3
      with:
        client-id: ${{ secrets.CLIENT_ID }}
        private-key: ${{ secrets.PRIVATE_KEY }}
        permission-contents: write
        permission-pull-requests: write
        permission-issues: read
    - uses: actions/checkout@v6
      with:
        token: ${{ steps.app-token.outputs.token }}
        persist-credentials: false
    - id: plan
      uses: Songmu/tagpr@v1
      with:
        mode: plan
      env:
        GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

  test-release:
    needs: plan
    if: needs.plan.outputs.plan != ''
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
    - uses: actions/checkout@v6
      with:
        ref: ${{ fromJSON(needs.plan.outputs.plan).commit_sha }}
        persist-credentials: false
    - run: go test ./...

  apply:
    needs:
    - plan
    - test-release
    if: needs.plan.outputs.plan != '' && needs.test-release.result == 'success'
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: write
      pull-requests: read
    steps:
    # This token is created after the protected environment is approved.
    - name: Generate token
      id: app-token
      uses: actions/create-github-app-token@v3
      with:
        client-id: ${{ secrets.CLIENT_ID }}
        private-key: ${{ secrets.PRIVATE_KEY }}
        permission-contents: write
        permission-pull-requests: read
    - uses: actions/checkout@v6
      with:
        ref: ${{ fromJSON(needs.plan.outputs.plan).commit_sha }}
        token: ${{ steps.app-token.outputs.token }}
        persist-credentials: false
    - id: apply
      uses: Songmu/tagpr@v1
      with:
        mode: apply
        plan: ${{ needs.plan.outputs.plan }}
      env:
        GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

Create the release environment under the repository’s Settings → Environments page and configure its required reviewers. GitHub waits before starting apply, so environment secrets and the final job’s short-lived token are not used before approval. A deployment that remains unapproved for 30 days fails automatically .

Workflow-level concurrency is required for this layout. While a plan waits for approval, another release-branch push must not start a second plan invocation against the same unreleased range. With cancel-in-progress: false, the active approval run remains in progress and GitHub keeps at most one later run pending. For multiple tagpr configurations in a monorepo, include the config path or another stable release stream identifier in the concurrency group.

Applying a plan is retryable. If the tag was pushed successfully but GitHub Release creation failed, rerunning the final job accepts the tag when it already points to the plan’s commit_sha and retries the Release operation. A tag with the same name pointing to another commit is rejected.

Trigger a separate release workflow

To run the release flow in a workflow configured with on.push.tags:

on:
  push:
    tags:
    - "v*"

Supply tagpr with a token other than GITHUB_TOKEN so the tag can trigger that workflow. A personal access token works, but a short-lived GitHub App installation token created by actions/create-github-app-token is recommended.

The GitHub App must be installed on the repository with these permissions:

  • Contents: Read and write
  • Pull requests: Read and write
  • Issues: Read-only

Creating the App, installing it, and storing its credentials are covered by the actions/create-github-app-token documentation. Once configured, generate the token and use it for both checkout and tagpr:

- name: Generate token
  id: app-token
  uses: actions/create-github-app-token@v3
  with:
    client-id: ${{ secrets.CLIENT_ID }}
    private-key: ${{ secrets.PRIVATE_KEY }}
    permission-contents: write
    permission-pull-requests: write
    permission-issues: read

- uses: actions/checkout@v6
  with:
    token: ${{ steps.app-token.outputs.token }}
    persist-credentials: false

- uses: Songmu/tagpr@v1
  env:
    GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

Tag creation and release pull request updates performed with this token can trigger downstream workflows without the GITHUB_TOKEN restrictions.

The repository setting Allow GitHub Actions to create and approve pull requests controls GITHUB_TOKEN; GitHub App tokens are instead governed by the App’s permissions.

Keep the release recoverable

Regardless of which workflow layout you choose, make the release operation accept an explicit tag. This allows a failed build, publication, or deployment to be rerun or invoked manually without creating another release tag.

For example, keep the packaging and upload logic in a script or local composite action:

- name: Publish
  run: ./.github/scripts/publish "${{ inputs.tag }}"

Both the tagpr workflow and a recovery workflow can then call the same release operation.

Security considerations

  • Prefer a short-lived GitHub App installation token over a long-lived personal access token.
  • Grant only the permissions needed by tagpr and the release operation.
  • Keep persist-credentials: false on checkout so credentials are not retained in the local Git configuration.
  • Pin third-party actions according to your repository’s supply-chain policy.

For the action’s complete output reference, see the README .