GitHub Action for Consistent Versioning, Taging, and Labeleling of Builds

This GitHub Action creates consistent versioning, tagging, and labels for use in package/assembly versions and docker images.

Version automatic increment

All versions are stored inside of tags. After every commit inside of the main branch (you may override it by releasesBranch parameter) version is incremented acconding to conventional commit messages and saved into a new tag. There are some quick examples:

Commit	What happens to versioning
`feat(#task123): allow users to edit their profile`	Increment MINOR version
`fix: remove memory leak inside of WebController`	Increment PATCH version
`feat(#task123)!: rewrite user JSON representation in API`	Add MAJOR version (by adding `!` sign)
`fix: Remove wrong user name\nBREAKING CHANGE: Changed user name format`	Increment MAJOR version (by adding `BREAKING CHANGE:` somewhere inside of commit message. Note that in must be in uppercase and contain `:` without any spaces in between)
`Rename user profile classes`	If you do NOT follow the conventional commit messages then it will increment PATCH

NOTE: Tags are only created in main branch. So if you work in a separate branch it will NOT create any release until you merge the changes into main.

NOTE: If you want tags to be created on every build even if there is no any change detected from previous release then set forcePatchIncrementIfNoChanges: true parameter.

Versioning

Event	Ref	Commit SHA	Base Ver	Run #	`${{ ver_semVer }}`	`${{ ver_tag }}`
`schedule`			`1.2.3`	`99`	`1.2.3-prerelease.99+20200919T202359087Z`	`nightly`
`pull_request`	`refs/pull/2/merge`	`a123b570`	`1.2.3`	`99`	`1.2.3-prerelease.99+20200919T202359087Z.sha-a123b570`	`pr-2`
`push`	`refs/heads/<default_branch>`	`676cae2a`	`1.2.3`	`99`	`1.2.3-prerelease.99+20200919T202359087Z.sha-676cae2a`	`edge`
`push`	`refs/heads/dev`	`cf202579`	`1.2.3`	`99`	`1.2.3-prerelease.99+20200919T202359087Z.sha-cf202579`	`dev`
`push`	`refs/heads/my/branch`	`a5df6872`	`1.2.3`	`99`	`1.2.3-prerelease.99+20200919T202359087Z.sha-a5df6872`	`my/branch`
`push tag`	`refs/tags/v1.2.3`		`1.2.3`	`99`	`1.2.3+20200919T202359087Z.sha-a8cb3d0e`	`v1.2.3`
`push tag`	`refs/tags/v1.2.3-alpha.1`		`1.2.3`	`99`	`1.2.3-alpha.1+20200919T202359087Z.sha-a8cb3d0e`	`v1.2.3-alpha.1`

Docker Tags

Borrowed logic from the docker/build-push-action and Docker Tagging: Best practices for tagging and versioning docker images (both of which are worth reading), this action also produces docker tags and a push flag that are for use in a subsequent Docker build or push.

Event	Ref	Commit SHA	`${{ docker_tag }}`	`${{ docker_push }}`
`schedule`			`nightly`	true
`pull_request`	`refs/pull/2/merge`	`a123b57`	`pr-2`	false
`push`	`refs/heads/<default_branch>`	`676cae2`	`sha-676cae2`, `edge`	true
`push`	`refs/heads/dev`	`cf20257`	`sha-cf20257`, `dev`	true
`push`	`refs/heads/my/branch`	`a5df687`	`sha-a5df687`, `my-branch`	true
`push tag`	`refs/tags/v1.2.3`		`1.2.3`, `1.2`, `1`, `latest`	true
`push tag`	`refs/tags/v1.2.3-alpha.1`		`1.2.3-alpha.1`	true

NOTE: the latest docker tag is only added if the release repo tag is actually the highest SEMVER tag that exists for the repo. This ensures that a patch release of v1.2.3 will not steal the latest tag from v2.1.7. No latest docker tag is created for a pre-release repo tag.

Open Container Image Format Labels

This action also produces OCI Image Format Specification labels for use in a subsequent Docker build or push. These labels are produced from repository information and generated version information to provide, as an example, for this repository this action produces:

steps.vtl.outputs.oci_title="action-vtl"
steps.vtl.outputs.oci_description="GitHub Action for establishing a consistent semver"
steps.vtl.outputs.oci_url="https://github.com/mapped/action-vtl"
steps.vtl.outputs.oci_source="https://github.com/mapped/action-vtl.git"
steps.vtl.outputs.oci_version="1.2.3-prerelease.21+20200919T205832346Z.sha-caed088d"
steps.vtl.outputs.oci_created="2020-09-19T20:58:32.346Z"
steps.vtl.outputs.oci_revision="caed088d0624b0dcb22cdf31b70ff0daff4c10d1"
steps.vtl.outputs.oci_licenses="MIT"
steps.vtl.outputs.oci_labels="org.opencontainers.image.title=action-vtl
                org.opencontainers.image.description=GitHub Action for establishing a consistent semver
                org.opencontainers.image.url=https://github.com/mapped/action-vtl
                org.opencontainers.image.source=https://github.com/mapped/action-vtl.git
                org.opencontainers.image.version=1.2.3-prerelease.21+20200919T205832346Z.sha-caed088d
                org.opencontainers.image.created=2020-09-19T20:58:32.346Z
                org.opencontainers.image.revision=caed088d0624b0dcb22cdf31b70ff0daff4c10d1
                org.opencontainers.image.licenses=MIT"

(These outputs are not shown in the examples below for brevity)

Usage:

# For the latest version built in main branch
- uses: mapped/action-vtl@latest
  with:
    baseVersion: '1.2.3'

# For specific version (DEPRECATED, switched to latest branch. Use commit hash if you need to pin to a specific version)
- uses: mapped/action-vtl@v0.2.0
  with:
    baseVersion: '1.2.3'

# For testing the latest build from any branch
- uses: mapped/action-vtl@dev
  with:
    baseVersion: '1.2.3'

Inputs

The following inputs can be passed to this action as step.with keys:

Name	Type	Description
`baseVersion`	String	The base version of this repo. The first version of release. Applied if there is no any release yet. "v" prefix is optional.
`dockerImage`	String	The name of the docker image to produce tags for. If omitted, no docker tags will be produced. (default ``)
`gitHubToken`	String	The GITHUB_TOKEN value. Required to produce latest tags. (default ``)
`branchMappings`	List	Used for mapping untagged branches to tag names. Mappings are one per line, each as `branch:target_name`. (default `main:edge`)
`prereleasePrefix`	String	The prefix on an untagged run. (default `prerelease`)
`versionFile`	String	A filename where the full SEMVER and commit SHA will be written. Set to empty string if you do not want a version file to be created. (default `VERSION`)
`releasesBranch`	String	Branch where automatic releases should be created. Set to empty string to deactivate releases creation. (default `main`)
`forcePatchIncrementIfNoChanges`	String	Forces to increment patch if no changes were made since the last release. (default ``)
`dockerPlatformSuffix`	String	Adds a suffix to the docker tag to identify the platform that can be referenced by a composit manifest. (default ``)

Examples:

1. Release Tag Created

With the following input:

Action run# 23

Action YML:

- uses: mapped/action-version
  id: vtl
  with:
    baseVersion: '1.2.3'
    dockerImage: 'owner/container-name'
    gitHubToken: ${{ secrets.GITHUB_TOKEN }}
    branchMappings: |
      main:latest
    prereleasePrefix: 'prerelease'
    versionFile: 'VERSION'

Last commit in the tag: a8cb3d0eae1f1a064896493f4cf63dafc17bafcf
v1.3.5 release tag is created

This action will produce the following output variables:

steps.vtl.outputs.ver_major=1
steps.vtl.outputs.ver_minor=3
steps.vtl.outputs.ver_patch=5
steps.vtl.outputs.ver_preRelease=''
steps.vtl.outputs.ver_metadata='20200919T202359087Z.sha-a8cb3d0e'
steps.vtl.outputs.ver_buildNumber='23'
steps.vtl.outputs.ver_created='2020-09-19T20:23:59.087Z'
steps.vtl.outputs.ver_tag='v1.3.5'
steps.vtl.outputs.ver_semVer='1.3.5+20200919T202359087Z.sha-a8cb3d0e'
steps.vtl.outputs.ver_semVerNoMeta='1.3.5'

steps.vtl.outputs.docker_tags='owner/container-name:v1.3.5,owner/container-name:v1,owner/container-name:v1.3'
steps.vtl.outputs.docker_push='true'

and create a VERSION file with the contents:

1.3.5+20200919T202359087Z.sha-a8cb3d0e

Note that the 20200918T041126920Z portions are UTC datetime strings representing the time the action was run.

2a. Push to a Mapped Branch

With the following input:

Action run# 23

Action YML:

- uses: mapped/action-version
  id: vtl
  with:
    baseVersion: '1.2.3'
    dockerImage: 'owner/container-name'
    gitHubToken: ${{ secrets.GITHUB_TOKEN }}
    branchMappings: |
      main:latest
    prereleasePrefix: 'prerelease'
    versionFile: 'VERSION'

Push to main branch with a commit hash of a8cb3d0eae1f1a064896493f4cf63dafc17bafcf

This action will produce the following output variables:

steps.vtl.outputs.ver_major=1
steps.vtl.outputs.ver_minor=2
steps.vtl.outputs.ver_patch=3
steps.vtl.outputs.ver_preRelease='prerelease.23'
steps.vtl.outputs.ver_metadata='20200919T202219571Z.sha-a8cb3d0e'
steps.vtl.outputs.ver_buildNumber='23'
steps.vtl.outputs.ver_created='2020-09-19T20:22:19.571Z'
steps.vtl.outputs.ver_tag='edge'
steps.vtl.outputs.ver_semVer='1.2.3-prerelease.23+20200919T202219571Z.sha-a8cb3d0e'
steps.vtl.outputs.ver_semVerNoMeta='1.2.3-prerelease.23'
steps.vtl.outputs.ver_semVerNoMetaPyPA='1.2.3+prerelease.23'

steps.vtl.outputs.docker_tags='owner/container-name:edge,owner/container-name:sha-a8cb3d0e'
steps.vtl.outputs.docker_push='true'

and create a VERSION file with the contents:

1.2.3-prerelease.23+20200918T041126920Z.a8cb3d0e

2b. Push to an Unmapped Branch

With the following input:

Action run# 23

Action YML:

- uses: mapped/action-version
  id: vtl
  with:
    baseVersion: '1.2.3'
    dockerImage: 'owner/container-name'
    gitHubToken: ${{ secrets.GITHUB_TOKEN }}
    branchMappings: |
      main:latest
    prereleasePrefix: 'prerelease'
    versionFile: 'VERSION'

Push to my-working-branch branch with a commit hash of a8cb3d0eae1f1a064896493f4cf63dafc17bafcf

This action will produce the following output variables:

steps.vtl.outputs.ver_major=1
steps.vtl.outputs.ver_minor=2
steps.vtl.outputs.ver_patch=3
steps.vtl.outputs.ver_preRelease='prerelease.23'
steps.vtl.outputs.ver_metadata='20200919T201859527Z.sha-a8cb3d0e'
steps.vtl.outputs.ver_buildNumber='23'
steps.vtl.outputs.ver_created='2020-09-19T20:18:59.527Z'
steps.vtl.outputs.ver_tag='my-working-branch'
steps.vtl.outputs.ver_semVer='1.2.3-prerelease.23+20200919T201859527Z.sha-a8cb3d0e'
steps.vtl.outputs.ver_semVerNoMeta='1.2.3-prerelease.23'

steps.vtl.outputs.docker_tags='owner/container-name:my-working-branch,owner/container-name:sha-a8cb3d0e'
steps.vtl.outputs.docker_push='true'

and create a VERSION file with the contents:

1.2.3-prerelease.23+20200918T041126920Z.a8cb3d0e

3. Pull Request

With the following input:

Action run# 23

Action YML:

- uses: mapped/action-version
  id: vtl
  with:
    baseVersion: '1.2.3'
    dockerImage: 'owner/container-name'
    gitHubToken: ${{ secrets.GITHUB_TOKEN }}
    branchMappings: |
      main:latest
    prereleasePrefix: 'prerelease'
    versionFile: 'VERSION'

Pull Request with a head commit hash of a8cb3d0eae1f1a064896493f4cf63dafc17bafcf

This action will produce the following output variables:

steps.vtl.outputs.ver_major=1
steps.vtl.outputs.ver_minor=2
steps.vtl.outputs.ver_patch=3
steps.vtl.outputs.ver_preRelease='prerelease.23'
steps.vtl.outputs.ver_metadata='20200919T201457882Z.sha-a8cb3d0e'
steps.vtl.outputs.ver_buildNumber='23'
steps.vtl.outputs.ver_created='2020-09-19T20:14:57.882Z'
steps.vtl.outputs.ver_tag='pr-37'
steps.vtl.outputs.ver_semVer='1.2.3-prerelease.17+20200919T201457882Z.sha-a8cb3d0e'
steps.vtl.outputs.ver_semVerNoMeta='1.2.3-prerelease.23'

steps.vtl.outputs.docker_tags='owner/container-name:pr-37'
steps.vtl.outputs.docker_push='false'

and create a VERSION file with the contents:

1.2.3-prerelease.23+20200918T041126920Z.a8cb3d0e

Building / Testing / Contributing

Install the dependencies
```
$ npm install
```
Build the package
```
$ npm run all
```
Commit to the repo and it will automatically publish to latest (if you pushed to main) or dev-<your-branch> (if you are outside of main) branch

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github		.github
.vscode		.vscode
__tests__		__tests__
src		src
test		test
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

GitHub Action for Consistent Versioning, Taging, and Labeleling of Builds

Version automatic increment

Versioning

Docker Tags

Open Container Image Format Labels

Usage:

Inputs

Examples:

1. Release Tag Created

2a. Push to a Mapped Branch

2b. Push to an Unmapped Branch

3. Pull Request

Building / Testing / Contributing

About

Releases

Contributors 5

Languages

License

mapped/action-vtl

Folders and files

Latest commit

History

Repository files navigation

GitHub Action for Consistent Versioning, Taging, and Labeleling of Builds

Version automatic increment

Versioning

Docker Tags

Open Container Image Format Labels

Usage:

Inputs

Examples:

1. Release Tag Created

2a. Push to a Mapped Branch

2b. Push to an Unmapped Branch

3. Pull Request

Building / Testing / Contributing

About

Resources

License

Stars

Watchers

Forks

Releases

Contributors 5

Languages