Migrate from GitHub Merge Queue to Mergify

GitHub’s native Merge Queue ensures each PR is tested against the latest base before merging. Migrating to Mergify keeps that guarantee while adding fine‑grained policies, batching strategies, real CI efficiency insights, and queue observability (latency, throughput, bottlenecks) in one system.

This guide shows a minimal, incremental migration: no rewrites, and you keep your branch protections and required checks exactly as they are.

Choose Mergify if you need any of:

• Multiple queue policies (e.g., different batch sizes / update methods per directory or label)

• Conditional enqueue rules (labels, file globs, author, commit message, path ownership)

• Explicit priorities (interactive hotfix elevation)

• Parallel speculative checks (reduce head‑of‑line blocking)

• Batching by size, with automatic splitting when a batch fails

• Queue metrics: queue time, CI runtime, batch outcomes, and where a pull request’s time in the queue goes

• Integrated workflow actions (label, rebase, backport, deployment gating) without extra bots

While Mergify offers more features, here is a mapping of existing GitHub Merge Queue features:

If today you rely on a protected main with a GitHub Merge Queue, no configuration is needed. Mergify automatically injects your ruleset or branch protections into the queue system. Type @mergifyio queue to queue a pull request.

This reproduces the same invariant: every PR merged only after re‑validation on the latest main.

Increase throughput by validating multiple PRs together. Start conservatively:

queue_rules:
  - name: main
    batch_size: 2

If a batch fails, Mergify automatically reduces scope and isolates the culprit PRs without manual intervention.

Enable urgent hotfix merges without draining the whole queue using priorities:

priority_rules:
  - name: critical
    conditions:
      - label = hotfix
    priority: high

Apply a hotfix label; those PRs jump ahead while fairness is preserved.

The Statistics page reports on the queue:

• Max Queue Size and Average Queue Time, for how deep the queue gets and how long a pull request waits in it

• Time Breakdown, splitting that wait across CI capacity, schedule windows, freeze periods, and CI runtime

• Batch Outcomes and Batch Bisection Count, for how often batches fail and have to be split

• Batches Saved, for batches that merged without running their own speculative checks

• Average CI Runtime, for how long the checks the queue triggers take

Use this data to tune batch size, break down monolithic checks, or add two‑step CI (fast + full) to shorten average cycle time.

1. If needed, add the .mergify.yml configuration file with a queue_rules block (leave GitHub Merge Queue enabled)

2. Queue a low‑risk PR using @mergifyio queue

3. Compare timing & merge behavior

4. Disable GitHub Merge Queue once satisfied and rely solely on Mergify

5. Layer in batching, priorities, additional rules

Rollback is trivial: toggle GitHub’s native queue back on; no destructive state.

Does Mergify require removing branch protections? No. Keep them; Mergify injects their conditions into the queue itself, so you do not have to restate them. Listing the same check in both a branch protection and queue_conditions is harmless: it does not make the check run twice.

Do I lose the merge squash/rebase options? No. Configure merge_method per rule; you can still vary merge strategies across PR subsets.

Is there vendor lock‑in? Config is a single YAML file; removal falls back to native GitHub behavior immediately.