Changelog Automation with GitHub Actions

Changelog Automation with GitHub Actions

The connection between human emotions and the next version number of a project can lead to unwanted outcomes.

As developers, we are often faced with the usually very laborious and tedious task of writing changelogs with tags and dedicated version names that have been tagged in a code repository. Therefore, it is nice if we can automate such tasks.

This blog post is about Semantic Versioning and how using GitHub Actions can automate the process of writing changelogs.

This blog post has a close connection to a previous post with the title “Changelog Automation within Gitlab” and presents an example implementation of Semantic Versioning within GitHub.

How does it work?

The use of Semantic Versioning allows GitHub to automatically create changelogs based on commit messages. Of course this means that commit messages need to follow a certain format.

• fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
• feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
• BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.

GitHub example

In this example we are using the following GitHub Action to create changelogs.

name: Releases
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  changelog:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: conventional Changelog Action
        id: changelog
        uses: TriPSs/conventional-changelog-action@v3.7.1
        with:
          github-token: $
          # skip-version-file: 'true'

      - name: create release
        uses: actions/create-release@v1
        if: $
        env:
          GITHUB_TOKEN: $
        with:
          tag_name: $
          release_name: $
          body: $

Of course, it is possible to add a build phase to this pipeline that - for example, creates and pushes a new Docker image and writes the latest tag of the Docker image to the changelog.

When this pipeline runs successfully, it automatically creates a CHANGELOG.md and a package.json file if they do not already exist.

The automatic creation of files can be controlled by providing further parameters in the GitHub Action workflow. With these parameters it is possible, for example, to skip the creation of the package.json file by using skip-version-file: 'true'. For further details please refer to the official documentation.

If the implementation occurs after a tag with a version number has been added, you must manually edit the package.json file to match that version number, should the file exist.

If there is no Git tag associated with a previous version of the project, the first version will be 0.1.0, regardless of what the change is (fix, feat, BREAKING CHANGE).

Example commit messages

FIX: (e.g. v0.1.0 → v0.1.1)

git commit -m "fix: message"

FEAT: (e.g. v0.1.1 → v0.2.0)

git commit -m "feat: message"

BREAKING CHANGE: (e.g. v0.2.0 → v1.0.0)

git commit -m "feat: message" -m "BREAKING CHANGE: message"