This GitHub Action consists of two major components:
- Scan all commits in your Pull Request against the Conventional Commits standard
- Create GitHub Releases based on unreleased Conventional Commits
The following permissions need to be set in order to have full support of the Commisery Action:
| Permission | Level | Notes |
|---|---|---|
pull-requests |
read |
Needed for Pull Request validation and (optionally) when creating a GitHub Release |
contents |
write |
Required in order to create tags and/or GitHub Releases |
💡 Please refer to the GitHub documentation for the default permissions for your GitHub Token
The workflow, usually declared in .github/workflows/conventional-commit.yml, looks like:
name: Commisery
on:
pull_request:
jobs:
commit-message:
name: Conventional Commit compliance
runs-on: ubuntu-latest
steps:
- name: Check for compliance
uses: tomtom-international/commisery-action@v2
with:
token: ${{ github.token }}
validate-pull-request: true # OPTIONAL, default: `true`
validate-commits: true # OPTIONAL, default: `true`| Item | Mandatory | Description |
|---|---|---|
token |
YES | GitHub Token provided by GitHub, see Authenticating with the GITHUB_TOKEN |
validate-pull-request |
NO | Includes the Pull Request title and description as part of the Conventional Commit validation (DEFAULT: true) |
validate-pull-request-title-bump |
NO | Ensures that the Pull Request title's version bump level matches that of its commits (DEFAULT: true) |
validate-commits |
NO | Includes commits associated with the current Pull Request as part of the Conventional Commit validation (DEFAULT: true) |
config |
NO | Location of the Commisery configuration file (default: .commisery.yml) |
NOTE: This action will only function as part of the
pull_requesttrigger for workflows.
With the /bump GitHub Action, you can create a new Git tag or a GitHub release (also implicitly a Git tag),
based on the types of Conventional Commits since the latest found [Semantic Versioning]-compatible tag.
Breaking changes bump MAJOR, feats bump MINOR, and fixes bump PATCH.
You may also specify additional types that bump PATCH using the tags.<tag>.bump
configuration item.
Both the current and bumped versions are available as outputs. Optional inputs can be provided to enable automatic tag or release creation when a bump is performed. When running from a pull request event, tag/release creation is forcibly disabled, but the outputs are still available.
Filtering the Git version tags is also possible, by providing a version-prefix input. If set, only tags matching
exactly with the value of version-prefix shall be taken into account while determining and bumping versions.
As an example, for version tag componentX-1.2.3, the version prefix would be componentX-.
During initial development, you should avoid bumping the MAJOR version.
By default, we will bump the MINOR version for breaking changes in case:
- The current
MAJOR-version is0 - AND the
initial-developmentconfiguration parameter istrue(default value)
We will automatically bump the version to 1.0.0 when:
- The current
MAJOR-version is0 - AND the
initial-developmentconfiguration parameter isfalse
NOTE: This behavior also applies to non-bumping commits (ie.
chore:,ci:)
An example workflow that creates a release on every commit or merge to the main branch if necessary:
name: Bump version
on:
push:
branches: [ main ]
jobs:
bump-version:
name: Bump version and release
runs-on: ubuntu-latest
steps:
- name: Release version
id: release-version
uses: tomtom-international/commisery-action/bump@v1
with:
token: ${{ github.token }}
create-release: true # OPTIONAL, default: `false`
create-tag: false # OPTIONAL
build-metadata: upstream-10.0.10 # OPTIONAL
version-prefix: v # OPTIONAL
config: .commisery.yml # OPTIONAL
- run: echo "Current version is ${{steps.release-version.outputs.current-version}}"
- if: steps.release-version.outputs.next-version != ""
run: echo "Version bumped to ${{steps.release-version.outputs.next-version}}The GitHub release will be automatically populated with a changelog based on the released Conventional Commit messages, for example:
| Item | Mandatory | Description |
|---|---|---|
token |
YES | GitHub Token provided by GitHub, see Authenticating with the GITHUB_TOKEN |
create-release |
NO | Can optionally be set to true to create a GitHub release on version bump. |
create-tag |
NO | Can optionally be set to true to create a lightweight Git tag on version bump. |
build-metadata |
NO | Build metadata to add to the SemVer version on version bump. |
version-prefix |
NO | An optional prefix specifying the tags to consider, eg. v, componentX-, "". |
config |
NO | Location of the Commisery configuration file (default: .commisery.yml) |
💡 Note that setting both
create-releaseandcreate-tagtotrueis never needed, since a GitHub release implicitly creates a Git tag.
| Output | Description |
|---|---|
current-version |
The Semantic Version associated with the latest tag in the repository, stripped of any and all prefixes, or an empty string if the latest tag could not be parsed as a SemVer. |
next-version |
The next version (including the optionally provided version-prefix) as determined from the Conventional Commits, or empty string if a version bump was not performed |
You can configure commisery-action using a YAML-based configuration file, i.e.
max-subject-length: 120
tags:
docs: Documentation changes not part of the API
example:
description: Changes to example code in the repository
perf:
description: Performance improvements
bump: true
disable:
- C001
- C018
allowed-branches: "^ma(in|ster)$"
initial-development: false # OPTIONAL, defaults to `true`| Item | Default value | Description |
|---|---|---|
max-subject-length |
80 |
The maximum length of the subject of the commit message |
tags |
fix, feat, build, chore, ci, docs, perf, refactor, revert, style, test, improvement |
Specify a custom list of Conventional Commit types to allow. If provided, this will overwrite the default list, so be sure to include those if you want to retain them.tags takes a dict per type tag, with two values that can be set:
description; the bump will be false implicitly. NOTE: The type tags feat and fix will automatically be provided. |
disabled |
None |
List of rules to disable as part of the checker |
allowed-branches |
.* |
A regex specifying from which branch(es) releases and Git tags are allowed to be created |
initial-development |
true |
A boolean indicating that this project is still under initial development. During this state, any commit message containing a breaking change will result in a MINOR version bump. |
💡 By default
commisery-actionwill search for the file.commisery.yml. You can specify a different file with theconfiginput parameter.