Zenn
📝

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

に公開
GitHub
GitHub Actions
tech

CHANGELOG やリリースノートの作成、バージョン更新を自動化してくれる Release Please を GitHub Actions を通して利用する方法について簡単に紹介する。

環境

  • googleapis/release-please-action: v4

Release please とは

https://github.com/googleapis/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 のマージをトリガーにしてリリースノートの追加やパッケージの公開を行うなど、リリースに関連する作業の多くを自動化できる。

以降は次のリポジトリの内容をベースに説明する。

https://github.com/hamakou108/practice-release-please

リポジトリの設定

リポジトリの 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-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 は次のような内容になる。

.release-please-manifest.json
{
  ".": "0.3.7"
}

基本的には現在のバージョンが記録される。また一度もリリースをしていないタイミングで、初期バージョンを明示的に指定する場合にも利用される。

GitHub Actions の設定

GitHub Actions の設定ファイルを作成して、次のように設定する。

.github/workflows/release-please.yml
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 アクションを利用する。

https://github.com/googleapis/release-please-action

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 が作成される。

https://github.com/hamakou108/practice-release-please/pull/71

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

https://github.com/hamakou108/practice-release-please/releases/tag/v0.3.7

脚注

  1. release-please/docs/manifest-releaser.md at main · googleapis/release-please ↩︎

  2. Automatic token authentication - GitHub Docs ↩︎

  3. Triggering a workflow - GitHub Docs ↩︎

Discussion