Release PleaseはリリースPRをどう組み立てるか、コミット規約から運用の詰まりまで読む

Release Pleaseが待機するリリースPR

Release Pleaseの中心は、デフォルトブランチへ変更が入るたびに即座にリリースすることではありません。git履歴からリリース可能な変更を拾い、更新され続けるリリースPRを作ります。担当者はPRの差分と生成されるリリースノートを確認し、準備が整った時点でそのPRをマージします。この流れなら、日々の開発とリリース確定の判断を分けられます。

リリースPRがマージされると、READMEに示される処理は三段階です。CHANGELOG.mdやpackage.jsonのような言語ごとのファイルを更新し、コミットへバージョン番号のタグを付け、そのタグを基にGitHub Releaseを作成します。パッケージマネージャーへの公開は扱わないため、npmなどへの配布を行うなら別の公開処理を組み合わせる必要があります。

featとfixがバージョン判断へつながる経路

Release PleaseはConventional Commitsの形式を前提にします。fix:はSemVerのパッチ、feat:はマイナーに対応し、feat!:やfix!:のように感嘆符を付けた変更は破壊的変更としてメジャー更新につながります。ここで大切なのは、本文の表現を人間が読めるかだけではなく、機械が同じ意味として解釈できるかです。

デフォルトブランチに前回リリース以降のreleasable unitがあれば、リリースPRを作る候補になります。READMEが挙げる基本の接頭辞はfeat、fix、depsです。choreやbuildは対象外で、JavaとPythonでは設定によりdocsも対象になります。チーム内で接頭辞を自由に増やすと、変更が履歴には残っていてもリリース候補として拾われない場合があるため、言語別設定と実際のコミット例を先に揃えるべきです。

スカッシュマージを推奨する理由

READMEはプルリクエストの統合方法としてスカッシュマージを強く推奨しています。線形の履歴では、コミットがマージ日順に並び、別のプルリクエストの変更が混ざりにくくなります。問題の導入箇所をgit bisectで探すときも、履歴の単位を追いやすくなります。

この推奨はリリースノートの制御にも関係します。開発中のテスト追加と修正を複数コミットに分けると、主ブランチには一時的にテストが通らない地点が生まれることがあります。プルリクエストを一つの変更として統合すれば、リリースノートに載せたい変更の境界を保ちやすくなります。通常のマージでもリリースPR自体は扱えますが、後述するコミットメッセージの上書きは、どのコミットへ適用するか判断できないため機能しません。

Release-Asとコミットメッセージの修正

通常の自動判定とは別に、コミット本文へRelease-As: x.x.xを追加して、指定したバージョンのリリースPRを開かせる方法があります。READMEの例では、空コミットの件名をchore: release 2.0.0とし、本文へRelease-As: 2.0.0を置きます。件名だけでバージョンを指定する設計ではない点に注意が必要です。

マージ済みプルリクエストのメッセージをリリースノート用に直したい場合は、PR本文を編集し、BEGIN_COMMIT_OVERRIDEからEND_COMMIT_OVERRIDEまでの範囲に新しいfeat、fix、choreなどのメッセージを書きます。次回の実行で、その範囲が元のマージ済みコミットメッセージの代わりに使われます。これは履歴を書き換える機能ではなく、生成されるノートに使う材料を指定する仕組みです。

PRが出ないときに見る三つの境界

リリースPRが作成されないとき、READMEの手順はまず変更の有無ではなく、リリース可能な単位の有無を確認します。前回のリリース以降にデフォルトブランチへ入ったコミットがfeat、fix、depsの形式になっているかを見ます。言語ごとの追加設定を使っているなら、docsなどの接頭辞もその設定と一致しているか確認します。

次に、古いPRへautorelease: pendingまたはautorelease: triggeredが残っていないか調べます。GitHub APIの障害などでラベルが消えず、Release Pleaseが前のリリースを保留中だと判断する場合があります。実際には公開済み、または取り下げたPRであれば、状態を確認した上で該当ラベルを削除します。最後に再実行します。GitHubアプリケーションではrelease-please:force-runラベル、Actionでは失敗したワークフローの再試行が案内されています。

エコシステム別設定を読む視点

Release Pleaseには複数のリポジトリ戦略が同梱されています。READMEに挙げられている対象には、Bazelモジュール、Dart、Elixir、Go、Helm、Java、Maven、Node、Expo、OCaml、PHP、Python、R、Ruby、Rust、SFDX、simple、Terraformモジュールがあります。各戦略は、プロジェクトのバージョン情報を置くファイルや生成対象を前提にします。

たとえばNodeはpackage.json、Dartはpubspec.yaml、Pythonはpyproject.tomlを見ます。Rustワークスペースではマニフェストを軸にしたリリースとcargo-workspaceプラグインが必要です。モノレポはマニフェスト設定を通じて扱い、細かな変更方法はcustomizing.mdやmanifest-releaser.mdへ分けて説明されています。READMEだけで全設定を決めるのではなく、採用する戦略の専用ドキュメントまで読んで、変更対象ファイルを明確にするのが安全です。

GitHub ActionとCLIの役割分担

READMEは推奨される実行方法としてGitHub Actionを挙げ、インストールと設定をrelease-please-actionリポジトリへ案内しています。リポジトリのイベントを契機に定期的な確認を行うなら、Actionはチームの既存CIに置きやすい選択肢です。一方、CLIも利用でき、docs/cli.mdに手順があります。ローカルで設定を試す、またはCIと異なる権限で検証する用途ではCLIの挙動を確認できます。

既存リポジトリへの導入では、マニフェスト設定のブートストラップが簡単な入口とされています。ただし、READMEは各オプションの詳細を一覧化していません。最初の候補PRで、CHANGELOG、言語固有のバージョンファイル、タグ名、GitHub Releaseの本文を一つずつ確認し、期待しない公開処理が動かないことも確かめる必要があります。

ランタイムとライセンスを採用判断に入れる

このプロジェクトはNode.jsのリリーススケジュールに合わせ、activeとmaintenanceのバージョンをサポートします。legacy-8のようなnpm dist-tagで古いランタイム向けの版も利用できますが、READMEではベストエフォート扱いです。レガシー版はCIでテストされず、セキュリティパッチが戻されない可能性があり、依存関係も更新されません。CIのNode.js版とRelease Pleaseの対応範囲を導入前に突き合わせてください。

プロジェクトはセマンティックバージョニングに従い、Apache 2.0でライセンスされています。READMEはGoogleの公式製品ではないことも明記しています。ライセンスの説明には著作権と特許に関する永続的、世界的、非独占的、ロイヤリティフリーの許諾がありますが、サポート、保証、セキュリティの提供を約束する記述はありません。自社のリリース責任をどこまで外部ツールへ預けるかは、ライセンス情報とは別に決める必要があります。

編集部の結論

Release Pleaseは、コミットの意味を一定の形式で残し、リリースPRを人が確認してからタグとGitHub Releaseへ進めたいチームに向きます。パッケージレジストリへの公開や複雑なブランチ管理まで任せる道具ではありません。導入前に、対象エコシステムの設定、コミット規約、スカッシュマージの運用、GitHub ActionsまたはCLIの実行権限を小さなリポジトリで確認してください。

採用判断では、機能追加、修正、破壊的変更、依存関係更新を表す履歴を用意し、feat、fix、deps、感嘆符付きの接頭辞が期待するSemVerの版上げへつながるかを確かめます。choreとbuildが候補外になること、JavaとPythonでは設定によりdocsが対象になり得ることも、実際の設定と照合します。PRが作られるかだけで終えず、CHANGELOGとpackage.jsonなどの言語固有ファイル、バージョンタグ、GitHub Releaseまで順に確認します。

運用上の判断も残してください。autorelease: pendingまたはautorelease: triggeredが古いPRに残った場合は、公開済みか保留中かを人間が確認してからラベルを扱います。指定版が必要なときはRelease-Asをコミット本文へ置き、リリースノートだけを直すときはBEGIN_COMMIT_OVERRIDEとEND_COMMIT_OVERRIDEの範囲を使います。通常のマージでは上書き機能が使えないため、READMEが推奨するスカッシュマージと整合させます。

READMEが詳しく扱っていない設定は、customizing.md、manifest-releaser.md、cli.mdなどの専用文書で補います。Node、Dart、Python、Rustでは版情報を置く場所や必要な設定が異なり、モノレポではマニフェストが軸になります。Googleの公式製品ではないこと、Apache 2.0であること、レガシーNode.js版がCIや依存関係更新を保証しないことも記録します。自動化の成果と残る責任を分けて管理できるチームなら、Release Pleaseを候補にできます。

検証順序も固定します。第一に、対象リポジトリの既定分岐、採用戦略、版管理対象を確定します。第二に、Conventional Commitsの接頭辞を持つ履歴を投入し、機能追加、修正、破壊的変更がどの版番号へ反映されるかを確認します。第三に、リリースPRの本文、CHANGELOG、package.json、pubspec.yaml、pyproject.toml、Rustマニフェストなど、対象戦略が扱う成果物を照合します。第四に、PR統合後のバージョンタグとGitHub Releaseを確認し、パッケージ公開が別工程であることを記録します。

変更履歴の確認では、同じプルリクエストに複数の試行修正を含めた場合の見え方を読みます。スカッシュマージなら、リリースノートへ載せる変更単位を一つへまとめやすく、git bisectで原因地点を追う履歴も整理しやすくなります。通常マージでもRelease PRは扱えますが、コミット上書きの対象を決められないため、BEGIN_COMMIT_OVERRIDEの利用条件が変わります。統合方法を開発者ごとに変えず、履歴規則として明文化します。

版番号の指定は自動判定と別の管理対象です。Release-Asはコミット本文に置く必要があり、件名へ版番号を書くだけではREADMEの例と一致しません。緊急版、指定版、通常版を同じ手順で処理しないなら、承認者、確認項目、再実行方法を分けます。マージ済みPRの説明をリリースノートへ反映する場合は、置換範囲をBEGIN_COMMIT_OVERRIDEからEND_COMMIT_OVERRIDEまでに限定し、元の履歴を変更する操作と混同しないようにします。

リリースPRが出ない場合は、最初からActionの失敗と決めつけません。前回リリース以降にreleasable unitがあるか、接頭辞が設定規則へ合っているか、古いPRにautorelease: pendingまたはautorelease: triggeredが残っていないかを順番に調べます。GitHub API障害でラベルが残った可能性と、実際に処理中のリリースがある可能性は別です。状態確認後にラベルを削除し、GitHubアプリケーションならrelease-please:force-run、Actionなら失敗ワークフロー再試行を使います。

エコシステム選択では、対応一覧の広さを実装保証と読み替えません。Nodeはpackage.json、Dartはpubspec.yaml、Pythonはpyproject.tomlを基準にし、Rustワークスペースはマニフェストとcargo-workspaceプラグインを必要とします。Bazel、Elixir、Go、Helm、Java、Maven、Expo、OCaml、PHP、R、Ruby、SFDX、simple、Terraformモジュールも対象として列挙されていますが、各戦略の設定文書を確認してから採用します。モノレポの版分離や変更対象はmanifest-releaser.md、細かな調整はcustomizing.mdで確認します。

実行環境では、GitHub ActionとCLIを同一視しません。Actionは推奨される導入経路ですが、実行条件、PR作成権限、タグ作成権限、GitHub Release作成権限が必要です。CLIはdocs/cli.mdの手順に従い、設定差分をローカルで確認する用途へ使えます。入力履歴、設定、Node.js版、実行権限のどれかが異なれば結果も変わり得るため、二つの経路を比較する場合は条件を記録します。

保守判断では、Node.jsのactive版とmaintenance版を優先し、legacy-8のようなnpm dist-tagを通常版と同じ前提で扱いません。レガシー版はCIで試験されず、セキュリティ修正のバックポート、依存関係更新が保証されない可能性があります。Apache 2.0の許諾には著作権と特許に関する範囲が示されていますが、サポート、保証、セキュリティ提供の約束とは別です。Release PleaseはGoogleの公式製品ではないため、障害対応、版確認、公開判断の責任を自社の手順へ残します。

結局のところ、このプロジェクトに任せる仕事は履歴解析、リリースPR維持、変更ファイル更新、タグ付け、GitHub Release作成です。任せない仕事はパッケージマネージャーへの公開、複雑な分岐管理、変更内容の最終説明、運用上の承認です。導入効果を測るときも、作業時間の削減だけでなく、版番号の誤り、CHANGELOGの欠落、保留ラベルの滞留、実行権限の不足が減ったかを確認します。これらを分離して評価できるチームなら、READMEの説明範囲に沿った採用判断ができます。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes