マージキューの管理

マージ キューについて

マージ キューを使用すると、pull request のマージをビジー ブランチに自動化し、互換性のない変更によってブランチが中断されないようにすることで、速度を向上できます。

マージ キューは、 [マージする前にブランチを最新の状態にする] ブランチ保護と同じ利点を提供しますが、pull request の作成者が pull request ブランチを更新し、状態チェックが完了するのを待ってからマージを試みる必要はありません。

マージ キューの使用は、多くの異なるユーザーから毎日比較的多数の pull request がマージされるブランチで特に便利です。

pull request が必要なすべてのブランチ保護チェックに合格すると、リポジトリへの書き込みアクセス権を持つユーザーは、その pull request をキューに追加できます。 マージ キューでは、pull request の変更がターゲット ブランチの最新バージョンとキュー内に既に存在する pull request に適用されたときに、それらが必要な状態チェックをすべて通過したことが保証されます。

マージ キューでは、GitHub Actions または独自の CI プロバイダーを使用して、マージ キュー内の pull request に対して必要なチェックを実行できます。 詳しくは、「GitHub Actions のドキュメント」を参照してください。

マージ キューを使用して pull request をマージする方法について詳しくは、「pull request とマージ キューのマージ」を参照してください。

マージ キューの継続的インテグレーション (CI) ワークフローを構成する

GitHub Actions を使ってマージ グループのチェックをトリガーする

pull request がマージ キューに追加されたときに GitHub Actions ワークフローをトリガーするには、merge_group イベントを使用する必要があります。

ターゲット ブランチの保護で必要なチェックを報告するワークフローは、次のようになります。

on:
  pull_request:
  merge_group:

merge_group イベントの詳細については、「ワークフローをトリガーするイベント」をご覧ください。

サードパーティの CI プロバイダーを使ってマージ グループのチェックをトリガーする

サードパーティの CI プロバイダーを使う場合、特別なプレフィックス gh-readonly-queue/{base_branch} で始まるブランチがプッシュされたときに実行するように CI 構成を更新する必要があります。 これらは、ユーザーに代わってマージ キューで作成される一時的なブランチであり、pull request とは異なる sha が含まれます。

マージキューの管理

リポジトリ管理者は、ベースブランチの保護ルールで「マージキューを必須にする」ブランチ保護設定を有効にし、マージを必須にできます。 詳しくは、「ブランチ保護ルールを管理する」を参照してください。

[マージ キュー必須] を有効にすると、次の設定にもアクセスできます。

• マージ方法: キューに登録済みの pull request をマージするときに使う方法 (マージ、リベース、スカッシュ) を選びます。

• ビルドのコンカレンシー: ディスパッチする merge_group Webhook の最大数 (1 から 100 まで)。同時 CI ビルドの合計量を調整します。 これは、マージ キューが完了できるマージの速度に影響します。

• 不合格以外の pull request のみをマージする: この設定により、マージされる pull request のグループがマージ キューによってどのように形成されるかが決まります。

  有効?	説明
  はい	すべての pull request は、マージするために必要なチェックを満たす必要があります。
  いいえ	必須のチェックに不合格だった pull request は、グループ内の最後の pull request が必須のチェックに合格している限り、グループに追加できます。 グループ内の最後の pull request が必須のチェックに合格している場合は、そのチェックがマージ グループ内の変更の組み合わせで合格だったことを意味します。 断続的にテストが不合格になるものの、偽陰性によってキューがそのままの状態にならないようにしたい場合は、このチェックボックスをオフのままにしておくのがよいでしょう。

• 状態チェックのタイムアウト: チェックが不合格だったと想定される前にキューで必要な CI からの応答待機時間を選びます。

• マージの制限: 1 つのグループ内でマージする pull request の最小数と最大数 (1 から 100 まで) とタイムアウトを選びます。このタイムアウトを過ぎると、キューは追加のエントリの待機を停止し、最小数より少ない数の pull request でマージを実行する必要があります。 グループに含まれる PR の正確な数は、マージ キューの設定によって異なります。

  マージの制限	ユース ケース
  マージする pull request の最大数	グループの最大サイズを指定できます。これは、ベース ブランチへのマージによってデプロイがトリガーされ、一度にデプロイする変更が多すぎないようにする場合に役立ちます。
  マージする pull request の最小数	グループの最小サイズを指定できます。これは、ベース ブランチへのマージによって長い CI ビルドまたはデプロイ プロセスがトリガーされ、キューに次のエントリを保持したくない場合に役立ちます。
  待機時間	グループの最小サイズに達するまでのタイムアウトを指定できます。これにより、指定した制限時間内にキューに登録される PR がなくなった場合に、より小さいグループをマージできます。

マージ キューのしくみ

pull request がマージ キューに追加されると、マージ キューによって、必要なチェックが常に満たされる先入れ先出しの順序で確実にマージされます。

マージ キューでは、pull request の変更の有効性を検証するための特別なプレフィックスを付けた一時ブランチが作成されます。 pull request がマージ キューに追加されると、pull request の変更はmerge_group にグループ化されます。これには、base_branch の最新バージョンとキュー内のそれより前の pull request の変更が含まれます。 GitHub では、base_branch のブランチ保護に必要なチェックに合格すると、これらの変更がすべて base_branch にマージされます。

マージ方法について詳しくは、「プルリクエストのマージについて」をご覧ください。

CI の成功

複数の pull request がマージ キューに追加され、一時 merge_group ブランチに成功した CI 結果が含まれると、両方がマージされます。 次のシナリオでは、2 つの pull request がキューに正常に追加され、ターゲット ブランチにマージされます。

1. ユーザーが pull request #1 をマージ キューに追加します。
2. マージ キューでは、ターゲット ブランチと pull request #1 からのコード変更を含む一時ブランチが作成され、プレフィックス main/pr-1 が付けられます。 checks_requested 型の merge_group Webhook イベントがディスパッチされ、マージ キューは CI プロバイダーからの応答を待ちます。
3. ユーザーが pull request #2 をマージ キューに追加します。
4. マージ キューでは、ターゲット ブランチ、pull request #1、pull request #2 からのコード変更を含む一時ブランチがプレフィックス main/pr-2 を付けて作成され、Webhook がディスパッチされます。
5. GitHub API で、merge_group ブランチ main/pr-1 と main/pr-2 の CI の成功を示す応答が受信されると、一時ブランチ main/pr-2 がターゲット ブランチにマージされます。 ターゲット ブランチには、pull request #1 と #2 の両方の変更が含まれるようになりました。

CI の失敗

ターゲット ブランチの最新バージョンとキュー内のそれより前の変更を含むグループに pull request をグループ化した後、必要な状態チェックが失敗した場合、またはベース ブランチと競合した場合、pull request はキューから削除されます。 pull request タイムラインには、その pull request がキューから削除された理由が表示されます。

次のシナリオでは、1 つの pull request について CI が失敗状態を報告した場合の動作について説明します。

1. ユーザーが pull request #1 をマージ キューに追加します。
2. マージ キューでは、ターゲット ブランチと pull request #1 からのコード変更を含む一時ブランチが作成され、プレフィックス main/pr-1 が付けられます。 checks_requested 型の merge_group Webhook イベントがディスパッチされ、マージ キューは CI プロバイダーからの応答を待ちます。
3. ユーザーが pull request #2 をマージ キューに追加します。
4. マージ キューでは、ターゲット ブランチ、pull request #1、pull request #2 からのコード変更を含む一時ブランチがプレフィックス main/pr-2 を付けて作成され、Webhook がディスパッチされます。
5. GitHub API で main/pr-1 の失敗状態が受信されると、マージ キューによって pull request #1 がマージ キューから自動的に削除されます。
6. マージ キューでは、ターゲット ブランチと pull request #2 からのコード変更のみを含む一時ブランチが作成され、プレフィックス main/pr-2 が付けられます。
7. GitHub API で、merge_group ブランチと main/pr-2 の CI の成功を示す応答が受信されると、一時ブランチ main/pr-2 がターゲット ブランチにマージされます。pull request #1 は含まれません。

pull request をマージ キューから削除できる理由は、数多くあります。

• 構成済みの CI サービスがマージ グループのテスト エラーを報告している
• 成功した CI 結果の待機が、構成されたタイムアウト設定に基づいてタイムアウトした
• ユーザーが API またはマージ キュー インターフェイスを使用して削除を要求した
• ブランチ保護エラーを自動的に解決できなかった

キューの先頭にジャンプする

マージ キューに pull request を追加する場合、その pull request をキューの先頭に移動するオプションがあります。

次のシナリオでは、ユーザーがキューでジャンプを行った場合の動作について説明します。

1. ユーザーが pull request #1 をマージ キューに追加します。
2. マージ キューでは、ターゲット ブランチと pull request #1 からのコード変更を含む一時ブランチが作成され、プレフィックス main/pr-1 が付けられます。 checks_requested 型の merge_group Webhook イベントがディスパッチされ、マージ キューは CI プロバイダーからの応答を待ちます。
3. ユーザーが pull request #2 をマージ キューに追加します。
4. マージ キューでは、ターゲット ブランチ、pull request #1、pull request #2 からのコード変更を含む一時ブランチがプレフィックス main/pr-2 を付けて作成され、Webhook がディスパッチされます。
5. ユーザーがジャンプ オプションを使用して pull request #3 をマージ キューに追加します。これにより、コミット グラフの中断が発生します。
6. マージ キューでは、ターゲット ブランチと pull request #3 からのコード変更を含む一時ブランチがプレフィックス main/pr-3 を付けて作成され、Webhook がディスパッチされます。
7. マージ キューでは、pull request #3 からのコード変更を含む 2 つの一時ブランチがプレフィックス main/pr-1 と main/pr-2 を付けて作成され、Webhook がディスパッチされます。

参考資料

• pull request とマージ キューのマージ
• 保護されたブランチについて