---
title: Migrate from GitHub Merge Queue to Mergify
description: Technical mapping of GitHub Merge Queue concepts to Mergify with added capabilities.
---

<IntegrationLogo src={githubLogo} alt="GitHub logo"/>

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.

:::tip[Need help?]

We've migrated many teams from GitHub Merge Queue. [Reach
out](mailto:support@mergify.com) and we’ll review your GitHub configuration and
propose an equivalent Mergify setup, plus quick wins (batching, priorities,
etc).

:::

## When to move beyond GitHub Merge Queue

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](/merge-queue/monitoring): 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

## Concept mapping

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

| GitHub Merge Queue | Mergify |
| ------------------- | ------- |
| Single queue per protected branch | One or more `queue_rules` with conditions |
| Merge Group (= test head + base) | [Batch](/merge-queue/batches), checked in place or on a draft pull request |
| Required status checks | `queue_conditions` using `check-success = <name>` |
| Strict update before merge | `update_method` (merge/rebase) + automatic refresh |

## Minimal equivalent configuration

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`](/commands/queue) to queue a pull request.

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

## Batching & parallelism

Increase throughput by validating multiple PRs together. Start conservatively:

```yaml
queue_rules:
  - name: main
    batch_size: 2
```

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

## Priorities

Enable urgent hotfix merges without draining the whole queue using
[priorities](/merge-queue/priority):

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

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

## Observability & reporting

The [Statistics page](/merge-queue/monitoring) 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](/merge-queue/two-step) (fast + full) to shorten average cycle time.

## Incremental migration strategy

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.

## FAQ

**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.