📝

GitHub Actions + Release Please でリリースノートを自動作成する

2023/03/11に公開

GitHub

GitHub Actions

tech

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 のリリースノートの作成、パッケージ管理ツールの設定ファイル中のバージョン番号の更新など、リリース時の面倒な作業を自動化することを可能にする。コミットメッセージを 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 の設定ファイルを作成して、次のように設定する。

.github/workflows/release-please.yml

on:
  push:
    branches:
      - main

name: release-please
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - name: Generate GitHub Apps token
        id: generate_token
        uses: tibdex/github-app-token@v1
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.PRIVATE_KEY }}
      - uses: google-github-actions/release-please-action@v3
        with:
          token: ${{ steps.generate_token.outputs.token }}
          release-type: python
          package-name: practice-release-please-hamakou108

on: の部分では main ブランチに PR がマージされたときにワークフローがトリガーされるように設定している。

次に jobs: の部分では、最初のステップとして GitHub Apps トークンの生成を行っている。 GitHub Actions ではワークフロー実行開始時にワークフローで使用する GITHUB_TOKEN シークレットが自動で作成される ^[1]。後続の Release Please のステップで明示的にトークンを指定しなかった場合はこのトークンが使用されるが、この方法では PR 作成をトリガーにして起動する別のワークフローを設定していても、 Release Please によるリリース PR の作成時には実行されない ^[2] ^[3]。この workaround として GitHub Apps トークンを使用する方法があり、 tibdex/github-app-token@v1 アクションを使用してトークンを生成している。

なお GitHub Apps の設定方法は tmknom さんの記事に詳しい。今回の場合はリリース PR の作成に必要な権限を付与する必要があるため、 Apps の作成時に Permissions の部分で Contents と Pull Requests の書き込み権限を設定する。

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]

次のステップでは Release Please 公式から提供されている google-github-actions/release-please-action@v3 アクションを指定している。

-with: の部分で Release Please の動作をカスタマイズできる。 token には1つ前のステップで生成されたトークンを指定する。 release-type にはリポジトリ中で使用している言語やフレームワークに対応する種別値を指定している ^[4] 。パッケージ管理ツールの設定ファイルを特定し、ファイル中のバージョン番号を更新するために用いられる。

バージョン番号に 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 を含む際にパッチバージョンが更新されるようになる ^[5] 。

またバージョンを発番していないリポジトリの場合、デフォルトでは初期バージョンが 1.0.0 に設定されてしまう。例えば 0.1.0 から始めたい場合、コミットメッセージに Release-As: 0.1.0 が含まれる空のコミットを追加する ^[6] 。明示的にバージョン番号を指定したい場合も同様に行う。

$ git commit --allow-empty -m "chore: release 0.1.0" -m "Release-As: 0.1.0"

実行結果

Conventional Commits に従ったコミットメッセージを含む PR がマージされると、次のようなリリース PR が作成される。

この PR をマージすると、 CHANGELOG やバージョン番号が更新され、リリースノートが作成される。

脚注

Automatic token authentication - GitHub Docs ↩︎
create-pull-request/concepts-guidelines.md at main · peter-evans/create-pull-request ↩︎
逆に言うと Release Please による PR 作成トリガーで GitHub Actions が実行されなくても良い場合は GITHUB_TOKEN を使用すれば良い。ただしその場合も permissions キーを通して contents と pull-requests の書き込み権限を設定する必要がある。 ↩︎
googleapis/release-please: generate release PRs based on the conventionalcommits.org spec ↩︎
google-github-actions/release-please-action: automated releases based on conventional commits ↩︎
Add initial-version configuration option · Issue #683 · google-github-actions/release-please-action ↩︎