update-tags-action/README.md

update-tags-action

Easily create/update one or more Git tags in a GitHub repository.

Generally useful for moving major (v1) and minor (v1.2) tags to same commit as the latest v1.x.x tag.

This action uses itself to move its own major and minor tags.

Examples

Basic

- uses: jimeh/update-tags-action@v2
  with:
    tags: v2,v2.2

- uses: jimeh/update-tags-action@v2
  with:
    tags: |
      v2
      v2.2

Deriving Tags from Version

Automatically derive major and minor tags from a semver version string:

- uses: jimeh/update-tags-action@v2
  with:
    derive_from: v1.2.3
    # Creates tags: v1, v1.2

With a custom template (major tag only):

- uses: jimeh/update-tags-action@v2
  with:
    derive_from: v1.2.3
    derive_from_template: '{{prefix}}{{major}}'
    # Creates tag: v1

Combine derived tags with explicit tags:

- uses: jimeh/update-tags-action@v2
  with:
    derive_from: v1.2.3
    tags: latest
    # Creates tags: latest, v1, v1.2

With Release Please

This example uses jimeh/release-please-manifest-action, but you can just as easily use the official google-github-actions/release-please-action instead.

First you'll want the workflow setup to run on push:

on: [push]

Then you'll want a release-please job which only runs on pushes to your main branch, and exposes relevant outputs from release please:

jobs:
  # [...]
  release-please:
    runs-on: ubuntu-latest
    if: ${{ github.ref == 'refs/heads/main' }}
    outputs:
      release_created: ${{ steps.release-please.outputs.release_created }}
      tag_name: ${{ steps.release-please.outputs.tag_name }}
    permissions:
      contents: write
      issues: write
      pull-requests: write
    steps:
      - uses: jimeh/release-please-manifest-action@v3
        id: release-please

And finally a job to create MAJOR and MINOR release tags, which only runs when release-please reports having created a release:

jobs:
  # [...]
  release-tags:
    runs-on: ubuntu-latest
    needs: release-please
    if: ${{ needs.release-please.outputs.release_created }}
    permissions:
      contents: write
    steps:
      - uses: jimeh/update-tags-action@v2
        with:
          derive_from: ${{ needs.release-please.outputs.tag_name }}
          # Creates tags: v2, v2.2 (for tag_name v2.2.0)

Inputs

name	description	required	default
tags	List/CSV of tags to create/update.	false	""
derive_from	Semver version string to derive tags from (e.g., 'v1.2.3'). When provided, generates tags using derive_from_template input. Default template will produce major and minor tags. (e.g., 'v1', 'v1.2')	false	""
derive_from_template	Handlebars template for deriving tags from the derive_from input. CSV/newline-delimited list with placeholders: {{prefix}}, {{major}}, {{minor}}, {{patch}}, {{prerelease}}, {{build}}, {{version}}.	false	{{prefix}}{{major}},{{prefix}}{{major}}.{{minor}}
ref	The SHA or ref to tag. Defaults to SHA of current commit.	false	${{ github.sha }}
when_exists	What to do if the tag already exists. Must be one of 'update', 'skip', or 'fail'.	false	update
annotation	Optional annotation message for tags. If provided, creates annotated tags. If empty, creates lightweight tags.	false	""
dry_run	If true, logs planned operations without executing them.	false	false
github_token	The GitHub token to use for authentication.	false	${{ github.token }}

Derive Template Syntax

The derive_from_template input uses Handlebars for template rendering. Splitting the template into separate tags by comma or newline is done after the template is rendered.

Available placeholders:

Placeholder	Description
{{prefix}}	v or V if input had a prefix, empty otherwise
{{major}}	Major version number
{{minor}}	Minor version number
{{patch}}	Patch version number
{{prerelease}}	Prerelease identifier (e.g., beta.1), empty if none
{{build}}	Build metadata (e.g., build.123), empty if none
{{version}}	Full version string without prefix

Conditional Sections

Use Handlebars {{#if}} blocks to include content only when a variable has a value. This is useful for optional components like prerelease or build metadata:

- uses: jimeh/update-tags-action@v2
  with:
    # Creates tag: v1-beta.1
    derive_from: v1.2.3-beta.1
    derive_from_template: |
      {{prefix}}{{major}}{{#if prerelease}}-{{prerelease}}{{/if}}

For a stable release without prerelease:

- uses: jimeh/update-tags-action@v2
  with:
    # Creates tag: v1 (prerelease section omitted)
    derive_from: v1.2.3
    derive_from_template: |
      {{prefix}}{{major}}{{#if prerelease}}-{{prerelease}}{{/if}}

You can also use {{#unless}} for inverse logic:

- uses: jimeh/update-tags-action@v2
  with:
    # Creates tag: v1-stable (only for non-prerelease versions)
    derive_from: v1.2.3
    derive_from_template: |
      {{prefix}}{{major}}{{#unless prerelease}}-stable{{/unless}}

Outputs

name	description
tags	List of tags that were created/updated.
created	List of tags that were created.
updated	List of tags that were updated.
skipped	List of tags that were skipped.

Runs

This action is a node24 action.

License

MIT