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.
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: TriPSsemail@example.com 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"
You want to learn more about this topic?
You don't learn pure knowledge from books and it is not available in capsule form. The most effective form of exercise is still with sparring partners and a guide. Therefore, our "Commandemy" brand offers training for the IT experts of tomorrow.
Become the undisputed king of code and take a look at our current courses now!See current courses