How-to setup a semi-automated release process with GitHub action/workflow

If you are a fan of conventional commits and want to semi-automate your release process then this recipe might help to get you started.

My goals were

• being able to generate changelog based on conventional commits
• being able to preview generated changelog and auto-determined version number
• being able to override version number for release in case I want to deviate from the auto-determined version number
• being able to decide when to release via a one-click action

By using the workflow_dispatch trigger event it is possible to start a workflow from GitHub directly.

workflow_dispatch:
  inputs:
    dryRun:
      description: 'Dry Run'
      required: true
      default: 'true'
    releaseVersion:
      description: 'Custom Version (major.minor.patch; leave empty for automatic determination)'
      required: false

By defining two input options it is possible to execute a dry run or actually create a release. If no custom version number is set then the version number gets calculated.

Here is an output of the workflow for a dry run.

You can find the source code of release.yml on https://github.com/MarcoEidinger/gh-workflow_dispatch-standard-version-recipe/blob/main/.github/workflows/release.yml and use it as inspiration.

But before you go ahead I’d like to point out specific implementation details so that you can avoid the following pitfalls:

Pitfall: no or not enough information in the changelog
Solution: set fetch-depth: 0 to ensure to fetch complete history during checkout

- name: Checkout Repo      
  uses: actions/checkout@v2
  with:
    fetch-depth: 0
    token: ${{ secrets.PAT }}

Pitfall: cannot push to a protected branch
Solution: make sure administrators are not included and use a personal access token with full repository authorization to fetch

Pitfall: GitHub shows on releases page no or incorrect “x commits to <branch>since this release” label
Solution: set commitish equal to the branch on which the commit with the tag resides

- name: Publish GitHub release
  uses: actions/create-release@v1.1.4
  env:
    GITHUB_TOKEN: ${{ secrets.PAT }}
  with:
    tag_name: ${{ env.NEXT_VERSION }}
    release_name: ${{ env.NEXT_VERSION }}
    commitish: main # set branch to avoid