GitHub Actions + Release Please でリリースノートを自動作成する
CHANGELOG やリリースノートの作成、バージョン更新を自動化してくれる Release Please を GitHub Actions から利用する機会があったので、使い方について簡単に紹介する。
環境
- google-github-actions/release-please-action: v3
Release please とは
Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects.
It does so by parsing your git history, looking for Conventional Commit messages, and creating release PRs.
Release Please は CHANGELOG の生成、 GitHub のリリースノートの作成、パッケージ管理ツールの設定ファイル中のバージョン番号の更新など、 Release 時の面倒な作業を自動化するためのツール。コミットメッセージを Conventional Commit の記法に沿って記述しておくと、前回のバージョン更新から最新のコミットまでの変更差分を CHANGELOG やリリースノートに出力することができる。
例えば次のようなコミット履歴があったとする。
* 2109bbc feat!: change baz
* e9d79ae fix: fix bar
* deadbee feat: add foo
この場合は次のような内容が出力される。
## [2.0.0](https://github.com/{user}/{repo}/compare/v1.0.0...v2.0.0) (2023-03-11)
### ⚠️ BREAKING CHANGES
* change baz ([#13](https://github.com/{user}/{repo}/issues/13))
### Features
* change baz ([#13](https://github.com/{user}/{repo}/issues/13)) ([2109bbc](https://github.com/{user}/{repo}/commit/2109bbcef209a8465856153f720ca5978c7ca20b))
* add foo ([#11](https://github.com/{user}/{repo}/issues/11)) ([deadbee](https://github.com/{user}/{repo}/commit/deadbeefcafef00d0000faceb00cabad1dea1dea))
### Bug Fixes
* fix bar ([#12](https://github.com/{user}/{repo}/issues/12)) ([e9d79ae](https://github.com/{user}/{repo}/commit/e9d79aef2650b650c6ec8e80edc8fc202b6b78a0))
GitHub Actions から Release Please を実行する
GitHub Actions から Release Please を実行するとより便利に利用できる。 PR のマージをトリガーにすることで、リリース PR の逐次的な更新や、リリース PR がマージされた際のリリースノートの自動作成などを実現できる。
なお以降は次のリポジトリの内容をベースに説明する。
リポジトリの設定
リポジトリの Settings タブを開き、サイドメニューの Actions > General から Allow GitHub Actions to create and approve pull requests にチェックを入れる。リリース PR を作成するためにこの設定が必要。
GitHub Actions の設定
適当な GitHub Actions の設定ファイルを作成して、次のように設定する。
on:
push:
branches:
- main
permissions:
contents: write
pull-requests: write
name: release-please
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: google-github-actions/release-please-action@v3
with:
release-type: python
package-name: practice-release-please-hamakou108
on: の部分では main ブランチに PR がマージされたときにワークフローがトリガーされるように設定している。
permission: の部分では contents と pull-requests の書き込み権限を設定している。 GitHub Actions ではワークフロー実行開始時にワークフローで使用する GITHUB_TOKEN シークレットが自動で作成される [1] 。シークレットにデフォルトで与えられている権限ではリリース PR の作成などを実行できないため、権限を追加する必要がある。
GitHub Actions のジョブに実際に付与された permissions を確認する方法
GitHub Actions のジョブに実際に付与された permissions はジョブの実行ログから確認できる。リポジトリの Actions タブを開き、 permissions を確認したいワークフロー、そしてジョブを開き、右上の歯車マークのメニュー中の View raw logs から実行ログを確認する。実行ログには次のように permissions が表示される。ちなみに Metadata の読み取り権限は設定しなくても自動的に付与される。
2023-03-07T22:48:34.7778787Z ##[group]GITHUB_TOKEN Permissions
2023-03-07T22:48:34.7779406Z Contents: write
2023-03-07T22:48:34.7779837Z Metadata: read
2023-03-07T22:48:34.7780426Z PullRequests: write
2023-03-07T22:48:34.7780842Z ##[endgroup]
最後に jobs: の部分では Release Please 公式から提供されている google-github-actions/release-please-action@v3 アクションを指定している。
-with: の部分で Release Please の動作をカスタマイズできる。 release-type にはリポジトリ中で使用している言語やフレームワークに対応する種別値を指定している [2] 。パッケージ管理ツールの設定ファイルを特定し、ファイル中のバージョン番号を更新するために用いられる。
バージョン番号に 0.x.x を用いる場合
次のように設定を追加する。
with:
release-type: python
package-name: practice-release-please-hamakou108
bump-minor-pre-major: true
bump-patch-for-minor-pre-major: true
bump-minor-pre-major: true によって breaking changes を含む際にマイナーバージョンが更新され、 bump-patch-for-minor-pre-major によって new feature を含む際にパッチバージョンが更新されるようになる [3] 。
またバージョンを発番していないリポジトリの場合、デフォルトでは初期バージョンが 1.0.0 に設定されてしまう。例えば 0.1.0 から始めたい場合、コミットメッセージに Release-As: 0.1.0 が含まれる空のコミットを追加する [4] 。明示的にバージョン番号を指定したい場合も同様に行う。
$ git commit --allow-empty -m "chore: release 0.1.0" -m "Release-As: 0.1.0"
実行結果
Conventional Commits に従ったコミットメッセージを含む PR がマージされると、次のようなリリース PR が作成される。
この PR をマージすると、 CHANGELOG やバージョン番号が更新され、リリースノートが作成される。
Discussion