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