versionist GitHub action

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 update CHANGELOG.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:

• versionist
• balena-versionist

Action's inputs and outputs

Example usage

GitHub Service account

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.

Configuring the workflow

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: '[email protected]'
        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 }}"

Tagging commits

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.

This action provides automatic Semver versioning and changelog generation. Useful to handle versioning in continuous delivery workflows that use NPM or Docker deployments.

The following actions are taken sequentially:

• Run balena-versionist. This will update CHANGELOG.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:

• versionist
• balena-versionist

Inputs

branch

Not required Name of the branch where versioning should be applied. Default: master.

github_email

Required The email address to be associated with the generated commits.

github_username

Required The username to be associated with the generated commits.

github_token

Required The GitHub token to authenticate. Automatically set by ${{ secrets.GITHUB_TOKEN }}. This is required to push the version update and tag.

Example usage

Here is a sample action workflow:

name: Run versionist
on:
  push:
    branches:
      - master

jobs:
  versionist:
    runs-on: ubuntu-latest
    steps: 
    - uses: actions/checkout@v1
    - uses: tmigone/versionist@master
      with:
        github_email: '[email protected]'
        github_username: 'Tomás Migone'
        github_token: ${{ secrets.GITHUB_TOKEN }}

You should include at least one commit with a Change-type: patch | minor | major footer tag in the comments, example:

feature: Fixed a bug with xyz

Change-type: patch

This action provides automatic Semver versioning, changelog generation and continuous delivery for NPM and docker projects.

The following actions are taken sequentially:

• Run balena-versionist. This will update CHANGELOG.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
• For node projects, publish package to NPM
• For docker projects, publish package to DockerHub

This action provides automatic versioning, changelog generation and npm publishing.

The following actions are taken sequentially:

• Run balena-versionist. This will update CHANGELOG.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
• For node packages, if an NPM auto token is provided: publish package to NPM