---
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 Mergify
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`.

:::caution
  While a `merge_queue` ruleset rule is active on `main` and Mergify is not a
  bypass actor on that ruleset, GitHub refuses every merge Mergify performs
  outside its own queue, and Mergify's queue reports a configuration error
  instead of merging. Either remove that rule from the ruleset, or add Mergify
  as a bypass actor with the `exempt` bypass mode, which lets Mergify merge
  directly while GitHub's queue stays active for everyone else. See [GitHub
  Rulesets Compatibility](/merge-queue/github-rulesets#github-native-merge-queue-rule).
:::

## 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

2. Add Mergify as a bypass actor with the `exempt` bypass mode on the ruleset
   carrying the `merge_queue` rule, so Mergify can merge while GitHub's queue
   stays active for everyone else

3. Queue a low‑risk PR using `@mergifyio queue`

4. Compare timing & merge behavior

5. Remove the `merge_queue` rule once satisfied and rely solely on Mergify

6. Layer in batching, priorities, additional rules

Rollback is a settings change: drop the bypass actor entry, or put the
`merge_queue` rule back if you already removed it, and every merge goes through
GitHub's queue again. Your branch protections and required checks are never
rewritten, so nothing has to be restored.

## 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. The `merge_queue` ruleset
rule is the exception, along with a handful of other rules the queue cannot work
under; [GitHub Rulesets
Compatibility](/merge-queue/github-rulesets#known-incompatibilities) lists them
and what to do about each.

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