ci: Configure release please

.github/workflows/build_publish.yml

@@ -1,7 +1,16 @@
 name: Build and publish
 
 on:
-  workflow_call: {}
+  workflow_call:
+    inputs:
+      ref:
+        description: Git ref to build (defaults to the ref that triggered the workflow)
+        type: string
+        default: ''
+      publish:
+        description: Publish the gem even when not triggered by a tag push
+        type: boolean
+        default: false
 
 jobs:
   build:
@@ -12,6 +21,8 @@ jobs:
       packages: read
     steps:
     - uses: actions/checkout@v4
+      with:
+        ref: ${{ inputs.ref }}
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
@@ -31,7 +42,7 @@ jobs:
   publish:
     name: Publish
     needs: build
-    if: github.ref_type == 'tag'
+    if: inputs.publish || github.ref_type == 'tag'
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
       - '**'
     tags:
       - '**'
+  # Allows the release-please workflow to run CI on the release PR branch:
+  # pushes made with GITHUB_TOKEN do not trigger workflows, but dispatches do.
+  workflow_dispatch: {}
 
 jobs:
   test:

.github/workflows/pr_title.yml

@@ -0,0 +1,25 @@
+name: PR title
+
+# release-please builds the changelog and picks the next version from
+# Conventional Commit messages, so PR titles (which become the squash-merge
+# commit message) must follow https://www.conventionalcommits.org/
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  conventional-title:
+    name: Conventional PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-please.yml

@@ -0,0 +1,82 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+jobs:
+  release-please:
+    name: Release Please
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      pr_branch: ${{ steps.release.outputs.pr && fromJSON(steps.release.outputs.pr).headBranchName || '' }}
+    steps:
+      - uses: googleapis/release-please-action@v5
+        id: release
+
+  # release-please bumps lib/rpi_auth/version.rb but does not fully update the
+  # lockfiles (it misses the CHECKSUMS entry and the Appraisal gemfiles), which
+  # makes `bundle install` fail in frozen mode. Re-lock them on the release PR.
+  update-lockfiles:
+    name: Update lockfiles on release PR
+    needs: release-please
+    if: needs.release-please.outputs.pr_branch != ''
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.pr_branch }}
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+
+      - name: Re-lock gemfiles
+        run: |
+          bundle lock
+          for gemfile in gemfiles/*.gemfile; do
+            BUNDLE_GEMFILE="${gemfile}" bundle lock
+          done
+
+      - name: Commit and push lockfiles
+        run: |
+          if git diff --quiet -- Gemfile.lock gemfiles/; then
+            echo "Lockfiles already up to date"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add Gemfile.lock gemfiles/*.gemfile.lock
+          git commit -m "chore: update lockfiles for release"
+          git push
+
+      # Pushes made with GITHUB_TOKEN don't trigger CI, so the required status
+      # checks would never report on the release PR. Dispatch CI explicitly so
+      # it runs against the final head commit of the release branch.
+      - name: Run CI on release PR
+        run: gh workflow run ci.yml --repo "${{ github.repository }}" --ref "${BRANCH}"
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BRANCH: ${{ needs.release-please.outputs.pr_branch }}
+
+  build_publish:
+    name: Build and publish
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    permissions:
+      contents: read
+      packages: write
+    uses: ./.github/workflows/build_publish.yml
+    with:
+      ref: ${{ needs.release-please.outputs.tag_name }}
+      publish: true

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "4.5.0"
+}

CHANGELOG.md

@@ -5,7 +5,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+From v4.6.0 onwards this file is maintained by
+[release-please](https://github.com/googleapis/release-please). Do not edit it
+by hand; see the "Releasing" section of the README.
 
 ## [v4.5.0]
 
@@ -184,7 +186,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - rails model concern to allow host app to add auth behaviour to a model
 - callback, logout and failure routes to handle auth
 
-[Unreleased]: https://github.com/RaspberryPiFoundation/rpi-auth/compare/v4.5.0...HEAD
 [v4.5.0]: https://github.com/RaspberryPiFoundation/rpi-auth/releases/tag/v4.5.0
 [v4.4.0]: https://github.com/RaspberryPiFoundation/rpi-auth/releases/tag/v4.4.0
 [v4.3.0]: https://github.com/RaspberryPiFoundation/rpi-auth/releases/tag/v4.3.0

README.md

@@ -324,17 +324,24 @@ After changing `Appraisals` or the gemspec dependencies, regenerate the gemfiles
 
 ## Releasing
 
-Ensure that the version number has been updated in: https://github.com/RaspberryPiFoundation/rpi-auth/blob/main/lib/rpi_auth/version.rb
+Releases are managed by [release-please](https://github.com/googleapis/release-please).
 
-Ensure that the changelog has been updated in: https://github.com/RaspberryPiFoundation/rpi-auth/blob/main/CHANGELOG.md
+PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/),
+because the squash-merge commit message is used to pick the next version and
+build the changelog:
 
-Create and push a new tag from `main`:
+* `fix: ...` produces a patch release.
+* `feat: ...` produces a minor release.
+* `feat!: ...`, or a `BREAKING CHANGE:` footer in the commit body, produces a major release.
+* Other types such as `chore:`, `ci:`, `docs:`, `test:` and `refactor:` do not trigger a release on their own.
 
-```
-git tag v1.2.2
-git push --tags
-```
+Do not edit `CHANGELOG.md` or `lib/rpi_auth/version.rb` by hand.
 
-Create a new release at: https://github.com/RaspberryPiFoundation/rpi-auth/releases/new
+When releasable commits land on `main`, release-please opens or updates a
+release PR. That PR bumps the version, updates the changelog and lockfiles. To
+release, review and merge the release PR. release-please then tags the merge
+commit (e.g. `v1.2.3`), creates a GitHub release, and the gem is built and
+published to GitHub Packages.
 
-Select the newly created tag, the target should be `main`, and the release name should be the same as the tag name eg. `v1.2.2`. Enter a short description of the release (generally best to copy / paste the changelog entry).
+To force a particular version, add a `Release-As: x.y.z` footer to a commit
+message on `main`.

release-please-config.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "include-component-in-tag": false,
+  "include-v-in-tag": true,
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "rpi_auth",
+      "version-file": "lib/rpi_auth/version.rb",
+      "changelog-path": "CHANGELOG.md"
+    }
+  }
+}