GitHub Tag Action

A GitHub Action to automatically bump and tag master, on merge, with the latest SemVer formatted version. Works on any platform.

Requirements

This action runs on the Node.js 24 Actions runtime (runs.using: node24 in action.yml). GitHub-hosted runners have shipped with Node 24 since late 2025; self-hosted runners must be on runner version v2.328.0 or newer. The action is built as native ESM — the compiled lib/main.js entrypoint is an ES module, matching the package's "type": "module" declaration — so every dependency in the (@actions/*, @octokit/*, @semantic-release/*, conventional-changelog-conventionalcommits) graph loads cleanly with Node 24's native ESM loader. No additional setup is needed in consumer workflows — GitHub executes the bundled lib/main.js entrypoint directly.

Developing locally

• Install: npm ci (public registry.npmjs.org only; see .npmrc).
• Test: npm test (runs Vitest against the TS source).
• Watch tests: npm run test:watch.
• Lint: npm run lint (ESLint 9 flat config + typescript-eslint strict + stylistic).
• Format: npm run format / npm run check.
• Build: npm run build (emits native-ESM lib/*.js via tsc).

Usage

name: Bump version
on:
  push:
    branches:
      - master
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Bump version and push tag
        id: tag_version
        uses: StackAdapt/github-tag-action@v7.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Create a GitHub release
        uses: ncipollo/release-action@v1
        with:
          tag: ${{ steps.tag_version.outputs.new_tag }}
          name: Release ${{ steps.tag_version.outputs.new_tag }}
          body: ${{ steps.tag_version.outputs.changelog }}

📥 Inputs

• github_token (required) - Required for permission to tag the repo. Usually ${{ secrets.GITHUB_TOKEN }}.
• commit_sha (optional) - The commit SHA value to add the tag. If specified, it uses this value instead GITHUB_SHA. It could be useful when a previous step merged a branch into github.ref.

Fetch all tags

• fetch_all_tags (optional) - By default, this action fetch the last 100 tags from Github. Sometimes, this is not enough and using this action will fetch all tags recursively (default: false).

Filter branches

• release_branches (optional) - Comma separated list of branches (JavaScript regular expression accepted) that will generate release tags. On any other branch (and on pull requests) the action logs "Skipping the tag creation" and exits without tagging the repository — no commit-hash-postfixed versions are computed or emitted. Examples: master or .* or release.*,hotfix.*,master... (default: master,main).
• pre_release_branches (optional) - Comma separated list of branches (JavaScript regular expression accepted) that will generate the pre-release tags.

Customize the tag

• default_bump (optional) - Which type of bump to use when none is explicitly provided when commiting to a release branch (default: patch). You can also set false to avoid generating a new tag when none is explicitly provided. Can be patch, minor or major.
• default_prerelease_bump (optional) - Which type of bump to use when none is explicitly provided when commiting to a prerelease branch (default: prerelease). You can also set false to avoid generating a new tag when none is explicitly provided. Can be prerelease, prepatch, preminor or premajor.
• custom_tag (optional) - Custom tag name. If specified, it overrides bump settings.
• create_annotated_tag (optional) - Boolean to create an annotated rather than a lightweight one (default: false).
• tag_prefix (optional) - A prefix to the tag name (default: v).
• append_to_pre_release_tag (optional) - A suffix to the pre-release tag name (default: <branch>).

Customize the conventional commit messages & titles of changelog sections

• custom_release_rules (optional) - Comma separated list of release rules.

  Format: <keyword>:<release_type>:<changelog_section> where <changelog_section> is optional and will default to Angular's conventions.

  Examples:

  1. hotfix:patch,pre-feat:preminor,
  2. bug:patch:Bug Fixes,chore:patch:Chores

Debugging

• dry_run (optional) - Do not perform tagging, just calculate next version and changelog, then exit

📤 Outputs

• new_tag - The value of the newly calculated tag. Note that if there hasn't been any new commit, this will be undefined.
• new_version - The value of the newly created tag without the prefix. Note that if there hasn't been any new commit, this will be undefined.
• previous_tag - The value of the previous tag. When no tag exists yet, defaults to a synthetic {tag_prefix}0.0.0 (e.g. v0.0.0 with the default prefix). Note that if custom_tag is set, this will be undefined.
• previous_version - The value of the previous tag without the prefix (e.g. 0.0.0 when no tag exists yet). Note that if custom_tag is set, this will be undefined.
• release_type - The computed release type (major, minor, patch or custom - can be prefixed with pre).
• changelog - The conventional changelog since the previous tag.

Note: This action creates a lightweight tag by default.

Bumping

The action will parse the new commits since the last tag using the semantic-release conventions.

semantic-release uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number.

By default semantic-release uses Angular Commit Message Conventions.

Here is an example of the release type that will be done based on a commit messages:

Commit message	Release type
fix(pencil): stop graphite breaking when too much pressure applied	Patch Release
feat(pencil): add 'graphiteWidth' option	Minor Release
perf(pencil): remove graphiteWidth option BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons.	Major Release

If no commit message contains any information, then default_bump will be used.

Credits

anothrNick/github-tag-action - a similar action using a Dockerfile (hence not working on macOS)