Automate your GitHub Releases with Release Please

The history of your code: Git tagging and releases

Git’s version control has become a gold standard in the tech industry, as no one would want to code without being able to collaborate and keep track of their changes. However, it is possible to go beyond simple commits using Git tags. These tags can be attributed to any commit in your repository, and act as aliases for them. The point is that you can more easily go back to a certain point in time by specifying a developer-friendly version number than a long hexadecimal string.

Not only is Git tagging really useful in a closed-source environment, but it is also crucial in open-source development. As more and more projects use a trunk-based Git flow, end users need to know at which point the provided code is considered ready for use. This is why GitHub, and other major Git platforms, allow developers to create releases.

As GitHub puts it, releases are software iterations meant for deployment and distribution, considered to be usable and not currently being developed. As an example, a release for version v1.3.0 of a project can differ from the v1.2.4 release because it includes new, tested features as well as some bug fixes, according to the Semantic Versioning (or SemVer) standard.

Releases are really useful for software deployment, however manually creating them can be tedious, and you would have to write your changelogs yourself. This is why Google created Release Please, a tool that automatically does all of this for you!

Automatic releases with Release Please

Release Please is a tool that creates “Release Pull Requests” which contain changelogs that are updated with your commits, provided that they follow the Conventional Commits specification (which has become somewhat of an industry standard). Your commits must have prefixes that describe their purpose.

The most important prefixes you should have in mind are:

• fix: which represents bug fixes and will result in a SemVer patch;
• feat: which represents a new feature and will result in a SemVer minor;
• feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.

As an example, a commit titled fix(auth): increase timeout duration will appear in your changelog as a bug fix, complete with a link to the corresponding commit.

As soon as you consider your code to be ready for a release, simply merge the PR, and you’re ready to go! Under the hood, Release Please does the following:

• updates your changelog file (for example CHANGELOG.md) along with other language-specific files (for example package.json);
• tags the commit with the new version number;
• creates a GitHub Release based on the tag.

Installing and using Release Please

Release Please can be installed as a GitHub Action. To do so in a Terraform project’s GitHub repo, simply create a workflow file such as .github/workflows/release-please.yml and paste the following code in it:

# .github/workflows/release-please.yml
name: release-please
on:
  push:
    branches:
      - main
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v3
        with:
          release-type: terraform-module # Multiple release types are supported
          default-branch: main

Release Please will then execute every time a commit is pushed to the main branch. Depending on your project’s programming language, you can define a different release type, such as helm, go, node, python...

As soon as this file is merged to the main branch, Release Please will start creating Release PRs, with the label “autorelease: pending”, and automatically updated version numbers and changelogs.

Merging one will create the corresponding release.

Congratulations, you’ve automated your GitHub releases! 🎉

While the Release Please GitHub action has good default configuration values, it can be further configured: as an example, you can set it to create its Release PRs as forks for public open-source projects. You can check out the full config on the GitHub Action’s repo.

Conclusion

Setting up Release Please in your GitHub repos is quite simple and allows you to easily create new releases, with great-looking changelogs and coherent version numbers. We’ve set up Release Please in most of our internal repos alongside Renovate, a tool that automatically upgrades package dependencies. However, while the latter works on many Git hosting services, the former only works on GitHub. If you work using GitLab, you might want to check out semantic-release 😉