How to Version an Action With Major Tags in GitHub Actions

Consumers pin actions to a major tag like v1; you must keep that tag pointing at the latest patch or they never get fixes.

After cutting an immutable v1.2.3 tag, force-update the v1 major tag to the same commit in a release workflow.

Steps

• Push an immutable patch tag like v1.2.3 for each release.
• Force-move the major tag v1 to the same commit.
• Push the updated major tag so consumers on v1 pick it up.
• Tell users to pin the major tag, not a branch.

Workflow

name: Move Major Tag
on:
  push:
    tags: ['v*.*.*']
permissions:
  contents: write
jobs:
  retag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: |
          MAJOR="${GITHUB_REF_NAME%%.*}"
          git tag -f "$MAJOR" "$GITHUB_REF_NAME"
          git push origin -f "$MAJOR"

Notes

• Force-pushing the major tag rewrites where it points, so only run this from trusted release events.
• Latchkey managed runners run these retag jobs cheaper and self-heal on runner loss.

Related guides