How to Version a Custom Action With Tags and a Major Branch

Publish an exact tag per release and a moving major tag (v1) so consumers pin to a stable major line.

Cut a precise tag such as v1.2.0 for each release, then move a major tag v1 to that commit. Consumers reference @v1 and get compatible updates automatically.

Steps

• Tag the release commit with a full semver tag (v1.2.0).
• Force-update the major tag v1 to the same commit.
• Push both tags; consumers reference owner/action@v1.

Moving the major tag

git tag v1.2.0
git tag -f v1 v1.2.0
git push origin v1.2.0
git push origin -f v1

How consumers pin

steps:
  - uses: my-org/my-action@v1        # tracks the v1 major line
  - uses: my-org/my-action@v1.2.0    # pinned to an exact release

Gotchas

• Never move a full semver tag; only the major (v1) tag moves.
• Security-sensitive consumers pin by full SHA instead of any tag.

Related guides