マージ キューについて
マージ キューを使用すると、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) ワークフローを構成する
注:
- マージキューは、ブランチ名パターンにワイルドカード文字 (
*
) を使用するブランチ保護ルールで有効にできません。 - マージ キューは、マージを続ける前に、必要なチェックが報告されるまで待機します。 マージ キューが必要な場合は、マージ グループ イベントをトリガーして報告するように、CI の構成を更新する必要があります。
- マージ キューと pull request のチェックは、ブランチ保護ルールまたはルールセットの下で、結合および構成されます。 詳しくは、「マージキューの管理」を参照してください。
GitHub Actions を使ってマージ グループのチェックをトリガーする
pull request がマージ キューに追加されたときに GitHub Actions ワークフローをトリガーするには、merge_group
イベントを使用する必要があります。
注: リポジトリで GitHub Actions を使用して、リポジトリ内の pull request において必要なチェックを実行する場合は、追加のトリガーとして merge_group
イベントを含むようにワークフローを更新する必要があります。 それ以外の場合、マージ キューに pull request を追加しても、ステータス チェックがトリガーされません。 必要な状態チェックが報告されないため、マージは失敗します。 merge_group
イベントは、pull_request
および push
イベントとは異なります。
ターゲット ブランチの保護で必要なチェックを報告するワークフローは、次のようになります。
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 からの応答待機時間を選びます。
-
マージの制限: 同時にベース ブランチにマージする pull request の最小数と最大数 (
1
から100
まで) とタイムアウトを選びます。このタイムアウトを過ぎると、キューでは追加のエントリの待機が停止されるため、最小数より少ない数でマージを実行する必要があります。
注: マージの制限では、merge_group
ビルドは結合されません。 マージの制限は、1 つまたは複数の merge_group
がビルド チェックを満たした場合にのみ、ベース ブランチへのマージに影響します。
マージの制限 | ユース ケース |
---|---|
マージする 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 がキューに正常に追加され、ターゲット ブランチにマージされます。
- ユーザーが pull request #1 をマージ キューに追加します。
- マージ キューでは、ターゲット ブランチと pull request #1 からのコード変更を含む一時ブランチが作成され、プレフィックス
main/pr-1
が付けられます。checks_requested
型のmerge_group
Webhook イベントがディスパッチされ、マージ キューは CI プロバイダーからの応答を待ちます。 - ユーザーが pull request #2 をマージ キューに追加します。
- マージ キューでは、ターゲット ブランチ、pull request #1、pull request #2 からのコード変更を含む一時ブランチがプレフィックス
main/pr-2
を付けて作成され、Webhook がディスパッチされます。 - 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 が失敗状態を報告した場合の動作について説明します。
- ユーザーが pull request #1 をマージ キューに追加します。
- マージ キューでは、ターゲット ブランチと pull request #1 からのコード変更を含む一時ブランチが作成され、プレフィックス
main/pr-1
が付けられます。checks_requested
型のmerge_group
Webhook イベントがディスパッチされ、マージ キューは CI プロバイダーからの応答を待ちます。 - ユーザーが pull request #2 をマージ キューに追加します。
- マージ キューでは、ターゲット ブランチ、pull request #1、pull request #2 からのコード変更を含む一時ブランチがプレフィックス
main/pr-2
を付けて作成され、Webhook がディスパッチされます。 - GitHub API で
main/pr-1
の失敗状態が受信されると、マージ キューによって pull request #1 がマージ キューから自動的に削除されます。 - マージ キューでは、ターゲット ブランチと pull request #2 からのコード変更のみを含む一時ブランチが作成され、プレフィックス
main/pr-2
が付けられます。 - GitHub API で、
merge_group
ブランチとmain/pr-2
の CI の成功を示す応答が受信されると、一時ブランチmain/pr-2
がターゲット ブランチにマージされます。pull request #1 は含まれません。
pull request をマージ キューから削除できる理由は、数多くあります。
- 構成済みの CI サービスがマージ グループのテスト エラーを報告している
- 成功した CI 結果の待機が、構成されたタイムアウト設定に基づいてタイムアウトした
- ユーザーが API またはマージ キュー インターフェイスを使用して削除を要求した
- ブランチ保護エラーを自動的に解決できなかった
キューの先頭にジャンプする
マージ キューに pull request を追加する場合、その pull request をキューの先頭に移動するオプションがあります。
注: キューの並べ替えによってコミット グラフが中断されるため、マージ キューの先頭にジャンプすると、進行中のすべての pull request が完全に再構築されることに注意してください。 この機能を頻繁に利用すると、ターゲット ブランチのマージの速度が遅くなる可能性があります。
次のシナリオでは、ユーザーがキューでジャンプを行った場合の動作について説明します。
- ユーザーが pull request #1 をマージ キューに追加します。
- マージ キューでは、ターゲット ブランチと pull request #1 からのコード変更を含む一時ブランチが作成され、プレフィックス
main/pr-1
が付けられます。checks_requested
型のmerge_group
Webhook イベントがディスパッチされ、マージ キューは CI プロバイダーからの応答を待ちます。 - ユーザーが pull request #2 をマージ キューに追加します。
- マージ キューでは、ターゲット ブランチ、pull request #1、pull request #2 からのコード変更を含む一時ブランチがプレフィックス
main/pr-2
を付けて作成され、Webhook がディスパッチされます。 - ユーザーがジャンプ オプションを使用して pull request #3 をマージ キューに追加します。これにより、コミット グラフの中断が発生します。
- マージ キューでは、ターゲット ブランチと pull request #3 からのコード変更を含む一時ブランチがプレフィックス
main/pr-3
を付けて作成され、Webhook がディスパッチされます。 - マージ キューでは、pull request #3 からのコード変更を含む 2 つの一時ブランチがプレフィックス
main/pr-1
とmain/pr-2
を付けて作成され、Webhook がディスパッチされます。