GitHub Actions + Release Please でリリースノートを自動作成する
CHANGELOG やリリースノートの作成、バージョン更新を自動化してくれる Release Please を GitHub Actions を通して利用する方法について簡単に紹介する。
環境
- googleapis/release-please-action: v4
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 のリリースノートの作成、パッケージ管理の設定ファイル中のバージョン番号の更新など、リリース時の面倒な作業を自動化してくれる。コミットメッセージを 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 を作成するためにこの設定が必要だ。
Release Please の設定
Release Please の設定は以下2つのマニフェストファイルで記述される [1]。
ファイル名 | 概要 |
---|---|
release-please-config.json |
各パッケージのリリース設定(リリースタイプ、プラグイン、管理下にあるパッケージ個別の設定など)を定義する構成管理ファイル |
.release-please-manifest.json |
各パッケージの最新リリースバージョンを記録し、次回リリース時のバージョン判定の基準となる状態管理ファイル |
release-please-config.json
は例えば次のような内容になる。
{
"release-type": "python",
"include-component-in-tag": false,
"bump-minor-pre-major": true,
"bump-patch-for-minor-pre-major": true,
"packages": {
".": {}
}
}
release-type
には使用している言語やフレームワークに対応する種別値を指定する。
bump-minor-pre-major
と bump-patch-for-minor-pre-major
はメジャーバージョンが 0
の場合に有用だ。 bump-minor-pre-major
によって breaking changes を含む際にマイナーバージョンが更新され、 bump-patch-for-minor-pre-major
によって new feature を含む際にパッチバージョンが更新されるようになる。
.release-please-manifest.json
は次のような内容になる。
{
".": "0.3.7"
}
基本的には現在のバージョンが記録される。また一度もリリースをしていないタイミングで、初期バージョンを明示的に指定する場合にも利用される。
GitHub Actions の設定
GitHub Actions の設定ファイルを作成して、次のように設定する。
on:
push:
branches:
- main
name: release-please
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: actions/create-github-app-token@v1
id: app-token
with:
app-id: ${{ vars.APP_ID }}
private-key: ${{ secrets.PRIVATE_KEY }}
- uses: googleapis/release-please-action@v4
with:
token: ${{ steps.app-token.outputs.token }}
on:
の部分では main ブランチに PR がマージされたときにワークフローがトリガーされるように設定している。
jobs:
の部分では、 GitHub Apps トークンの生成と Release Please の実行を定義している。 Release Please の実行には公式から提供されている googleapis/release-please-action@v4
アクションを利用する。
GitHub Apps トークンの生成は Release Please のリリース PR 作成の用途では不要だが、実際上不便な点があるため定義している。 GitHub Actions ではワークフロー実行開始時に GITHUB_TOKEN
というデフォルトのシークレットが自動作成される [2]。このトークンを使って Release Please のリリース PR を作成可能だが、リリース PR の作成をトリガーにして別のワークフローを実行することができない [3]。これは意図しない再起的なワークフロー実行を防ぐための GitHub の仕様だが、リリース PR がマージされたらパッケージを公開するといったワークフローを組む場合にその妨げになってしまう。
この問題を回避するための方法の1つが適切な権限を持つ GitHub Apps トークンの生成だ。あらかじめ GitHub App を作成しておき、公式から提供されている create-github-app-token
アクションに app-id
と private-key
を渡せばトークンを生成できる。今回の場合はリリース PR の作成に必要な権限を付与する必要があるため、 Apps の作成時に Permissions の部分で Contents と Pull Requests の書き込み権限を設定する。
なお GitHub Apps の設定方法は tmknom さんの記事に詳しい。
実行結果
Conventional Commits に従ったコミットメッセージを含む PR がマージされると、次のようなリリース PR が作成される。
この PR をマージすると、 CHANGELOG やバージョン番号が更新され、リリースノートが作成される。
Discussion