Improve your Github releases 10x with this one simple action

5 min readFeb 25, 2023

Release Please v4 has been released. This article is still relevant but you should checkout my updated article here 😎

https://danwakeem.medium.com/beware-the-release-please-v4-github-action-ee71ff9de151

What if I told you you could keep track of changes that are staged for production just by looking at the description of a PR?

Keeping track of changes ready for production in a PR

What if I told you that you could do this while only managing a single git branch? (trunk based development)

Managing only one branch for all dev and prod

In a mono repo (or not for the haters)

A CHANGELOG.md is generated uniquely for each service

Changelog auto generated for each service

Github releases are also generated with the most recent changes included in the description

Github releases are created when deploying to production

You get a raise and a slap on the ass for fine work keeping up with your Changelogs

Retire early and raise three beautiful children.

Retiring early and raising 3 beautiful children because of all the time you saved not writing CHANGELOGS

Okay maybe the last two are a little far fetched but you get the idea.

Release Please

The github action I am talking about is release-please. This is an action created by google that implements their release-please cli tool. The gist of how this tool works is easily explained by this flow chart 👇

The Release PR that gets created is really great because you don’t have to try and remember what changes are in dev or try and track them manually. You can simply view the PR that was created for the current release to discover changes.

As long as you tag your feature branch commits with conventional commit messages the changes will be reflected in your services CHANGELOG.md , Release PR, as well as the github release notes.

Example Github Actions Config

name: Deploy User Service

on:
  push:
    branches: [main]
    paths:
      - "backends/users/**"
      - ".github/workflows/users.deploy.yml"
  workflow_dispatch:
    inputs:
      stage:
        description: "Stage to deploy to - IE: dev / prod"
        required: true
        default: "prod"

permissions:
  contents: write
  pull-requests: write

defaults:
  run:
    working-directory: ./backends/users

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18.x'
          cache: 'yarn'
          cache-dependency-path: |
            **/yarn.lock
            **/package-lock.json
      - name: Deploy
        run: yarn deploy -s ${{ github.event.inputs.stage == '' && 'dev' || github.event.inputs.stage }}
      - uses: google-github-actions/release-please-action@v3
        id: release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          release-type: node
          path: backends/users
          monorepo-tags: true
          package-name: users
          tag-separator: '@'
      - name: Deploy Prod
        if: ${{ steps.release.outputs.releases_created }}
        run: yarn deploy -s prod

Conventional Commits

Conventional commits are fairly simple and they have pretty solid documentation on them already.

I will TL;DR the common ones here 👇

feat— This prefix will add a feature to your change log. Try adding an exclamation point to make it a breaking change. Ex. feat!
fix— This prefix will add a bug fix to your change log. Try adding an exclamation point to make it a breaking change. Ex. fix!
chore— This prefix is meant to be something that needed to be done but you don’t want to show up in your change log.

Gotchas

Here are a few things I found out while implementing this on my own.

My release PR is not getting created

You need to be sure to do two things.

First, include the contents and pull-request write permissions in your github action config.

Second, you need to make sure the settings > actions > general > Workflow permissions is set to read and write.

My release PR/release is not triggering other Github Actions

If you want the release PR or release itself to tigger other github actions you will need to use a personal access token instead of the default GITHUB_TOKEN in your workflow. By default the GITHUB_TOKEN will not trigger other actions.

I am hitting my github API limit

This can happen if you are applying this action to a repository that already has a large number of commits in it. To prevent this from happening use the following options.

bootstrap-sha This will let release-please know which commit sha to start its search for changes from. I would recommend just setting this to the most recent commit sha.
commit-search-depth This will limit the action to a specific commit search depth. The rate limit for the github API is 5000 requests an hour so 100 or 50 should be appropriate here.
release-search-depth This will limit the action to a specific release search depth. If you were not already doing releases this might not be necessary but it could be worth adding anyway. Same 50 or 100 limit should be fine here.

I forgot to tag my commit with a conventional prefix

To fix this you will just need to edit the commit message in the history so it contains the prefix. Once the prefix is added and your git action runs again your messages will be added to the release PR.

Here is a helpful stack overflow link showing how to edit your commit message if it isn’t the most recent commit. 😎

Hopefully you find this useful 😎 If so let me know how you like this action in the comments or if you know another great release tool I should check out also let me know in the comments. 🎸