😱 Beware the Release Please v4 Github Action!! 😱

My reaction when I ran discovered the release please v4 bug

The release please team has launched a v4 of their github action. This article will talk about how to integrate with the v4 version of the release please github action. There is a very nasty surprise in the upgrade from v3 to v4 that I will warn you about in the github workflow section below.

In my previous article I discussed the benefits of using this release please github action.

Improve your Github releases 10x with this one simple action

In a nut shell this release please action uses conventional commits to auto generate release documentation for you. It works great in mono and non-mono repos!

Setting up to v4

Using release please v4 is, in my opinion, slightly more complicated to configure but offers some benefits over the previous configuration in v3.

There are two configuration files you will want to create, release-please-config.json and a release-please-manifest.json to go along with your github action workflow.

Release Please Config

The release-please-config.json file is where you will register default options for all the packages that you want to create releases for in your repository and you will specify release details about each package. The docs outline all the options pretty well so I will just show a basic configuration file below one for a mono repo and one for a non-mono repo.

Mono repo

{
  "include-component-in-tag": true,
  "tag-separator": "@",
  "release-type": "node",
  "separate-pull-requests": true,
  "packages": {
    // In each section you can override options in the root of this JSON doc.
    // For example, if you deploy a python service you can add
    // "release-type": "python" and release please will know you are deploying
    // a python service.
    "./backend/svc1": {
      "package-name": "svc2"
    },
    "./path/to/svc2": {
      "package-name": "svc2"
    }
  }
}

Non-mono repo

{
  "release-type": "node",
  // This section is completely optional. If you don't specify a package name
  // the releases will be created without a name I.E v2.3.4
  // Personally I like always having a name to for the service.
  "tag-separator": "@",
  "include-component-in-tag": true,
  "packages": {
    ".": {
      "package-name": "cool-svc"
    }
  }
}

Release Please Manifest

The manifest file is where you define the version for the package. The main benefit for this is that release please will not have to search through github apis to determine the most recent version of your service.

This manifest will look the same if you are using a mono repo or a non-mono repo. I will show a file below that is for a mono repo and a non-mono repo.

Mono repo 👇

{
  // If you registered a package-name that will be the key to your services
  // version number
  "svc1": "2.1.0",
  "svc2": "3.0.2",
}

Non-mono repo 👇

{
  ".": "4.13.1"
}

Github workflow

Now that we have the two config files defined for release please we can run our release please github action.

Here is a simple workflow showing a serverless deploy for svc1 in our mono repo 👇

name: Service 1 Deploy
permissions:
  id-token: write
  contents: write
  pull-requests: write
env:
  RELEASE_PREFIX: 'chore(main): release'
on:
  push:
    branches: [main]
    paths:
      - "backend/svc1/**"
      - ".github/workflows/svc1-deploy.yml"
  workflow_dispatch:
    inputs:
      stage:
        description: 'Stage to deploy to - for example, "dev" or "prod"'
        required: true
        default: 'dev'      
defaults:
  run:
    working-directory: ./backend/svc1

jobs:
  deploy:
    name: Deploy service
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          cache: 'yarn'
          cache-dependency-path: |
            ./backend/svc1/yarn.lock

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111111111111:role/GithubActionsDeploymentRole
          aws-region: us-east-1

      - name: Install dependencies
        run: yarn install

      - name: Serverless deploy - ${{ github.event.inputs.stage == '' && 'dev' || github.event.inputs.stage }}
        if: ${{ !startsWith(github.event.head_commit.message, env.RELEASE_PREFIX) }}
        run: yarn deploy --stage=${{ github.event.inputs.stage == '' && 'dev' || github.event.inputs.stage }};

      - uses: google-github-actions/release-please-action@v4
        id: release

      - name: Configure Prod AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        if: ${{ steps.release.outputs.svc1--release_created }}
        with:
          role-to-assume: arn:aws:iam::222222222222:role/GithubActionsDeploymentRole
          aws-region: us-east-1

      - name: Serverless deploy - Production
        if: ${{ steps.release.outputs.svc1--release_created }}
        run: yarn deploy -s prod

The most important thing to take note of here is the release please section of the github action template

- uses: google-github-actions/release-please-action@v4
  id: release

and the if statement that checks if a release was created for our service.

if: ${{ steps.release.outputs.svc1--release_created }}

One very imporant note about v4. If you use either release_created or <path>--release_created from the output of the the release step in your github action you will be safe to use this for production deployments.

NEVER use the releases_created output from this the release please step.

If you are upgrading from v3 you would have been using the releases_created output and you should NEVER DO THIS!

Even though the README says releases_created is an option you should not use this.

The releases_created value will be set to true if there was a release created or not!!

I found out the issue with releases_created in both a mono repo and a non-mono repo the hard way where we had unexpected deploys to production.

Hopefull this issue is fixed in future version of release please but for now there is an open issue

`outputs.releases_created` has different behavior compared to v3 · Issue #912 ·…

If you stick to the Github workflow template I suggested you should be alright 😎

Let me know what you think or if there are other interesting release please configurations I should know about.