README.md

tag-version-commit GitHub Action

GitHub action for tagging commits whose title matches a version regex.

1. Overview
2. Usage
   1. Basic
   2. Typical
   3. Advanced
      1. Use a capture group
      2. Compare matched version with content of file(s)
      3. Use a version tag prefix
      4. Check entire commit message for matching version
      5. Check commit selected by another action
3. Inputs
4. Outputs
5. Contributing
6. License

Overview

Some projects maintain a version number somewhere in a file, e.g. __version__ = '1.2.3' for a Python project. When maintainers want to bump the version, they update that number, commit the change, and tag that commit. This action automates the tag creation.

When the commit that triggers a workflow has a title that matches a version regex (e.g. 1.2.3), this action creates a lightweight tag (e.g. 1.2.3) pointing to that commit. It is also possible to create an annotated tag using the commit body as the message. See inputs for more details.

Currently, it does not support checking any commit other than the last commit that was pushed. It also does not make sure that the tag does not exist before creating it, in which case the API request will simply fail and so will the action.

Usage

See action.yml.

Basic

- uses: christophebedard/tag-version-commit@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

Typical

Only consider commits pushed to master or releases/*.

name: 'tag'
on:
  push:
    branches:
      - master
      - 'releases/*'
jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: christophebedard/tag-version-commit@v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}

Advanced

Use a capture group

Use a capture group to allow including something other than the version itself in the commit title, e.g. Version: 1.2.3. This would create a 1.2.3 tag.

name: 'tag'
on:
  push:
    branches:
      - master
jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: christophebedard/tag-version-commit@v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        version_regex: 'Version: ([0-9]+\.[0-9]+\.[0-9]+)'

Compare matched version with content of file(s)

Compare the new version against the one declared in a package.json file. The action will fail and no tag will be created if the assertion command fails.

name: 'tag'
on:
  push:
    branches:
      - master
jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: christophebedard/tag-version-commit@v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        version_assertion_command: 'grep -q "\"version\": \"$version\"" package.json'

Use a version tag prefix

Use a prefix for the version tag, e.g. v. For example, this would create a v1.2.3 tag for a commit titled 1.2.3.

name: 'tag'
on:
  push:
    branches:
      - master
jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: christophebedard/tag-version-commit@v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        version_tag_prefix: 'v'

Check entire commit message for matching version

Check the entire commit message for a version matching the regex, and not just the commit title. For example, this would create a 1.2.3 tag for a commit message (body or title) containing Version: 1.2.3.

name: 'tag'
on:
  push:
    branches:
      - master
jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: christophebedard/tag-version-commit@v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        version_regex: 'Version: ([0-9]+\.[0-9]+\.[0-9]+)'
        check_entire_commit_message: true

Check commit selected by another action

Check a specific commit selected and output by another action. For example, if some/get-commit-action has a non-empty commit output, then that commit will be checked.

name: 'tag'
on:
  push:
    branches:
      - master
jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: some/get-commit-action@v1
      id: some-get-commit-action
    - uses: christophebedard/tag-version-commit@v1
      if: ${{ steps.some-get-commit-action.outputs.commit != '' }}
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        commit: ${{ steps.some-get-commit-action.outputs.commit }}

Inputs

Name	Description	Required	Default
token1	GitHub token, required for permission to create a tag	yes
version_regex	the version regex to use for detecting version in commit messages; can contain either 0 or 1 capture group2	no	'^[0-9]+\.[0-9]+\.[0-9]+$'
version_assertion_command3	a command to run to validate the version, e.g. compare against a version file	no	''
version_tag_prefix	a prefix to prepend to the detected version number to create the tag (e.g. "v")	no	''
commit	commit SHA to use, otherwise HEAD commit will be used	no	''
check_entire_commit_message	whether to check the entire commit message, not just the title, for a matching version	no	false
annotated	whether to create an annotated tag, using the commit body as the message	no	false
dry_run	do everything except actually create the tag	no	false

    1     if you want the tag creation/push to trigger an on.push.tags workflow, create a personal access token (with "repo" scope), add it as a secret, and use it here instead of the provided GITHUB_TOKEN, which will not trigger an on.push.tag workflow

    2     if there is more than 1 capture group, the action will fail

    3     use $version in the command and it will be replaced by the new version, without the prefix

Outputs

Name	Description	Default1
tag	the tag that has been created	''
message	the message of the annotated tag (if annotated) that has been created	''
commit	the commit hash that was tagged	''

    1     if no tag has been created (unless dry_run is enabled)

Contributing

See CONTRIBUTING.md.

License

See LICENSE.