Skip to content

Latest commit

 

History

History
222 lines (180 loc) · 7.63 KB

README.md

File metadata and controls

222 lines (180 loc) · 7.63 KB

tag-version-commit GitHub Action

GitHub Action GitHub release (latest by date) GitHub Workflow Status codecov

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.