コンテンツへスキップ

GitHubのマージキュー: セットアップ、ワークフロー、注意点

最終更新日

多くの人が一日中mainにマージするチームでは、昨日のmainに対してCIを通過したPRが、今日のmainでは壊れることがあります。マージキューは、各PRを先行するPRと組み合わせてテストし、その組み合わせた結果が通過した場合にのみマージすることでこの問題を解決します。本ガイドでは、その仕組み、セットアップ方法、そして必要となるCIの変更点について説明します。

解決する問題

ブランチ保護では、マージ前にPRを「最新の状態」にすることを要求できます。これは安全ですが、誰かがマージするたびに全員がブランチを更新し、CIを再実行する必要があります。これはチームの規模が大きくなるほど悪化する競合状態です。このルールがない場合、単独ではそれぞれ成功する2つのPRが、組み合わさると main を壊すことがあります。例えば、別々のファイルで同じ関数のシグネチャを変更する2つの変更がこれにあたります。

キューの仕組み

  1. 開発者が「準備ができたらマージ」をクリックします(またはPRをキューに追加します)。
  2. GitHubは、ベースブランチ、キュー内で前にあるPR、そしてこのPRを含む一時ブランチを作成します。ブランチ名は gh-readonly-queue/main/pr-123-<sha> のような形式です。
  3. そのブランチに対して merge_group イベントでワークフローを起動します。
  4. 必須チェックが成功すると、PRがマージされます。失敗した場合は、そのPRがキューから除外され、後ろにあるPRはそれを除いて再構築されます。

開発者は従来どおりPRのチェックを実行します。キューは、組み合わさった結果に対して2つ目の最終チェックを追加します。

提供状況: GitHubのドキュメントによると、マージキューは組織が所有するパブリックリポジトリ、およびGitHub Enterprise Cloudのプライベートリポジトリで利用できます。計画を立てる前に、ドキュメントで現在のプラン要件を確認してください。

ステップ1: ワークフローを merge_group で実行する

これは多くのチームが見落とす手順です。キューで必要とされるステータスチェックは、ワークフローが merge_group でトリガーされている場合にのみ報告されます。そうでない場合、キューのPRは実行されないチェックを待ち続けます。

on:
  pull_request:
  merge_group:
    types: [checks_requested]

必須チェックを提供するすべてのワークフローに、このトリガーが必要です。lintや tests-passed のサマリージョブなどの軽量なものも含まれます。paths フィルターには注意してください。必須チェックがパスフィルターでスキップされた場合でも、キューはそのチェックが報告されるのを待ち続けます。まずはトラフィックの少ないブランチでテストしてください。

また、actions/checkout も確認してください。merge_group の実行では、github.sha は一時ブランチのマージコミットになるため、デフォルトのチェックアウトで正しいコードが取得されます。github.event.pull_request が存在することを前提とするステップは避けてください。merge_group では存在しません。影響範囲のビルドなど、差分に基づくロジックでは、github.event.merge_group.base_sha と比較してください。

ステップ2: ルールセットまたはブランチ保護で有効にする

リポジトリの設定で、ルール(ルールセット)またはブランチ(ブランチ保護)を開き、デフォルトブランチに対して「マージキューを要求する」を有効にし、次のオプションを選択します。

設定機能一般的な選択
マージ方法キュー内のPRのマージ、スカッシュ、リベースの方法履歴に合わせてスカッシュ
ビルドの同時実行数一度にテストされるキューエントリの数3~5
最小グループサイズまとめてマージする最小のバッチ1
最大グループサイズ一度にマージする最大のバッチ活発なリポジトリでは3~5
最小数に達するまでの待機時間グループが埋まるまでの待機時間5分以下
ステータスチェックのタイムアウトチェックに時間がかかりすぎた場合にキューエントリを失敗させるCIの実行時間の約2倍
失敗していないPRのみマージグループ内で失敗したPRが他をブロックするかどうか有効化

デフォルトは保守的な設定です。ビルドの同時実行数はスループットを制御します。同時実行数が5で、CIの実行時間が10分の場合、各エントリは前のエントリの上に投機的にテストされるため、一度に1つずつマージするよりもはるかに速くマージできます。

ステップ3: 必須チェックの一致

キューのブランチで強制したいチェックを、同じルールセット内で必須ステータスチェックとして追加してください。安定した名前を使ってください。マトリックスは、マトリックスが変わると名前も変わってしまいます。単一のサマリージョブを用意すると、この問題を防げます。詳しくは正しいマトリックスビルドの方法をご覧ください。

二重に実行するチェックを決めてください。よくあるパターンは次のとおりです。高速なチェック(lintやユニットテスト)はPRとキューの両方で実行し、低速なチェック(完全なエンドツーエンドテストやマルチOS)はキューでのみ実行します。これにより、すべてのPRがその費用を負担しなくて済みます。コストはキューに集中し、PRへのフィードバックは素早く保たれます。

コストと速度への影響

マージキューは実行回数を増やします。キューに入った各PRでCIが少なくとも1回余分に実行されます。投機的ビルドを使う場合、前のエントリーが失敗すると、後続のエントリーはキャンセルされて再開されます。目安は次のとおりです。

  • マージされるPR1件あたりの追加時間は、キューで必須となるチェックの完全なCI実行1回分程度です。
  • 失敗が頻繁に起きると、その再実行が積み重なります。主な原因は不安定なテストです。詳しくは不安定なテストへの対処をご覧ください。
  • グループを大きくする(バッチ処理)と実行回数を減らせます。最大グループサイズを5にすると、5件のPRが1回のCI実行を共有できます。その代わり、失敗時の原因特定は難しくなります。

CI分数の予測ツールで試算してください。PR数/日 × キューのCI分数 × 料金率で算出できます。そのうえで、壊れたmainのコストと比較してください。通常、mainが壊れると全員の作業が止まります。

注意すべき点

  • チェックが開始されない: merge_groupトリガーが設定されていません。
  • 必須チェックがスキップされる: if:でスキップされたジョブは、スキップとして報告されることがあります。構成によっては、これが必須チェックでは合格扱いになります。if: always()を使ったサマリージョブのパターンを利用してください。
  • シークレットと権限: merge_groupは、通常のアクセス権を持つリポジトリのコンテキストで実行されます。それらのワークフローがどのシークレットに触れるかを確認してください。
  • ボットと依存関係の更新: Dependabotのプルリクエストはキューで問題なく動作します。手動でマージするのではなく、自動マージを有効にしてください。詳しくはDependabotの設定をご覧ください。
  • 必須レビューとCODEOWNERSは、PRがキューに入る前にも引き続き適用されます。詳しくはCODEOWNERSとブランチ保護をご覧ください。
  • 緊急修正: ルールセットの設定によっては、管理者がキューをバイパスしたり、割り込ませたりできます。事前にポリシーを決めておいてください。

代替手段

GitHubのマージキューを使えない場合は、サードパーティのツールで同様の動作を実現できます。Mergify、Aviator、Graphiteのキュー、Bors系のボットなどがあります。これらはいずれも、同じ種類の一時的な結合ブランチを作成して動作します。上記の懸念事項(トリガーの設定とコスト)は、すべてのツールに当てはまります。

よくある質問

自動マージを使うためにキューを有効にする必要はありますか?

いいえ。自動マージは、要件を満たした時点でマージします。キューが有効な場合は、代わりにPRをキューに追加します。

キューはPRをリベースしますか?

キューは、PRを一時的なブランチにマージします。最終的な方法は、マージ方法の設定に従います。PRのブランチは更新されません。

PRではチェックに合格するのに、キューで失敗した場合はどうなりますか?

そのPRはキューから削除されます。これは、他の変更との組み合わせによって何かが壊れたことを意味します。キューはまさにこのために存在します。ブランチを更新し、修正してから再度キューに入れてください。

必須のデプロイメントでも動作しますか?

環境を必須チェックに含めることはできますが、頼る前にトラフィックの少ないブランチで試してください。

効果を測定する

「マージ可能な状態になった」時点からマージされるまでの時間と、導入前後の<main>破損インシデントの件数を追跡してください。キューのCIがボトルネックになっている場合は、高速なランナーを使うと全員の待ち時間を短縮できます。compiler.devの比較モードを使うと、より高速なマシンでキューのワークフローを試し、実行ごとのコストを比較できます。

このワークフローを compiler.dev で実行する カード登録不要 · 200 無料分

無料で試す