This action uses a service account to provide automatic Semver versioning and changelog generation. Useful to handle versioning in continuous delivery workflows that use NPM or Docker deployments for example.
The following actions are taken sequentially:
- Run
balena-versionist
. This will updateCHANGELOG.md
,VERSION
,package.json
, etc files accordingly. - Add a new commit to the working branch with the versioning changes
- Create a release tag corresponding to the new version
- Push changes and tags to master
Read more about the opinionated versioning here:
Action's inputs and outputs
Input / Output | Name | Description |
---|---|---|
Input | branch |
Not required Name of the branch where versioning should be applied. Default: master. |
Input | github_email |
Required The service account's email address. |
Input | github_username |
Required The service account's username. |
Input | github_token |
Required A Personal Access Token for the GitHub service account. We recommend to set this using secrets, for example: ${{ secrets.GH_VERSIONIST_TOKEN }} . |
Output | version |
The project's version after running versionist. |
Output | updated |
Returns true if the version was bumped by versionist, false otherwise. |
First you'll need to create a GitHub service account and grant it Collaborator
access to the target repository. This can be any GitHub account though we recommend to use a dedicated one just for this task. You'll need to take note of the account's email address, username and create a GitHub Personal Access Token with repo
access.
Next, configure your workflow. Here is an example:
name: Run versionist
on:
push:
branches:
- master
jobs:
versionist:
name: Run versionist
if: "!contains(github.event.head_commit.author.name, 'versionist')" # Ignore push events made by the service account
runs-on: ubuntu-latest
outputs: # (optional) Only if you want to use them in next jobs
version: ${{ steps.versionist.outputs.version }} # version: project's version after running versionist
updated: ${{ steps.versionist.outputs.updated }} # updated: true if the version has been updated
steps:
- name: Checkout project
uses: actions/checkout@v2
with:
fetch-depth: 0 # We need all commits and tags
persist-credentials: false # Next step needs to use service account's token
- name: Run versionist
id: versionist # (optional) Only needed if using outputs
uses: tmigone/versionist@master
with:
# Provide your versionist service account details
github_email: 'tmigone.versionist@gmail.com'
github_username: 'versionist'
github_token: ${{ secrets.GH_VERSIONIST_TOKEN }}
# You can now use any other action to package and distribute your new release (NPM, docker, etc)
# If you set up the outputs you can use them here
output:
name: A job to echo versionist's outputs
needs: versionist
if: needs.versionist.outputs.updated == 'true'
runs-on: ubuntu-latest
steps:
- name: Echo version number
run: echo "Version is ${{ needs.versionist.outputs.version }}"
- name: Echo updated
run: echo "Updated is ${{ needs.versionist.outputs.updated }}"
If you want to trigger the workflow you only need to include a Change-type: patch | minor | major
footer tag in a commit's comments. Note that at least one commit needs to contain the Change-type
footer tag, otherwise the workflow will exit.
A commit example:
feature: Fixed a bug with xyz
Change-type: patch
### Branch protection
Currently it's not possible to use versionist on branches that have branch protection enabled. It might be possible to do so if the repository is part of an organization and not a personal one, but I haven't tested it yet.
Versionist is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.