github-tag-action

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

Medium Post: Creating A GitHub Action to Tag Commits

📣 This project is seeking maintainers! 📣

Usage

Note: We don't recommend using the @master version unless you're happy to test the latest changes.

# example 1: on push to master
name: Bump version
on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-22.04
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: '0'

    - name: Bump version and push tag
      uses: anothrNick/github-tag-action@v1 # Don't use @master or @v1 unless you're happy to test the latest version
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # if you don't want to set write permissions use a PAT token

# example 2: on merge to master from pull request (recommended)
name: Bump version
on:
  pull_request:
    types:
      - closed
    branches:
      - master

jobs:
  build:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-22.04
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v4
      with:
        ref: ${{ github.event.pull_request.merge_commit_sha }}
        fetch-depth: '0'

    - name: Bump version and push tag
      uses: anothrNick/github-tag-action@v1 # Don't use @master or @v1 unless you're happy to test the latest version
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # if you don't want to set write permissions use a PAT token
        TAG_PREFIX: v
        PRERELEASE: true

Depending if you choose example 1 or example 2 is how crafted version bumps operate when reading the commit log.

Is recommended to use on pull_request instead of on commit to master/main.

NOTE: set the fetch-depth for actions/checkout@v2 or newer to be sure you retrieve all commits to look for the semver commit message.

Options

Environment Variables

• GITHUB_TOKEN (required) - Required for permission to tag the repo.
• DEFAULT_BUMP (optional) - Which type of bump to use when none explicitly provided (default: minor).
• DEFAULT_BRANCH (optional) - Overwrite the default branch its read from GitHub Runner env var but can be overwritten (default: $GITHUB_BASE_REF). Strongly recommended to set this var if using anything else than master or main as default branch otherwise in combination with history full will error.
• WITH_V (optional, deprecated) - Tag version with v character. Replaced by TAG_PREFIX
• RELEASE_BRANCHES (optional) - Comma separated list of branches (bash reg exp accepted) that will generate the release tags. Other branches and pull-requests generate versions postfixed with the commit hash and do not generate any tag. Examples: master or .* or release.*,hotfix.*,master ...
• CUSTOM_TAG (optional) - Set a custom tag, useful when generating tag based on f.ex FROM image in a docker image. Setting this tag will invalidate any other settings set!
• SOURCE (optional) - Operate on a relative path under $GITHUB_WORKSPACE.
• DRY_RUN (optional) - Determine the next version without tagging the branch. The workflow can use the outputs new_tag and tag in subsequent steps. Possible values are true and false (default).
• GIT_API_TAGGING (optional) - Set if using git cli or git api calls for tag push operations. Possible values are false and true (default).
• INITIAL_VERSION (optional) - Set initial version before bump. Default 0.0.0. MAKE SURE NOT TO USE vX.X.X here if combined TAG_PREFIX
• TAG_CONTEXT (optional) - Set the context of the previous tag. Possible values are repo (default) or branch.
• TAG_PREFIX (optional) - Prefix to add to the tag. eg v to create v0.0.0. This takes precidance over WITH_V
• PRERELEASE (optional) - Define if workflow runs in prerelease mode, false by default. Note this will be overwritten if using complex suffix release branches. Use it with checkout ref: ${{ github.sha }} for consistency see issue 266.
• PRERELEASE_SUFFIX (optional) - Suffix for your prerelease versions, beta by default. Note this will only be used if a prerelease branch.
• VERBOSE (optional) - Print git logs. For some projects these logs may be very large. Possible values are true (default) and false.
• MAJOR_STRING_TOKEN (optional) - Change the default #major commit message string tag.
• MINOR_STRING_TOKEN (optional) - Change the default #minor commit message string tag.
• PATCH_STRING_TOKEN (optional) - Change the default #patch commit message string tag.
• NONE_STRING_TOKEN (optional) - Change the default #none commit message string tag.
• BRANCH_HISTORY (optional) - Set the history of the branch for finding #bumps. Possible values last, full and compare defaults to compare.
  • full: attempt to show all history, does not work on rebase and squash due missing HEAD [should be deprecated in v2 is breaking many workflows]
  • last: show the single last commit
  • compare: show all commits since previous repo tag number
• FORCE_WITHOUT_CHANGES (optional) - Enforce the brach creation even if there are no changes from the tag.
• FORCE_WITHOUT_CHANGES_PRE (optional) - Similar to force without changes, for pre-releases.

Outputs

• new_tag - The value of the newly created tag.
• old_tag - The value of the last semantic version tag before the version bump. Empty if no version bump is performed.
• tag - The value of the latest tag after running this action.
• part - The part of version which was bumped.

Note: This action creates a lightweight tag.

Bumping

Manual Bumping: Any commit message that includes #major, #minor, #patch, or #none will trigger the respective version bump. If two or more are present, the highest-ranking one will take precedence. If #none is contained in the merge commit message, it will skip bumping regardless DEFAULT_BUMP.

Automatic Bumping: If no #major, #minor or #patch tag is contained in the merge commit message, it will bump whichever DEFAULT_BUMP is set to (which is minor by default). Disable this by setting DEFAULT_BUMP to none.

Note: This action will not bump the tag if the HEAD commit has already been tagged.

Workflow

• Add this action to your repo
• Commit some changes
• Either push to master or open a PR
• On push (or merge), the action will:
  • Get latest tag
  • Bump tag with minor version unless the merge commit message contains #major or #patch
  • Pushes tag to GitHub
  • If triggered on your repo's default branch (master or main if unchanged), the bump version will be a release tag. see issue 266.
  • If triggered on any other branch, a prerelease will be generated, depending on the bump, starting with *-<PRERELEASE_SUFFIX>.1, *-<PRERELEASE_SUFFIX>.2, ...
  • To create a repository release you need another workflow like automatic-releases.

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Credits

• fsaintjacques/semver-tool
• Contributors to this project

Projects using github-tag-action

Examples of projects using github-tag-action for reference.

• another/github-tag-action (uses itself to create tags)

• anothrNick/json-tree-service

  Access JSON structure with HTTP path parameters as keys/indices to the JSON.