Validate Semantic Version Action

Ensure the given version complies with semantic versioning.

This action will validate the given version input and ensure that it complies with semantic versioning. If the action succeeds then the cleansed version and its separate components can be accessed through the acount outputs. The input can also be a git-ref which contains a version string, in this case it will be parsed out. See resolution strategy for more information.

Usage

The action can be used on its own or with an assigned id depending on the use case. When the given version is not valid the action will cause the workflow to halt with an error. Otherwise the version and its components are available through the action outputs.

- id: semver
  uses: matt-usurp/validate-semver@v3
  with:
    version: ${{ github.ref }} # refs/tags/v1.2.3

- run: |
    echo "v${{ steps.semver.outputs.version }}"
    echo "v${{ steps.semver.outputs.major }}"
    echo "v${{ steps.semver.outputs.minor }}"
    echo "v${{ steps.semver.outputs.patch }}"
    echo "v${{ steps.semver.outputs.prerelease }}"
    echo "v${{ steps.semver.outputs.build }}"

Inputs

You can configure the action with the following parameters:

Name	Type	Required	Description	Example
version	string	true	The version or git-ref	v2.3.4-dev+001

Outputs

The following outputs are available through steps.<id>.outputs when the action has completed successfully.

Name	Type	Description	Example
version	string	The full version without prefixes	2.3.4-dev+001
major	number	The major version number	2
minor	number	The minor version number	3
patch	number	The patch version number	4
prerelease	string	The prerelease version	dev
build	string	The build metadata	001

Tip

The version is coerced in to a semantic version as per the resolution strategy, therefore all outputs will be present assuming the action succeeds. The default values for number types is 0 and string types (such as prerelease and build) will be empty strings.

Resolution Strategy

The version parameter can be a version string with an optional v prefix which is stripped. All versions that are in a short-form are expanded to their full-form.

Input	Output
1 or v1	1.0.0
1.2 or v1.2	1.2.0
1.2.3 or v1.2.3	1.2.3

If you supply a git-ref then the version will be extracted before performing the above operation.

Input	Output
refs/tags/1 or refs/tags/v1	1.0.0
refs/tags/1.2 or refs/tags/v1.2	1.2.0
refs/tags/1.2.3 or refs/tags/v1.2.3	1.2.3

Action Versions

This action uses semantic versioning for its tagging and change management.

As with most actions, there is a major version branch that mimics the latest tag for that major version. This means its safe to target the v3 ref instead of a specific tag (e.g 3.0.1) if you want to receive bug fixes automatically. Breaking changes from this point will result in the creation of a new v4 branch and set of tags.

Tip

It is recommended to use v3 of this action.

Action	Node	Comment
matt-usurp/validate-semver@v3	node@24	Recommended
matt-usurp/validate-semver@v2	node@20	Archived
matt-usurp/validate-semver@v1	node@16	Archived