What is release-please?

googleapis/release-please is a nifty piece of software that parses a repo’s commits since the last release, looking for Conventional Commits to generate the changelog and determine the next release version.

It then tracks the release’s changes in a PR. When the PR is merged, the commit is tagged with the version number and it creates a Github release.

How to set up release-please?

I’ll be using the googleapis/release-please-action github action.

Config

Add a release-please-config.json file to your repo, I usually put it in the .github/ folder, with the following content.

{
  "packages": {
    ".": {
      "release-type": "{{your release type}}"
    }
  },
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
}

By defaults release-please will write changes to the CHANGELOG.md file. To change it add a "changelog-path" property.

Make sure to swap use the appropriate release-type of your repo.

The full list of release-types is shown here

If there isn’t an appropriate release-type for your repo, you can always use simple and tell release-please where to update the version string by using the extra-files option paired with the x-release-please-version marker.

For the full list of configuration options, see the schema and the docs.

Example using extra-files and x-release-please-version marker.

Let’s assume we want to update the version string contained in the src/file_containing_version.lua file. We can add it to the extra-files property.

{
  "packages": {
    ".": {
      "release-type": "simple",
      "extra-files": ["src/file_containing_version.lua"]
    }
  },
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
}

And add the x-release-please-version marker in a comment on the line where the version string is in the src/file_containing_version.lua file.

local M = {}
M.version = "1.2.3" -- x-release-please-version

With this release-please will know where to update the version number when a release is made.

Manifest

release-please keeps track of the current version using a .release-please-manifest.json file. You’ll need to add one to your repo. Let’s add in the .github/ folder.

{
  ".": "{{your current version}}"
}

If you’re adding release-please to a fresh repo just use "0.0.0".

Workflow

The final step is to add the release-please-action to the repo’s CI/CD workflows.

The simplest way is just to add this workflow snippet.

on:
  push:
    branches:
      - main
permissions:
  contents: write
  pull-requests: write

name: release-please
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          config-file: .github/release-please-config.json
          manifest-file: .github/.release-please-manifest.json

If we want to run additional jobs when a release is made, say to publish the package to a package index, we can modify the workflow as follows:

on:
  push:
    branches:
      - main
permissions:
  contents: write
  pull-requests: write

name: release-please

jobs:
  release-please:
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        id: release
        with:
          config-file: .github/release-please-config.json
          manifest-file: .github/.release-please-manifest.json

  publish:
    needs:
      - release-please
    if: needs.release-please.outputs.release_created
    runs-on: ubuntu-latest
    steps:
      # ...