GitHubの非同期マージAPIが正式提供。202応答の後に確認すべきこと

GitHub Pull Request REST API DevOps
<style> .gm-hero{padding:clamp(25px,5vw,48px);border-radius:24px;background:linear-gradient(125deg,#102035,#15477b 55%,#19a3a2);color:#fff}.gm-hero h2{color:#fff;margin:.35em 0}.gm-kicker{font-size:.8rem;letter-spacing:.13em;font-weight:800;color:#a9eff0}.gm-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px;margin:22px 0}.gm-card{padding:18px;border-radius:16px;background:#eff9fc;border:1px solid #b7dce8}.gm-card strong{display:block;color:#145477;font-size:1.25rem}.gm-flow{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:9px;margin:20px 0}.gm-step{padding:15px;border-radius:14px;border:1px solid #c1e3df;background:#f1fbf9}.gm-step b{display:block;color:#08736e}.gm-table{overflow-x:auto;margin:20px 0}.gm-table table{min-width:630px;width:100%;border-collapse:collapse}.gm-table th,.gm-table td{border:1px solid #cbd5e1;padding:11px;text-align:left;vertical-align:top}.gm-table th{background:#e7f4f9;color:#174a69}.gm-note{padding:16px 19px;border-left:5px solid #e59b25;border-radius:10px;background:#fff8e9;margin:20px 0}@media(max-width:760px){.gm-grid,.gm-flow{grid-template-columns:1fr}} </style>

DEVELOPMENT / DEVOPS / 2026.10

「受け付けた」と「マージした」は違う

大きなPRや積み重ねPRを扱う自動化ほど、非同期処理の最終状態を正しく見届ける必要があります。

3行で要約

  • GitHubは2026年10月1日、Pull Request向けの非同期マージAPIを一般提供しました。単独PR、積み重ねPR、マージキューを1つの入口から扱えます。[^news]
  • PUT .../merge-asyncのHTTP 202は処理の受理です。返されたUUIDでGETを行い、merged・enqueued・failedを判別します。[^api]
  • enqueuedはキューに入っただけでマージ完了ではありません。自動化の成功条件はマージ済み状態まで追跡して設計します。^api

背景：同期APIの「待つ」限界

従来の同期マージAPIは1回のリクエストでマージ結果を返します。一方、ルール評価、複数PRの処理、マージキューなどは時間がかかることがあります。GitHubは非同期APIを、複雑なマージでタイムアウトを避けやすく、バックグラウンドで再試行できる方式として説明し、プログラムからマージする際の推奨経路と位置づけました。これはGitHubの製品説明であり、すべてのリポジトリでマージ所要時間が短縮するという実測結果ではありません。[news][api]

積み重ねPR（stacked PR）は、小さな変更を依存関係のある複数PRに分ける方法です。GitHubの現行文書では、このPR群をAPIからマージするには非同期APIが必須です。[stack][api]

何が新しいのか

単一・積み重ねPR単独PRに加え、対象までの未マージ下位PRをまとめて処理。
マージキュー対応設定に応じて直接マージ、キュー追加、既定動作を選択。
状態を追跡PUTの戻り値に含まれるUUIDで最終結果を確認。

merge_actionはdefault、direct_merge、merge_queueを選べます。defaultは対象ブランチにキューが設定されていればキューを使い、そうでなければ直接マージします。bypass_rulesもありますが、権限のある利用者が明示的に指定する例外操作です。通常の自動化では既定のままルールを尊重するのが基本です。[^api]

技術的な要点：状態遷移を分けて扱う

1 / PUTPR番号と期待するhead SHAを指定して要求
2 / 202 + UUID受理された要求IDを保存
3 / GETUUIDでpending・merged・enqueued・failedを確認
4 / 最終確認キュー利用時はPRの実際のマージ状態も確認
公式API文書に基づく応答の意味
応答・状態意味自動化での判断
PUT: HTTP 202非同期要求を受け付けた成功完了にはしない。UUIDを保存
GET: pending処理中間隔を空けて再確認
GET: mergedベースブランチにマージ済みマージコミットIDを記録
GET: enqueuedマージキューへ追加済みPRのマージ済み状態を別途追跡
GET: failed要求が失敗理由を記録し、ルール・競合を確認

GitHubの文書では、ブランチ保護やリポジトリルールはPUT時点で完全には評価されず、後段で失敗する可能性があります。202をデプロイ開始の合図にしてはいけない理由です。また、enqueuedのGET結果はキュー投入に対する最終結果で、その後にmergedへ変わるわけではありません。[^api]

実践例：安全なCI連携の骨組み

以下はAPIの形を示す擬似コードです。実行用トークンの取得・保存方法は組織の秘密情報管理に従ってください。shaには事前に取得したPRの現在のhead SHAを指定し、確認後にPRが更新された場合の意図しないマージを防ぎます。[^api]

PUT /repos/OWNER/REPO/pulls/NUMBER/merge-async
body: {"sha":"確認済みのPR head SHA","merge_action":"default"}

202ならUUIDを保存
GET /repos/OWNER/REPO/pulls/NUMBER/merge-async/UUID
pending  → 間隔を空けて再確認
merged   → マージコミットIDを記録し次工程へ
enqueued → PRのmerged状態を別の確認経路で監視
failed   → 理由を記録して停止
  1. PRのレビュー、チェック、ルール、head SHAを確認します。shaを省略した場合もGitHubは要求時のheadを使い、処理までに更新されたらキャンセルすると説明しています。明示すると自動化側の意図が監査しやすくなります。[^api]
  2. PUTの200、202、400、409を分岐します。409は同じPRの保留中要求がある場合にUUIDとオプションを返すため、無条件に別要求を連打しません。[^api]
  3. 202ならGETで確認します。結果は最終更新から24時間保持され、その後UUID照会は404になり得ます。タイムアウトと失敗通知を設け、ジョブを放置しないでください。[^api]
  4. マージキューを利用する場合、enqueuedの後はPRが実際にマージされたか別途確認します。キューから除外される場合もあります。^api

開発者・企業への影響

自動マージbotやリリースパイプラインは、単一のHTTP応答ではなく要求・処理・キュー・実際のマージを別の状態として管理する必要があります。GitHubは積み重ねPRの対象までの未マージ下位PRをまとめて扱い、要求を原子的に処理すると説明しています。レビューとチェックが揃わなければ、後段で失敗し得ます。^stack

実務上の推論として、デプロイやリリースノート作成のトリガーは202やenqueuedではなく、マージ済みのPRまたはベースブランチ上のコミットを根拠に置くのが安全です。

リスクと限界

一番多い誤解：「要求を受け付けた」「キューに入った」は「コードがmainに入った」と同義ではありません。[^api]
  • ルール違反や競合： 要求時に受理されても、後段のルール評価で失敗し得ます。[^api]
  • 積み重ねPRはプレビュー： 非同期マージAPI自体は一般提供ですが、GitHub文書では積み重ねPR機能を公開プレビューと記載しています。両者の成熟度を混同しないでください。^news
  • 権限： APIにはリポジトリのContents: writeが必要です。bypass_rulesを安易に有効化しないでください。[^api]
  • ポーリング： 過度な照会を避ける間隔と、タイムアウト時の再確認・通知を設計する必要があります。これは運用上の提案です。

今後注目すべき点

積み重ねPRの正式提供範囲、キュー連携の運用実績、既存の同期APIを使うbotの移行状況です。まずはテスト用リポジトリでpending → mergedとenqueued → 実際のマージを別経路として検証し、成功条件を見直すとよいでしょう。

最終確認日：2026年10月2日（日本時間）。 発表日は2026年10月1日。仕様とステータスはGitHubの一次資料、CI運用の勧めは編集上の提案です。

参照元

[^news]: GitHub Changelog：非同期マージAPIの一般提供（2026年10月1日） [^api]: GitHub公式REST API：非同期マージ要求と結果取得

Previous Post Next Post