Mergify Merge Queue

Mergify Merge Queue

Overview

The merge queue serializes PR merges, running CI on temporary merge commits to catch integration failures before they reach the target branch. Use the CLI to monitor queue state, inspect individual PRs, and manage the queue.

Commands

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        # Detailed state of a PR in the queue
mergify queue show  -v    # Full checks table and conditions tree
mergify queue show  --json # Machine-readable JSON output
mergify queue pause --reason "..."   # Pause the queue (requires reason)
mergify queue unpause                # Resume the queue

Checking Queue Status

Use mergify queue status to see the current state of the merge queue:

• Batches: groups of PRs being tested together, shown with their CI status and ETA
• Waiting PRs: PRs queued but not yet in a batch, shown with priority and queue time
• Pause state: whether the queue is paused and why

Use --json when you need to parse the output programmatically.

Inspecting a PR

Use mergify queue show to check why a PR is stuck or how it's progressing:

• Position: where the PR sits in the queue
• Priority: which priority rule matched
• CI state: whether checks are passing, pending, or failing
• Conditions: which merge conditions are met and which are blocking
• Use -v (verbose) for the full checks table and conditions tree

Queue States

| State | Meaning | | ------------------------------ | ------------------------------------------- | | running | Batch is actively running CI | | preparing | Batch is being set up | | bisecting | Batch failed, bisecting to find the culprit | | failed | CI failed for this batch | | merged | PRs in this batch have been merged | | waiting_for_merge | CI passed, waiting for GitHub to merge | | waiting_for_previous_batches | Blocked on earlier batches completing | | waiting_for_batch | Waiting to be picked up into a batch | | waiting_schedule | Outside the configured merge schedule | | frozen | Queue is paused |

Pausing and Unpausing

Pause the queue to temporarily halt all merges (e.g., during incidents or deployments):

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

• Pausing does not cancel running CI — it prevents new merges from starting
• The reason is visible to all team members in the queue status
• Use --yes-i-am-sure to skip the confirmation prompt in scripts

Troubleshooting

PR not entering the queue:

• Check that the PR's merge conditions are met: mergify queue show -v
• Look at the conditions section for unmet requirements

PR stuck in queue:

• Check CI state: mergify queue show
• If checks are failing, inspect the failing checks with -v
• If the queue is paused, check who paused it: mergify queue status

Queue moving slowly:

• Check for failing batches that trigger bisection: mergify queue status
• Bisecting batches test PRs individually, which is slower than batch merging

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: FlatbreadLabs
• Source: FlatbreadLabs/flatbread
• License: MIT

Install and usage instructions live in the source repository linked above.