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

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.

      description: 'Dry Run'
      required: true
      default: 'true'
      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 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
    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

And last but not least

  • 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
    GITHUB_TOKEN: ${{ secrets.PAT }}
    tag_name: ${{ env.NEXT_VERSION }}
    release_name: ${{ env.NEXT_VERSION }}
    commitish: main # set branch to avoid

Did you find this article valuable?

Support Marco Eidinger by becoming a sponsor. Any amount is appreciated!