Skip to content

Latest commit

 

History

History
308 lines (245 loc) · 14.9 KB

README.md

File metadata and controls

308 lines (245 loc) · 14.9 KB
Raw

action-semver status

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

  1. Install the dependencies

    $ npm install

  2. Build the package

    $ npm run all

  3. 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