How to Use Mergify: The Beginner’s Guide (First Install, the Queue Rule, First Auto-Merge, the Conditions Lesson, and the Stacked-PRs Arc)

CodexFuse Team · 2026-11-02T07:12:48.194Z · 15 min read min read

Learn how to use Mergify in 2026: install the GitHub App, queue your first PR, write .mergify.yml conditions, split your CI into two steps, and queue whole stacked-PR chains — the beginner’s guide.

How to Use Mergify: The Beginner's Guide (First Install, the Queue Rule, First Auto-Merge, the Conditions Lesson, and the Stacked-PRs Arc)

Learning how to use Mergify is the fastest way to stop babysitting your pull requests. If your team's main branch keeps breaking because two green PRs were merged on stale code — the classic merge skew — a merge queue is the fix, and Mergify is the most feature-complete one you can add to a GitHub repository without changing how anyone writes code. This Mergify tutorial for beginners takes you from a fresh install to your first queued merge, then through the four lessons that trip up every newcomer: the queue rule (and the one ruleset step everyone misses), the difference between auto-merge and the queue, the conditions syntax, and the stacked-PRs arc.

Mergify works on top of the CI you already run — if your checks live in GitHub Actions, our beginner guide covers that setup first — and it speaks one language: a YAML file in your repo.

What Is Mergify, Exactly?

Mergify is a GitHub-only automation service that adds a merge queue, merge protections, workflow automation, and CI analytics to your repositories, installed as a GitHub App. The headline product is the merge queue: instead of merging PRs directly, PRs enter an ordered queue, where Mergify tests each one against the latest main — speculatively, in parallel batches — and merges only the ones whose checks pass on the exact code that will land. Its own tagline is "Stop breaking main — Mergify tests every pull request against the latest main before it merges."

Say the GitHub-only line once and move on: Mergify is a GitHub App. It does not support GitLab or Bitbucket. If your code lives anywhere else, this guide isn't for you.

What Do You Need Before You Start?

You need three things: a GitHub repository, a CI suite that already runs on pull requests (GitHub Actions, CircleCI, Jenkins — anything that reports checks to GitHub), and admin access to the repo so you can install an App and touch branch protection. Mergify does not replace your CI; it orchestrates it. A team of two merging five PRs a week will not feel the pain this solves — a team of ten merging twenty a day, where two green PRs landing back-to-back break main, will.

How Do You Install Mergify on Your Repo?

Installing Mergify takes about five minutes and needs no config file at first. From the Mergify dashboard, click Add Repository, which sends you to GitHub to install the Mergify GitHub App and pick which repositories it can access. Back on the dashboard's Repositories page, you check the boxes for the products you want per repo — Merge Queue, Merge Protections, Workflow Automation, CI Insights — and save. That is the whole install; a .mergify.yml file comes later, when you want batches, lanes, or custom rules.

The only step people skip — the number-one setup trap — is the ruleset bypass for the queue. Mergify offers two deployment modes: Hybrid Mode (the default, where manual merges and the queue coexist, no setup) and Exclusive Mode (only Mergify can merge, enforced via GitHub rulesets). For Exclusive Mode you must add Mergify to the ruleset's bypass list as "Exempt" — without it, GitHub's own protection rules block the queue from merging and nothing happens. The classic branch-protection alternative is Settings > Branches > "Restrict who can push to matching branches" with only the Mergify app selected. I say it once because it ends half of all first-day support threads: put Mergify in the bypass list.

How Do You Queue Your First PR?

You queue your first pull request with a comment, and nothing else. The five-minute arc:

1. Open any open pull request in the repo where you enabled Mergify.
2. In the comment box, type @mergifyio queue as the very first text of the comment — the command must start the comment, with a single space after @mergifyio; "Please @mergifyio queue" runs nothing. (All Mergify commands accept the @Mergifyio prefix, case-insensitive.)
3. Click Comment. Mergify acknowledges with a thumbs-up reaction and a bot reply.
4. Watch the PR enter the queue from the dashboard: Merge Queue shows a live "Batch · N PRs checking" view, and the "Mergify Merge Queue" check run on the PR records the outcome.
5. When the queue's merge conditions pass, Mergify merges the PR itself — with the strategy you configured — and posts the result.

By default anyone with write permission can run queue commands; commands_restrictions in the config can narrow that. The counterpart command is @mergifyio dequeue, which pulls the PR back out of the queue.

The Conditions Lesson: How Does .mergify.yml Work?

A .mergify.yml is a plain YAML file — your Mergify config — that turns your merge process into rules. Mergify queue rules live under the queue_rules key, which is the only key most beginners ever need. Mergify finds it in one of several locations — .mergify.yml, .mergify.yaml, .mergify/config.yml, .mergify/config.yaml, .github/mergify.yml, .github/mergify.yaml — and always reads it from the default branch. The keys you will touch first are:

• queue_rules — defines the queue: its queue_conditions (what lets a PR in), its merge_conditions (what lets a PR be merged), and its merge_method.
• pull_request_rules — Workflow Automation rules for everything that isn't the queue (labels, comments, auto-reviewers).
• merge_queue — queue-wide options like max_parallel_checks (default 5; set it to 1 to disable speculative checks).
• scopes — scope-aware parallel lanes for monorepos.

Here is a small real queue rule, from Mergify's own documentation, that batches up to 8 PRs into one CI run and merges when the build and test checks pass:

queue_rules:
  - name: default
    batch_size: 8 # one CI run can validate up to 8 PRs
    merge_conditions:
      - check-success = build
      - check-success = test
scopes:
  source:
    files:
      api:
        include:
          - services/api/**
      web:
        include:
          - apps/web/**

The merge strategy for a queue rule is set with merge_method: merge (merge commit, GitHub's default), squash, rebase, fast-forward (linear history that preserves SHAs, serial-only), or merge-batch.

What Is Two-Step CI and Why Does It Cut Your CI Bill?

Two-step CI is the feature that pays for Mergify. It splits your test suite into two steps: step 1 (preliminary) runs cheap, fast checks — linters, formatters, unit tests, compile checks — on every PR push and gates entry into the queue; step 2 (pre-merge) runs the expensive suite — integration, end-to-end, performance benchmarks — only when a PR enters the queue, gating the final merge.

Configuration has two halves. First, your pre-merge jobs run only on branches prefixed mergify/merge-queue/ — in GitHub Actions that's an if: startsWith(github.head_ref, 'mergify/merge-queue/') guard on the job (CircleCI and GitLab equivalents exist in the docs). Second, the queue rule splits its conditions:

queue_rules:
  - name: default
    queue_conditions:
      - check-success=preliminary-tests   # gates entry into the queue
    merge_conditions:
      - check-success=pre-merge-tests     # gates the final merge

The payoff is arithmetic: five PRs each with a 30-minute pre-merge suite cost 2.5 hours of CI when run per PR, but about 30 minutes when the queue validates them as one batch. If your CI jobs run in Docker containers, our Docker beginner guide is the companion read — two-step CI is where containerized test suites start paying for themselves. Teams that run their own CI runners usually put them on a VPS hosting box; if you don't have one yet, that guide explains the option.

What Is the Difference Between Auto-Merge and the Queue?

Auto-merge fires the moment a PR's last success condition is met, configured with auto_merge_conditions under merge_protections_settings (it can be unconditional or conditioned, e.g. author = dependabot[bot]); the queue orders PRs and re-tests each one speculatively against the latest main before merging. That's the whole distinction in one line: auto-merge is "merge as soon as it's ready," the queue is "merge as soon as it's ready and proven safe against everything ahead of it."

Two details matter. First, auto-merge feeds the queue: if the queue is enabled and the PR also matches queue_conditions, auto-merge adds it to the queue instead of merging directly. Second, auto-merge requires Merge Protections to be enabled — if you omit auto_merge_conditions, nothing automatic happens and you queue manually with @mergifyio queue.

The Stacked-PRs Arc: How Do You Queue a Whole Chain?

Stacked PRs are how large changes stay reviewable: a chain of small PRs, each building on the one below. With Mergify stacked PRs, one command on the top PR queues the entire chain — the members keep their order and ride in the same batch when it has room for them, and pulling one out pulls out everything above it. A "Queue this pull request" checkbox on a stacked PR acts exactly like commenting @mergifyio queue there. The command is cancelled if new commits are pushed, if you run @mergifyio dequeue, or if the PR closes.

There are two kinds of stacks. GitHub-native stacks are created with gh-stack or mergify stack push and registered with GitHub's stacking API (no body markers). Mergify Stacks use mergify stack push --no-github-native: one local branch where each commit maps to its own PR, chained via Depends-On: #N body markers. The CLI flow is:

brew install mergifyio/tap/mergify-cli   # or the curl install script
mergify stack new feat/my-feature
# make commits — each gets a Change-Id trailer
mergify stack push    # rebases on latest main, opens one PR per commit
mergify stack list    # check stack status

Stacks cap at 20 levels deep, and — the trap, said once — they require Mergify as the bypass actor with "Exempt" bypass mode on every ruleset covering the base branch, or the queue refuses the PRs. Stacks are also where your Git habits meet the tool, so our Git beginner guide is worth a refresher before you chain your first one.

What Does Mergify Cost in 2026?

Mergify's pricing is seat-based with one plan covering every product, read from mergify.com/pricing on 2026-11-02 (prices move — verify before you budget):

A "seat" is an active contributor: someone who opened a PR or pushed commits to one in the last 30 days. Inactive teammates, bots, and one-off contributors don't count, and the dashboard shows exactly who counts. If you're an early-stage startup (50 or fewer employees, new customer), the Startup Program offers up to $12,000 in credit for 12 months on up to 50 seats.

Mergify vs GitHub Merge Queue: Which Do You Need?

GitHub ships a native merge queue, free and included. Mergify's own comparison page (updated 2026-10-14) draws the line honestly:

The honest beginner rule: start with GitHub's native queue if your team is small and your CI is simple — it solves basic merge skew for free. Graduate to Mergify when queue restarts start eating your CI budget or your mornings. One historical note: Kodiak was one of the late-2010s merge-automation bots (alongside Bors, Homu, and Bulldozer) that solved merge skew before GitHub had a native queue — per Mergify's own origin-story post, it's a predecessor, not a current rival.

7 Beginner Mistakes (and the Fix for Each)

What Changed in Mergify in 2026?

Two threads are worth knowing. First, the State of Merge Queues 2026 report (July 2026) analyzed 200,000+ merges across 477 organizations and found that AI-assisted PRs broke main about half as often as human ones (1.9% vs 4.4%), that the broken-main rate scales roughly 16x with team size, and that private code breaks main 4.5x more often than open source. Second, the product shipped for the agent era: an isolated queue mode (June 2026, trades the cross-batch conflict check for speed), dynamic batch sizing (July 2026 — the queue widens under load, shrinks when quiet, via batch_size: {min: 1, max: 10}), a "Fix with Mergify" LLM button that repairs a broken .mergify.yml and opens the fix as a PR, and auto-freeze on deploy failure (a GitHub Actions job freezes the queue the moment any deploy scope fails). The theme of the July 2026 engineering post says it plainly: merge queues were built for humans, and AI agents need more — batch sizing and flaky handling are where the queue earns its keep now.

Sources

• Mergify documentation — merge-queue quick start, deployment modes (Hybrid vs Exclusive), configuration file format, commands reference, merge strategies, monitoring, stacks, two-step CI, auto-merge, performance/speculative checks: docs.mergify.com (fetched 2026-11-02)
• Mergify product page — merge-queue FAQ, 5-minute setup, Max pricing $21/seat/month or $216/seat/year, 14-day trial: mergify.com/product/merge-queue (page updated 2026-10-16, fetched 2026-11-02)
• Mergify pricing page — Free/Open Source $0, Max, Enterprise custom, seat-billing definition, retention tiers: mergify.com/pricing (fetched 2026-11-02)
• Mergify comparison hub — GitHub native merge queue comparison, feature table: mergify.com/compare/github-merge-queue (page updated 2026-10-14, fetched 2026-11-02)
• Mergify Startup Program — up to $12,000 credit, 12 months, 50 seats: mergify.com/startups (fetched 2026-11-02)
• Mergify blog — State of Merge Queues 2026 report (2026-07-27), isolated queue mode (2026-06-17), dynamic batch sizing (2026-07-06), "Fix with Mergify" LLM button (2026-06-05), auto-freeze on deploy failure (2026-06-24), the origin story of merge queues: mergify.com/blog (fetched 2026-11-02)
• Mergify vendor blog — pull-request automation walkthrough (1314 days old) and Tutorialspoint — "How to use mergify to automate merging pull requests" (auto-merge angle, no queue arc): SERP checks 2026-11-02

Frequently Asked Questions

Is Mergify free?

Yes, for open-source projects and for private teams with up to five active contributors — that's the Free/Open Source tier at $0. Bigger teams pay the Max plan: $21 per seat per month or $216 per seat per year, with a 14-day trial that needs no credit card. A "seat" only counts contributors who opened a PR or pushed commits in the last 30 days — bots and inactive teammates are free.

Does Mergify work with GitLab or Bitbucket?

No. Mergify is a GitHub-only product, installed as a GitHub App. GitHub Enterprise Server is supported only through the on-premise Enterprise plan; there is no GitLab or Bitbucket integration at all.

What's the difference between @mergifyio queue and auto-merge?

@mergifyio queue is a comment command that manually puts one PR into the merge queue; auto-merge is a configured rule (auto_merge_conditions) that fires the moment a PR's conditions are met, merging it directly — or adding it to the queue if the queue is enabled. Use the command for manual control, auto-merge for bot-authored PRs like dependency updates.

Why is my PR stuck in the Mergify queue?

The three usual causes: the PR doesn't match the queue's queue_conditions (check the "Mergify Merge Queue" check run), Mergify isn't in the ruleset bypass list as "Exempt" so it can't merge, or a required check from a previous batch is still running. The dashboard's queue view shows exactly where a PR is waiting.

Can I use Mergify with GitHub's native merge queue at the same time?

Not meaningfully — Mergify's Exclusive Mode replaces the native queue per repository, and the native queue's one-CI-run-per-PR model conflicts with Mergify's batching. Pick one: the native queue for small teams and simple CI, Mergify when batching, scopes, two-step CI, or stacked-PR chains matter.