Version Increment ➕

Use 📄

Note

This action is confirmed to work on all three of GitHub's hosted runners - ubuntu-latest, macos-latest and windows-latest - at the point in time of the release of the action

Example ⌨️

      - name: Checkout code
        uses: actions/checkout@v4

      - name: Get next version
        uses: reecetech/[email protected]
        id: version
        with:
          scheme: semver
          increment: patch

      - name: Build image
        uses: docker/build-push-action@v2
        with:
          push: false
          tags: "example/application:${{ steps.version.outputs.version }}"
          context: .

API mode 🔗

Maybe you don't want to checkout your code in the job that calculates the version number. That's okay, you can use the API mode:

      - name: Get next version
        uses: reecetech/[email protected]
        id: version
        with:
          use_api: true

semver 🔖

This action will detect the current latest normal semantic version (semver) from the tags in a git repository. It will increment the version as directed (by default: +1 to the patch digit). Both the current latest and the incremented version are reported back as outputs.

Normal semantic versions are made up of a major, minor and patch digit. Normal versions do not include pre-release versions, or versions with build meta-data.

e.g. 1.2.7

See: https://semver.org/spec/v2.0.0.html

calver (semver compliant) 📅

Optionally, this action can provide semver compliant calendar versions (calver). In this calver scheme, the semver major, minor and patch digits map to year, month and release digits.

Note: to be semver compliant, digits must not have leading zeros.

e.g. 2021.6.2

semver	calver	example	note
major	year	2021
minor	month	6
patch	release	2	The nth release for the month

If the current latest normal version is not the current year and month, then the year and month digits will be set to the current year and month, and the release digit will be reset to 1.

Conventional Commits (semver with smarts) 💡

If you choose the conventional commits scheme, the action will parse the last commit message (usually the merge commit) to determine the increment type for a semver version.

The following increment types by keyword are supported:

• patch: build, chore, ci, docs, fix, perf, refactor, revert, style, test
• minor: feat
• major: any of the above keywords followed by a '!' character, or 'BREAKING CHANGE:' in commit body

If none of the keywords are detected, then the increment specified by the increment input will be used (defaults to patch).

Tip

You might like to enforce conventional commits in the title of your pull requests to ensure that the merge commit has the correct information. Something like this action might be handy: https://github.com/marketplace/actions/conventional-commit-in-pull-requests

Default branch vs. any other branch 🎋

Default branch

The action will return a normal version if it is detected that the current commit is on the default branch (usually main).

Examples:

• 1.2.7
• 2021.6.2

You may override the branch to consider the release branch if it is not the default branch, by providing a specific release branch name as an input. For example:

      - name: Get next version
        uses: reecetech/[email protected]
        id: version
        with:
          release_branch: publish

Any other branch

The action will return a pre-release version if any other branch is detected (e.g. new-feature, bugfix/foo, etc). The pre-release portion of the version number will be the literal string pre. followed by the git commit ID short reference SHA (trimmed of any leading zeros).

Examples:

• 1.2.7-pre.41218aa78
• 2021.6.2-pre.32fd19841

Inputs 📥

name	description	required	default
scheme	The versioning scheme in-use, either semver, calver or conventional_commits	No	semver
pep440	Set to true for PEP440 compatibility of pre-release versions by making use of the build metadata segment of semver, which maps to local version identifier in PEP440	No	false
increment	The digit to increment, either major, minor or patch, ignored if scheme == calver	No	patch
release_branch	Specify a non-default branch to use for the release tag (the one without -pre)	No
use_api	Use the GitHub API to discover current tags, which avoids the need for a git checkout, but requires curl and jq	No	false
tag_prefix	Prefix the tag with a string (defaults to empty string). e.g. if set to @org/product/ the action will filter by this prefix and return @org/product/1.2.3 in prefixed-version output	No

Outputs 📤

name	description
current-version	The current latest version detected from the git repositories tags
current-v-version	The current latest version detected from the git repositories tags, prefixed with a v character
version	The incremented version number (e.g. the next version)
v-version	The incremented version number (e.g. the next version), prefixed with a v character
major-version	Major number of the incremented version
minor-version	Minor number of the incremented version
patch-version	Patch number of the incremented version
pre-release-label	Pre-release label of the incremented version
major-v-version	Major number of the incremented version, prefixed with a v character
minor-v-version	Minor number of the incremented version, prefixed with a v character
patch-v-version	Patch number of the incremented version, prefixed with a v character
prefixed-version	Incremented version calculated, including a tag_prefix if specified
prefixed-v-version	Incremented version calculated, prefixed with a v charatcter, and also including a tag_prefix if specified

Contributing 💕

Please raise a pull request, but note the testing tools below

bats

BATS is used to test the logic of the shell scripts.

See: https://github.com/bats-core/bats-core

shellcheck

Shellcheck is used to lint our shell scripts.

Please use local ignores if you'd like to skip any particular checks.

See: https://github.com/koalaman/shellcheck