mergify-merge-queue

Mergify マージキュー

概要

マージキューは PR のマージを直列化し、一時的なマージコミットに対して CI を実行することで、統合時の失敗がターゲットブランチに到達する前に検出します。PR へのコメントを使用してキューへの追加・削除を行い、CLI を使用してキューの状態を監視し、個々の PR を調査し、キューを管理します。

mergify queue show <PR> は、もはやキューにない PR についても報告します — キューから削除されたのか、キューによってマージされたのか、そもそもキューに入っていなかったのか、そしてその理由 — したがって、キューから消えた PR についてはまずここから始めてください。キューから削除された PR の診断を参照してください。そこに記載されている GitHub 側のサーフェスは、CLI がアクティビティログを読み取れない場合のフォールバックです。

PR のキューへの追加と削除

キューへの追加、削除、再追加のアクションは、CLI ではなく プルリクエストへのコメントによって実行されます:

コメント	効果
@mergifyio queue	PR をマージキューに追加します(キューから削除された PR を再追加する場合にも使用します)
@mergifyio dequeue	PR をマージキューから削除(デキュー)します

@mergifyio requeue も受け付けられますが、これは @mergifyio queue と同じコマンドを実行する非推奨のエイリアスです — 個別の再追加動作はありません。@mergifyio queue を投稿してください。

Mergify がコメントを処理すると、受け取ったことを知らせるためにコメントに 👍(サムズアップ)リアクションを追加します。キューへの追加後、mergify queue show <PR_NUMBER> を使用して、PR がキューを進むにつれてそのステータスを確認できます。

コマンド

mergify queue status                 # Show queue status (batches, waiting PRs)
mergify queue status --branch main   # Filter by branch
mergify queue status --json          # Machine-readable JSON output
mergify queue show <PR_NUMBER>       # Detailed state of a PR in the queue
mergify queue show <PR_NUMBER> -v    # Full checks table and conditions tree
mergify queue show <PR_NUMBER> --json # Machine-readable JSON output
mergify queue pause --reason "..."   # Pause the queue (requires reason)
mergify queue unpause                # Resume the queue

これが queue グループの全体です: status、show、pause、unpause。PR をデキューするためのサブコマンドはありません — デキューの理由は、フラグからではなく、キューを離れた PR に対する queue show から得られます。完全なキューの トレイル(最後の離脱イベントだけでなく、すべての enter / checks / leave イベント)については、mergify events --pr <PR> --since 90d を使用してください — mergify-events スキルを参照してください。

PR はキューに入っているか、デキューされたか、それとも一度もキューに入っていないか？

ここから始めてください — ワークフローの残りの部分はこの答えで分岐します。

mergify queue show <PR> は 4 つのケースすべてに答えます。キューエントリのない PR は正常な答えであり、エラーではありません。このコマンドは以下のどのケースでも通知を出力し、終了コード 0 で終了します。

queue show の結果	意味
位置 / CI 状態を含む PR #N ブロック	その PR はキューに入っています
PR #N was dequeued <when> + Dequeue code	マージされずにキューを離れました — 理由の表を参照
PR #N was merged by the merge queue <when>	マージによってキューを離れました。デキューではありません
PR #N is not in the merge queue	保持ウィンドウ内にキューのアクティビティがありません — 一度もキューに入っていない、期限切れ、または実在しない PR 番号

--json では、現在キューに入っていない PR は queued: false と dequeued ディスクリミネーターを持ちます。

mergify queue show 1234 --json | jq -e '.queued == false' >/dev/null && echo "not in queue"

• dequeued: true — マージされずに離れました。生の離脱イベントは queue_leave の下にあります
• dequeued: false — キューによってマージされた、または一度もキューに入っていない（queue_leave がこの 2 つを区別します。null は一度もキューに入っていないことを意味します）
• dequeued: null — ルックアップ自体が失敗しており、queue_leave_error がその理由を示します。「一度もキューに入っていない」とは同じではありません — 何かを結論づける前に、GitHub 側のサーフェスにフォールバックしてください

queue_leave_head_sha は、この診断が対象としている head を保持します。そこから何かを報告する前に、PR の現在の head と比較してください — デキューはしばしばプッシュによって引き起こされるため、その失敗チェックは PR がもはや持っていないコミットに属していることがよくあります。

mergify queue show 1234 --json | jq -r '.queue_leave_head_sha'   # 31b4a485b8ce…
gh pr view 1234 --json headRefOid -q .headRefOid                 # 340361aae580…  → superseded, stay quiet

留意すべき 2 つの制限があります。履歴は90 日前までさかのぼります（アクティビティログの保持期間）。そのため、それより古いデキューは「アクティビティなし」として読み取られます。また、このコマンドは PR が存在することを確認しないため、番号を打ち間違えると同じ「not in the merge queue」通知が出力されます。一度もキューに入っていないと結論づける前に、PR が実在することを確認してください（gh pr view <PR>）。

Mergify Merge Queue チェックランの存在を判定基準として使用しないでください。キュー条件に単に一致するだけの PR は、一度もキューに入ることなく Waiting for queue conditions というタイトルのチェックランを取得します。# Merge Queue Status コメントは信頼できるポジティブシグナルです（キューの前段階である「Queue this pull request」オファーコメントは、意図的にそのような見出しを持ちません）が、その不在は何も証明しません。コメントはリポジトリごとに無効化できるためです。

デキューされた PR の診断

理由を保持するサーフェスは 4 つあります。この順序で優先してください。

1. mergify queue show <PR>（ここから始める）

もはやキューに入っていない PR に対して、queue show はその PR の最後のマージキュー離脱を読み取り、それをレンダリングします。

PR #37823 was dequeued 24m ago

  Dequeue code:  CHECKS_FAILED
  Queue:         default
  Queued at:     46m ago
  Trigger:       merge queue internal
  Head SHA:      31b4a48

  The merge conditions cannot be satisfied due to failing checks

  - `@github-actions/all-greens`

  Failing checks:
    ✗ all-greens  failure
      https://github.com/Mergifyio/monorepo/actions/runs/…/job/…

  Fix the cause above, then comment `@mergifyio queue` on the pull request.

これはエンジン自身の説明に加えて、失敗チェックをそのジョブログ URL 付きで示します — 失敗したジョブを探し回るのではなく、直接そのジョブに進んでください。説明はコンパクトモードでは 12 行に制限されます。全体を表示するには -v を追加してください（PR_DEQUEUED 理由は満たされなかった条件のツリー全体を埋め込み、それは数十行に及びます）。

Head SHA は、そのすべてが説明しているコミットです。これが PR の現在の head でない場合、そのレポートはその後置き換えられたコミットに関するものです — 上記のチェックはすでに再びグリーンになっている可能性があります。失敗に基づいて行動する前に確認してください。

--json は同じものを機械可読な形で提供します。dequeued、および生のイベントを保持する queue_leave により、.queue_leave.metadata から dequeue_code、reason、unsuccessful_checks[].details_url を読み取れます。上記の陳腐化チェックには、昇格された queue_leave_head_sha を使用してください。

アクティビティログの読み取りはベストエフォートです。マージキューにスコープされたトークンは、リポジトリのイベントログへのアクセスを拒否されることがあります（403）。その場合、コマンドは単なる「not in the merge queue」通知と stderr への警告にデグレードし、dequeued: null を報告します — これは以下のサーフェスにフォールスルーするためのシグナルであり、その PR が一度もキューに入っていないという表明ではありません。

2. Mergify のアクティビティログ（サーフェス 1 が内部で読み取るもの）

GET /v1/repos/{owner}/{repo}/logs はキューのライフサイクルイベントを新しい順に返します。queue show はこれを代わりに呼び出し、mergify events --pr <PR> --since 90d（mergify-events スキル）はコマンドラインからライフサイクル全体を閲覧できます — キューのイベントだけでなく、すべてのイベントタイプを含みます。curl を直接使うのは、それが機能しなくなる場合（上記の 403 で、ログを読み取れるトークンがある場合）または CLI がインストールされていない環境からのみにしてください:

MERGIFY_TOKEN には Mergify トークンを設定する必要があります。GitHub トークンは Mergify API に対して依然として機能しますが非推奨であり、mergify auth login が保存する認証情報は環境変数ではなく OS のキーチェーンに保存されるため、生の curl からはアクセスできません。

REPO=owner/repo
PR=1234
FROM=$(date -u -d '90 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-90d +%Y-%m-%dT%H:%M:%SZ)

curl -sS -H "Authorization: Bearer ${MERGIFY_TOKEN:?set a Mergify token}" \
  "https://api.mergify.com/v1/repos/$REPO/logs?pull_request=$PR&event_type=action.queue.leave&received_from=$FROM" \
| jq 'if .events == [] then "no leave event in window — never queued (or aged out)"
      else .events[0].metadata
           | {merged, dequeue_code, reason,
              failing: [.unsuccessful_checks[]? | {name, state, details_url}]}
      end'

{
  "merged": false,
  "dequeue_code": "CHECKS_FAILED",
  "reason": "The merge conditions cannot be satisfied due to failing checks\n\n- `ci-gate`",
  "failing": [
    {
      "name": "ci-gate",
      "state": "failure",
      "details_url": "https://github.com/owner/repo/actions/runs/28589756829/job/84771312071"
    }
  ]
}

これを次のように読み取ります:

• "events": [] / size: 0 → ウィンドウ内に leave イベントがない → その PR は 一度もキューに入っていない（またはイベントがウィンドウ外になった。以下のウィンドウのルールを参照）。
• merged: true → マージによってキューを離れた。デキューではありません。
• merged: false → デキューされた。dequeue_code が理由を示します（理由の表を参照）。
• unsuccessful_checks[].details_url → 失敗した CI ジョブのログへの直接リンク。これは、PR がキューを離れた後に CI の失敗にたどり着く方法です。

これが何も返さない原因になる 2 つの罠:

• received_from は実際には必須です。 ウィンドウのデフォルトは過去 24 時間です。先週のデキューはエラーなしで size: 0 を返し、「一度もキューに入っていない」とまったく同じように読めます。常に received_from を渡してください。
• ウィンドウは 93 日を超えることはできません（保持期間は 90 日）。超えると、呼び出しは 422 'received_from' and 'received_to' cannot span more than 93 days で失敗します。

同じエンドポイントで、他にも便利なフィルターがあります: &outcome=failure は leave イベントをデキューに限定します（マージは success）。event_type を外すとライフサイクル全体（action.queue.enter、checks_start、checks_end、leave）を確認できます。

3. Mergify Merge Queue チェックラン

チェックランのタイトルが理由を直接示し、そのサマリーが完全なキューレポートです:

SHA=$(gh pr view $PR --repo $REPO --json headRefOid -q .headRefOid)
gh api "repos/$REPO/commits/$SHA/check-runs" \
  -q '.check_runs[] | select(.name=="Mergify Merge Queue") | {conclusion, title: .output.title, summary: .output.summary}'

タイトルは解析なしで状態に対応します:

output.title	状態
Dequeued — <reason>（conclusion neutral）	デキュー済み、理由はタイトル内
Dequeued from merge queue（conclusion neutral）	デキュー済みだが、理由が名前付きコードに解決されなかった — サーフェス 1 を使用
Merged via merge queue（conclusion success）	キューによってマージ済み
Waiting for queue conditions、Checks …、In merge queue	まだライフサイクル内

注意点: チェックランはそれが書き込まれた head SHA 上に存在します。デキューがプッシュ（PULL_REQUEST_UPDATED、DRAFT_PULL_REQUEST_CHANGED）によって引き起こされた場合、現在の head には新しいチェックランがあり、デキューレポートは前の SHA 上にあります。その場合はサーフェス 1 または 4 を使用してください — サーフェス 1 は SHA（Head SHA / queue_leave_head_sha）を示すので、その不一致に陥るのではなく検出できるのはこちらです。また、gh pr view --json statusCheckRollup は null の title を返すことに注意してください — 上記のように gh api .../check-runs を経由してください。

4. # Merge Queue Status コメント

mergify[bot] はキューセッションごとに 1 件のコメントを投稿するため、最後の 1 件を読んでください。これはプッシュ後も残るため、GitHub 側で最も堅牢なサーフェスとなります。

gh api --paginate --slurp "repos/$REPO/issues/$PR/comments" \
| jq -r '[.[][] | select(.user.login=="mergify[bot]")
              | select(.body|contains("# Merge Queue Status"))] | last | .body'

--paginate が重要です。このエンドポイントは 1 ページあたり 30 件のコメントを返し、最新のものは最後のページにあるため、これがないと last は実際に議論がある PR で古いステータスコメント（または何も）を黙って返してしまいます。--slurp はページを配列の配列にまとめます — したがってフラット化するために .[][] を使います — そして -q とは互換性がないため、フィルターは代わりに jq を通します。

その構造は、順に、隠された JSON ペイロード、タイムライン、マージ条件、そして ## Reason、Failing checks:（それぞれに [job log] リンク付き）、## Hint です。隠されたペイロードは文章を解析せずに状態を提供します:

state は waiting、checking、frozen、bisecting、merged、dequeued のいずれかです。これはデキューコードを保持しません — それはその下の ## Reason の文章にあります。

注意点: このコメントはリポジトリごとに無効化できます（merge_queue.status_comments: none、または終端イベントのみの場合は outcomes）。コメントが存在しないことは、PR がキューに入れられたことがない証拠にはなりません。

デキュー理由と次に取るべきアクション

dequeue_code の値と、それに対して求められるアクション。エンジンはレポート内に理由ごとの ## Hint を含めています。ここに記載のないコードについては、推測せずにその Hint を読んでください。

dequeue_code	何が起きたか	次に取るべきアクション
PR_MERGED	キューによってマージされた	何もなし — これは成功です
PR_MANUALLY_MERGED	キューを介さずにマージされた	何もなし
CHECKS_FAILED	マージコミットで必須チェックが失敗した	unsuccessful_checks[].details_url を読み、CI を修正してください。修正をプッシュすると、条件が再び一致した時点で自動的に再キューされます。一時的な失敗だった場合は、そのまま @mergifyio queue で再キューしてください
CHECKS_TIMEOUT	条件が満たされる前に checks_timeout が経過した	理由の詳細を確認してください。一度も報告されなかったチェックは、条件内のチェック名が CI の公開する名前と一致していないことを意味します (PR ではなく設定を修正してください)。まだ実行中のチェックは、CI が遅すぎるかスタックしていることを意味します
PULL_REQUEST_UPDATED	キュー中に誰かが PR にプッシュした	キュー中の PR へのプッシュはやめてください。ブランチが確定したら再キューしてください
DRAFT_PULL_REQUEST_CHANGED	キューのドラフト/バッチ PR に Mergify が作成していないコミットが入った	マージキューのドラフトブランチには絶対にプッシュしないでください。元の PR を再キューしてください
CONFLICT_WITH_BASE_BRANCH	PR がベースブランチとコンフリクトしている	ベースブランチをリベースまたはマージし、コンフリクトを解消してから再キューしてください
CONFLICT_WITH_PULL_AHEAD	PR がキュー内で先行する PR とコンフリクトしている	先行する PR がマージされるのを待ち、その後リベースして再キューしてください
BRANCH_UPDATE_FAILED	Mergify が PR のヘッドブランチを更新できなかった	理由の詳細を読み、自分でブランチを更新して再キューしてください
BASE_BRANCH_MISSING / BASE_BRANCH_CHANGED	ベースブランチが存在しないか変更された	PR のターゲットを有効なベースブランチに変更してから再キューしてください
PR_MANUALLY_DEQUEUED	人間が削除した (コマンド、ダッシュボード、または API)	理由に誰がどのように削除したかが示されています。なぜ外されたかを把握してから再キューしてください
PR_DEQUEUED	キューの条件が一致しなくなった	レポート内の条件を確認し、PR を修正するか再キューしてください
DROPPED_BY_BISECTION_ELIMINATION	二分探索が他の PR を原因とみなし、この PR を未検証のまま外した	これは未証明であり、壊れていると判明しているわけではありません。単独でテストするために再キューしてください
STACK_PREDECESSOR_DEQUEUED	同じスタック内の先行 PR がデキューされた	先行 PR を修正し、スタックを再キューしてください
QUEUE_RULE_MISSING / CONFIGURATION_CHANGED	キュー中の PR の下で設定が変更された	.mergify.yml を修正し (mergify-config スキルを参照)、その後再キューしてください
INCOMPATIBILITY_WITH_BRANCH_PROTECTIONS	キューの設定がブランチ保護と衝突している	リポジトリのブランチ保護とキューの設定を整合させてください — 再キューだけでは解決しません
UNPROCESSABLE_PULL_REQUEST	Mergify が処理するにはチェック実行、コメント、またはファイルが多すぎる	PR を縮小してください

すべてのコードが PR のキュー離脱を意味するわけではありません。 以下の理由はチェックを中断するものであり、PR はキューのままです — これらをデキューとして扱わず、再キューもしないでください:

PR_AHEAD_DEQUEUED, BATCH_AHEAD_FAILED, PR_WITH_HIGHER_PRIORITY_QUEUED, MERGE_QUEUE_RESET, SCHEDULED_FREEZE_STATUS_CHANGED, SPECULATIVE_CHECK_NUMBER_REDUCED, INTERMEDIATE_RESULTS_SKIPPED, CHECKS_RETRIED, BATCH_SCOPES_CHANGED, SCHEDULE_BLOCKED_AHEAD_YIELDED, PR_CHECKS_STOPPED_BECAUSE_MERGE_QUEUE_PAUSE

これらは、離脱イベントの dequeue_code としてではなく、action.queue.checks_end イベントの abort_code として (aborted: true とともに) 届きます。また、チェック実行のタイトルは Dequeued — … ではなく Checks restarted — … または Checks aborted — … となります。「実際にキューから離脱したか」を判断する確実なテストは、merged: false を持つ action.queue.leave イベントであり、このリストのコードの有無ではありません。

キューの状態を確認する

mergify queue status を使うと、マージキューの現在の状態を確認できます。

• バッチ：まとめてテストされている PR のグループです。CI の状態と ETA が表示されます
• 形成中：PR を集めている途中のバッチです（○）。キュールール、スコープ（バリアの場合は all scopes）、ルールのバッチサイズに対して現在含まれている PR の数、開始予定時刻の最遅時刻が表示されます。形成中のバッチは、まだマージ順序上の位置を持ちません。ID がなく、CI も実行されず、バッチツリーにも含まれません。このバッチ内の PR を queue show で確認すると、Waiting for mergeability check... と表示されます
• 待機中の PR：キューに入っているものの、まだバッチに含まれていない PR です。優先度とキューに入った時刻が表示されます。形成中のバッチに含まれる PR は、代わりに「形成中」の下に表示されます。ただし、--json では引き続き waiting_pull_requests にも含まれます
• 一時停止状態：キューが一時停止中かどうかと、その理由です

出力をプログラムで解析する場合は、--json を使います。

キュー内の PR を調べる

mergify queue show <PR_NUMBER> を使うと、PR が停滞している理由や進行状況を確認できます。

• 位置：キュー内での PR の位置
• 優先度：一致した優先度ルール
• CI タイムアウト：キューが PR のチェックを打ち切る時刻（タイムアウトが設定されていない場合は -）。CHECKS_TIMEOUT が発生する前に気づけるよう、ここを確認してください
• CI の状態：チェックが成功、保留中、失敗のいずれか
• 条件：満たされている条件と、ブロックしている条件
• チェックの一覧表と条件ツリーをすべて表示するには、-v（詳細表示）を使います

-v で表示されるのはチェックの 名前と状態だけで、CI ジョブへのリンクはありません。キューにまだ入っている PR のジョブログ URL を確認するには、上記の GitHub 側の表示（チェック実行の概要とステータスコメント）を使ってください。PR がキューを離れた後は、queue show 自体に URL が表示されます。--json は API ペイロードをそのまま返すため、人間向けの表示では省略される追加フィールド queue_rule（名前だけでなく、解決済みのキュールール設定）も含まれます。

キューの状態

状態	意味
running	バッチの CI が実行中です
preparing	バッチを準備中です
bisecting	バッチが失敗し、原因を特定するために二分探索しています
failed	このバッチの CI が失敗しました
merged	このバッチの PR がマージされました
waiting_for_merge	CI は成功し、GitHub によるマージを待っています
waiting_for_previous_batches	先行するバッチの完了を待っているため、ブロックされています
waiting_for_batch	バッチに取り込まれるのを待っています
waiting_for_requeue	先行するバッチが失敗しました。このバッチは再度キューに入れられます
waiting_schedule	設定されたマージスケジュールの時間外です
frozen	キューは一時停止中です

一時停止と再開

インシデント対応中やデプロイ中などに、すべてのマージを一時的に停止するには、キューを一時停止します。

mergify queue pause --reason "production incident — halting merges"
mergify queue unpause

• 一時停止しても、実行中の CI はキャンセルされません。新たなマージの開始を防ぎます
• 理由はキューの状態に表示され、チームメンバー全員が確認できます
• スクリプトで確認プロンプトを省略するには、--yes-i-am-sure を使います

トラブルシューティング

PR がキューに入らない場合：

• PR がキューに追加されたことを確認します。@mergifyio queue を投稿し、Mergify がコメントに 👍 で反応したことを確認してください
• PR のマージ条件が満たされているか確認します：mergify queue show <PR_NUMBER> -v
• 条件のセクションで、満たされていない要件を確認します
• キューコマンドが実行されなかったと決めつけないでください。queue show では、キューに追加された後にキューから外された PR と、一度もキューに入らなかった PR を区別できます

PR がキューで止まっている場合：

• CI の状態を確認します：mergify queue show <PR_NUMBER>
• チェックに失敗している場合は、-v で失敗したチェック名を確認できます。ジョブログは、# Merge Queue Status コメントまたは Mergify Merge Queue チェック実行の概要にある Failing checks: のリンクから確認してください
• キューが一時停止している場合は、誰が一時停止したか確認します：mergify queue status

PR がキューから消えた場合：

• mergify queue show <PR_NUMBER> — PR がキューから外されたのか、キューによってマージされたのか、または一度もキューに入っていなかったのかが表示され、キューから外されたコード、理由、失敗したチェックの URL が出力されます
• 「マージキューにない」からといって「一度もキューに入っていない」と決めつけないでください。再度キューに追加するよう誰かに伝える前に、見出し（または --json の dequeued）を確認します
• その後、理由の表に従って対応します

キューの進行が遅い場合：

• 二分探索の原因となる失敗したバッチがないか確認します：mergify queue status
• バッチの二分探索では PR を個別にテストするため、バッチマージより時間がかかります