Merge Strategies

The merge_method option in your queue rules controls how Mergify merges pull requests into your base branch. Each method produces a different git history shape, with trade-offs between linearity, SHA preservation, and throughput.

queue_rules:
  - name: default
    merge_method: merge

Creates a merge commit joining the PR branch into the base branch. This is the default GitHub merge behavior.

• History: non-linear — the PR branch and base branch are visible as separate lines in git log --graph

• Merge commits: yes — each PR produces a merge commit on the base branch

• SHAs preserved: yes — original PR commits keep their SHAs

• Use case: most teams; simplest setup with no constraints on parallelism or batching

queue_rules:
  - name: default
    merge_method: squash

Squashes all PR commits into a single commit on the base branch.

• History: linear — one commit per PR on the base branch
• Merge commits: no
• SHAs preserved: no — a new commit is created
• Use case: teams that want a clean git log where one commit = one PR

queue_rules:
  - name: default
    merge_method: rebase

Replays each PR commit on top of the base branch, creating new commits with new SHAs.

• History: linear — no merge commits, individual commits are preserved

• Merge commits: no

• SHAs preserved: no — commits are recreated with new SHAs, so the PR branch ref won’t match the base branch

• Use case: teams that want linear history with individual commits visible, but don’t need SHA preservation

queue_rules:
  - name: default
    merge_method: fast-forward

Fast-forward merging advances the base branch ref directly to the tested commit(s) using the Git API instead of creating a merge via GitHub. The exact behavior depends on whether the queue operates in inplace or draft-PR mode.

The PR is rebased on top of the base branch, CI runs on the PR itself, and the base branch ref is fast-forwarded to the PR’s head commit.

In this mode, update_method must be set to rebase (the default). If a rebase update occurs, the commit SHAs on the PR will change — what fast-forward preserves are the SHAs of the PR branch at merge time.

• History: strictly linear — commits sit directly on the base branch

• Merge commits: none

• SHAs preserved: yes — the exact same commit SHAs from the PR appear on the base branch

Mergify creates a draft PR that combines the queued pull requests, runs CI on that draft, and then fast-forwards the base branch to the draft PR’s head commit.

Because the draft branch combines multiple PRs, the history may contain merge commits from folding each PR into the draft branch.

• History: linear at the base-branch level, but individual merge commits from combining PRs may appear

• Merge commits: possible — from combining PRs in the draft branch

• SHAs preserved: the final merged result is the exact SHA tested by CI

• commit_message_template must not be set — fast-forward preserves the original commits, so custom commit messages are not applicable

• Parallel mode is not supported — fast-forward is not compatible with scope-based parallel queues

• Use case: teams and OSS projects that care about commit identity and want the exact CI-tested code on their base branch

Inplace mode — strictly linear history with preserved commit SHAs:

merge_queue:
  max_parallel_checks: 1

queue_rules:
  - name: default
    merge_method: fast-forward
    batch_size: 1
    merge_conditions:
      - check-success = ci

Draft-PR mode — batching with fast-forward merge:

queue_rules:
  - name: default
    merge_method: fast-forward
    batch_size: 5
    merge_conditions:
      - check-success = ci

The update_method option controls how Mergify updates PR branches when they fall behind the base branch. Combining merge_method with update_method gives you additional control over your history shape.

queue_rules:
  - name: default
    merge_method: merge
    update_method: rebase

PRs are rebased on top of the base branch before being merged with a merge commit. This produces a history where individual commits are linear, but each PR is wrapped in a merge commit that marks the PR boundary.

• Use case: teams that want linear commits but also want merge commits as PR boundary markers in git log --graph

queue_rules:
  - name: default
    merge_method: rebase
    update_method: rebase

PRs are rebased to stay current, then rebased again at merge time. This produces a fully linear history with no merge commits, though SHAs will differ from the original PR branch.