Update Version Tags Action

• Inputs
  • Permissions
• Outputs
• Examples
  • Rolling Back
• Tags
• Badges
• Support
• Contributing

Update Version Tags on Push or Release for Semantic Versions or Custom Tags.

Zero configuration to maintain both major vN -> vN.x.x and minor vN.N -> vN.N.x tags.

This is useful if you want to automatically update additional tags, to point to your pushed/released tag. For example, many GitHub Actions maintain a vN and vN.N tag that points to the latest release of the vN.x.x branch.

- name: 'Update Tags'
  uses: cssnr/update-version-tags-action@v2

GitHub Actions can copy and paste this workflow: release.yaml

Make sure to review the Inputs and checkout more Examples.

Note

Please submit a Feature Request for new features or Open an Issue if you find any bugs.

Warning

This action no longer works on the master branch.
The latest tag is also being sunset very soon.
If you need a rolling tag use the @release branch.

Inputs

Input	Default Value	Description of Input Value
prefix	v	Tag Prefix for Semantic Versions
major	true	Update Major Tag vN
minor	true	Update Minor Tag vN.N
release	false	Update Release Tag vN.N.N
tags	-	Additional Tags to Update
sha	-	Override Target Sha
ref	-	Resolve Git Ref to Sha
tag	github.ref_name	Manually Set Target Tag
create	false	Create Target tag
force	false	Force Update Ref
summary	true	Add Summary to Job
dry_run	false	Will not Create/Update Tags, Output Only
token	github.token	For use with a PAT to Rollback

prefix

The prefix is applied to the generated version tags. If you release 1.0.0 or v1.0.0, the parsed major/minor is 1 and 1.0 and then with the prefix added becomes v1 and v1.0.

To disable the prefix, set it to an empty string prefix: ''

The prefix is not applied to the specified input tags.

Default: v

major/minor

Both major and minor versions are parsed from the release tag using semver. If you release version 1.0.0 this will update or create a reference for v1 and v1.0. If you are not using semantic versions, set both to false and provide your own tags.

Default: true

release

If true and you provide a non-release tag 1.2.3-release.1 this would create the release tag 1.2.3.

Default: false

tags

These are extra tags to set. For example, you could maintain a latest tag that always points to the latest release.

These can be a string list "v1,v1.0" or newline delimited.

👀 View Example tags

Extra Tag.

with:
  tags: latest

CSV with major/minor disabled.

with:
  tags: v1,v1.0,latest
  major: false
  minor: false

Newline with major/minor disabled.

with:
  tags: |
    v1
    v1.0
    latest
  major: false
  minor: false

---

To only set these tags set both major and minor to false.

Note the prefix is not applied to these tags...

sha

Override the target sha. If not provided, defaults to the sha that triggered the workflow.

This is useful if you want to manually specify a sha to point tags to.

ref

Resolve an arbitrary git ref to a sha and use it as the target. Overrides both sha and tag.

Accepts any ref such as heads/main, tags/v1, refs/heads/release, or refs/tags/v1.0.0. This is useful for pointing tags to the latest commit on a branch rather than looking up a tag.

tag

This is the target tag to parse the sha from. Defaults to the sha that triggered the workflow. To override this behavior you can specify a target tag here from which the target sha will be parsed. This is the sha that all parsed or provided tags are updated too. To create this tag at the current sha set create to true.

Rolling back requires a PAT. See Rolling Back for more details and a manual workflow example.

Default: ${{ github.ref_name }}

create

If true this will create the tag at the current sha of the workflow run.

Default: false

force

If true, will force the update of the ref. This is useful for non-fast-forward updates.

Default: false

summary

Write a Summary for the job. To disable this set to false.

👀 View Example Job Summary

---

Tag	v1.0.1
Sha	9b5d1797561610366c63dcd48b0764f4cdd91761
Tags	v1,v1.0

Tags

v1
v1.0

Results

Tag	Result
v1	Updated
v1.0	Updated

SemVer

{
  "options": {},
  "loose": false,
  "includePrerelease": false,
  "raw": "v1.0.1",
  "major": 1,
  "minor": 0,
  "patch": 1,
  "prerelease": [],
  "build": [],
  "version": "1.0.1"
}

Inputs

prefix: v
major: true
minor: true
tags: ""
tag: ""
summary: true
dry_run: false

---

Default: true

dry_run

If this is true no tags will be created/updated and will only output the results.

Default: false

token

GitHub workflow tokens do not allow for rolling back or deleting tags. To do this you must create a PAT with the repo and workflow permissions, add it to secrets, and use it. See Rolling Back for more information and an example.

For semantic versions, simply add this step to your release workflow:

- name: 'Update Tags'
  uses: cssnr/update-version-tags-action@v2

Default: ${{ github.token }}

Permissions

This action requires the following permissions:

permissions:
  contents: write

Permissions documentation for Workflows and Actions.

Outputs

Output	Output Description
tags	Comma Seperated String of Parsed Tags
semver	Parsed Semantic Version JSON
sha	SHA Used to Update Tags

Example output.

v1,v1.0

Using the outputs.

- name: 'Update Tags'
  uses: cssnr/update-version-tags-action@v2
  id: tags

- name: 'Echo Tags'
  run: |
    echo "tags: ${{ steps.tags.outputs.tags }}"
    echo "semver: ${{ steps.tags.outputs.semver }}"
    echo "sha: ${{ steps.tags.outputs.sha }}"

👀 View Example semver

{
  "options": {},
  "loose": false,
  "includePrerelease": false,
  "raw": "v1.0.1",
  "major": 1,
  "minor": 0,
  "patch": 1,
  "prerelease": [],
  "build": [],
  "version": "1.0.1"
}

---

Let us know if you need more output formats...

Examples

This is the workflow used by this Action to update tags on release: release.yaml

name: 'Release'

on:
  release:
    types: [published]

jobs:
  release:
    name: 'Release'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: write

    steps:
      - name: 'Update Tags'
        uses: cssnr/update-version-tags-action@v2

Specifying the tags to update or create:

- name: 'Update Tags'
  uses: cssnr/update-version-tags-action@v2
  with:
    major: false
    minor: false
    tags: |
      v1
      v1.0

Specifying the target tag to update too:

- name: 'Update Tags'
  uses: cssnr/update-version-tags-action@v2
  with:
    tag: v1.0.1

For more examples, you can check out other projects using this action:
https://github.com/cssnr/update-version-tags-action/network/dependents

Rolling Back

To roll back or manually update tags, copy this workflow: tags.yaml

To rollback tags you must use a PAT with the repo and workflow permissions. The target sha will be parsed from the target tag provided in the UI.

For example, if you releases v1.0.1 but wanted to roll back to v1.0.0. You would run the workflow with tag v1.0.0 it would update the v1 and v1.0 tags (or what ever tags you manually specify) to point back to the sha of tag v1.0.0.

This same workflow could be used to manually roll forward without a PAT.

name: 'Tags'

on:
  workflow_dispatch:
    inputs:
      tag:
        description: 'Target Tag'
        required: true

jobs:
  tags:
    name: 'Tags'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: write

    steps:
      - name: 'Update Tags'
        uses: cssnr/update-version-tags-action@v2
        with:
          tag: ${{ inputs.tag }}
          token: ${{ secrets.GH_PAT }}

Tags

The following rolling tags are maintained.

Version Tag	Rolling	Bugs	Feat.	Name	Target	Example
	✅	✅	✅	Major	vN.x.x	vN
	✅	✅	❌	Minor	vN.N.x	vN.N
	❌	❌	❌	Micro	vN.N.N	vN.N.N

You can view the release notes for each version on the releases page.

The Major tag is recommended. It is the most up-to-date and always backwards compatible. Breaking changes would result in a Major version bump. At a minimum you should use a Minor tag.

Badges

You can use shields.io to generate dynamic badges that always point to the latest tags for semantic versions.

Tag badges can be created here: https://shields.io/badges/git-hub-tag

Set sort to semver and filter to one of the following.

Version	Filter	Example Labels	Icons Only	For The Badge	Social Icons
Major	!v*.*
Minor	!v*.*.*
Micro

You may need to adjust the filter to match your tagging scheme.

To create a 2 color badge with icon and no text; set a labelColor with an empty label.

GitHub's media proxy caches images for 1 hour. You can purge the cache by sending a PURGE request.

curl -X PURGE 'https://camo.githubusercontent.com/xxx'

Support

If you run into any issues or need help getting started, please do one of the following:

• Report an Issue
• Q&A Discussion
• Request a Feature
• Chat with us on Discord

Contributing

If you would like to submit a PR, please review the CONTRIBUTING.md.

Please consider making a donation to support the development of this project and additional open source projects.

Additionally, you can support other GitHub Actions I have published:

• Stack Deploy Action
• Portainer Stack Deploy Action
• Docker Context Action
• AI Issue Action
• Actions Up Action
• Webstore Publish Action
• Rhysd Actionlint Action
• Zensical Action
• VirusTotal Action
• Homebrew Action
• Mirror Repository Action
• Update Version Tags Action
• Docker Tags Action
• TOML Action
• Update JSON Value Action
• JSON Key Value Check Action
• Parse Issue Form Action
• Cloudflare Purge Cache Action
• Mozilla Addon Update Action
• Package Changelog Action
• NPM Outdated Check Action
• Label Creator Action
• Algolia Crawler Action
• Create Pull Action
• Upload Release Action
• Check Build Action
• Web Request Action
• Get Commit Action

❔ Unpublished Actions

These actions are not published on the Marketplace, but may be useful.

• cssnr/create-files-action - Create various files from templates.
• cssnr/draft-release-action - Keep a draft release ready to publish.
• cssnr/env-json-action - Convert env file to json or vice versa.
• cssnr/push-artifacts-action - Sync files to a remote host with rsync.
• smashedr/update-release-notes-action - Update release notes.
• smashedr/combine-release-notes-action - Combine release notes.
• smashedr/openai-translate-action - OpenAI translate action.

---

📝 Template Actions

These are basic action templates that I use for creating new actions.

• javascript-action - JavaScript
• typescript-action - TypeScript
• py-test-action - Dockerfile Python
• test-action-uv - Dockerfile Python UV
• docker-test-action - Docker Image Python

Note: The docker-test-action builds, runs and pushes images to GitHub Container Registry.

---

For a full list of current projects visit: https://cssnr.github.io/