---
title: GitHub Rulesets Compatibility
description: How Mergify interacts with GitHub branch protections and rulesets, including known incompatibilities and how to resolve them.
---

Mergify automatically detects [GitHub branch
protections](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
and
[rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)
configured on your repository and injects the supported ones as conditions.
This page explains how that injection works, which ruleset rule types are
supported, which ones are incompatible with the merge queue, and how to
resolve conflicts.

## How Condition Injection Works

When Mergify processes a pull request, it reads the branch protection and
ruleset rules that apply to the target branch and converts them into
[merge conditions](/configuration/conditions). For example, if you require at
least one approved review, Mergify injects the condition
`#approved-reviews-by >= 1`.

This injection happens automatically for both the
[`merge`](/workflow/actions/merge) action and the merge queue. For the
merge queue, you can control how injection behaves using the setting below.

### Controlling Injection

You can control merge queue injection with the
[`branch_protection_injection_mode`](/configuration/file-format/#queue-rules)
option on your queue rules:

- **`queue`** (default) -- rules are injected as required conditions for
  both queuing and merging pull requests.

- **`merge`** -- rules are injected as merge conditions, checked after the
  queue has tested the pull request.

- **`none`** -- rules are not injected at all. This mode requires a
  `merge_bot_account` on the queue rule, since Mergify must merge with
  an account able to satisfy the protections itself.

### Bypass Actors

If you are using GitHub rulesets (not classic branch protections), add
Mergify as a **bypass actor** on the ruleset. The bypass mode you give it
decides what the merge queue may do:

- **`exempt`** covers everything, and is the only mode that works for
  [GitHub-native stacked pull
  requests](#github-native-stacked-pull-requests).

- **`always`** covers everything except GitHub-native stacked pull requests.

- **`pull_requests_only`** covers only what Mergify does through a pull
  request. The merge queue also creates, renames, pushes to, and deletes its
  own queue branches, and those are raw ref operations, so this mode still
  blocks the queue.

Choose `exempt` unless you have a reason not to. See [Configuring Mergify as
a Bypass Actor](#configuring-mergify-as-a-bypass-actor) for the steps.

### Bypass Actors and Injection

A bypass actor entry lets the merge queue work on your branches. Beyond merging
pull requests, the queue runs raw ref operations on its own queue branches,
which are prefixed with `mergify/merge-queue/` by default, so a ruleset that
covers those branches blocks the queue until you either narrow the ruleset so
it no longer matches them, or add Mergify as a bypass actor with the `exempt`
or `always` bypass mode. See [Bypass Actors](#bypass-actors) for what each mode
covers, and [Configuring Mergify as a Bypass
Actor](#configuring-mergify-as-a-bypass-actor) for the steps.

With the [`fast-forward` merge
method](/merge-queue/merge-strategies#fast-forward), Mergify advances the
target branch itself by a direct ref update, so a ruleset on that branch also
needs the `exempt` or `always` bypass mode. Narrowing the ruleset is not an
option there, since the branch the rules protect is the one being updated.

Bypassing is not injection. A bypass mode decides what GitHub lets Mergify
*do*; injection decides what Mergify *requires* before it merges, and the two
are set in different places:

- Injection reads every branch protection and ruleset that applies to the
  target branch and turns the supported rules into merge conditions.

- [`branch_protection_injection_mode`](/configuration/file-format/#queue-rules)
  is the only way to control it, and [Controlling
  Injection](#controlling-injection) covers its modes. It is set per queue rule
  and covers everything Mergify detects on the branch, so there is no way to
  turn injection off for one ruleset and leave it on for another.

If a rule should not gate your queue, take it out of the ruleset or scope the
ruleset so it no longer targets the branch.

:::caution
  Choosing `exempt` is not a way to keep a ruleset's rules out of your merge
  conditions, even though it is what lets Mergify bypass that ruleset on
  GitHub. `exempt` is also the only mode that works for
  [GitHub-native stacked pull requests](#github-native-stacked-pull-requests),
  so you may have to pick it for reasons that have nothing to do with injection.
  Control injection with `branch_protection_injection_mode`, or change the
  ruleset itself.
:::

### Required Reviewers

A `pull_request` ruleset rule can require approvals from specific teams or
users (the rule's **Required reviewers** setting). Mergify detects this and
injects the
[`github-require-review-from-specific-teams`](/configuration/conditions#attributes-list)
boolean condition, so a pull request is merged only once those approvals are
in.

The condition is `true` when every required reviewer is satisfied:

- each required **team** has at least the requested number of approvals from
  its members, and

- each required **user** has approved the pull request.

When the requirement is scoped to a subset of files (the ruleset's
`file_patterns` field), it only applies to pull requests that touch a matching
file. Other pull requests are unaffected.

You can also reference the condition explicitly in your `.mergify.yml`:

```yaml
queue_rules:
  - name: default
    merge_conditions:
      - github-require-review-from-specific-teams
```

:::note
  The condition evaluates to `false` if a ruleset entry points to a team or
  user that no longer exists, so the misconfiguration surfaces instead of
  being silently skipped. Fix the ruleset to remove the stale reviewer.
:::

### Require Approval of the Most Recent Push

When your branch protection or ruleset enables GitHub's *Require approval of the
most recent reviewable push* option (`require_last_push_approval`) and requires
at least one approving review, Mergify injects a matching
[merge condition](/configuration/conditions). A pull request is not merged
until its latest push has been approved by someone other than the person who
pushed it, so Mergify stays aligned with GitHub's own enforcement.

:::caution
  Mergify does not inject the condition when the same rule sets the required
  approval count (`required_approving_review_count`) to `0`. GitHub keeps
  blocking merges from anyone who cannot bypass the rule, but where Mergify
  bypasses it, as the [bypass actor](#bypass-actors) setup this page
  recommends, a pull request merges with an unapproved latest push.

  Requiring at least one approving review on the rule is what makes Mergify
  inject the condition. That also makes an approval mandatory on the pull
  requests the rule targets.
:::

## Ruleset Rule Compatibility

Mergify handles each GitHub ruleset rule type as follows.

| Ruleset rule type | Mergify behavior | Notes |
|---|---|---|
| `required_status_checks` | Injected as conditions | See [below](#require-branches-to-be-up-to-date) |
| `pull_request` | Injected as conditions | Required reviewers injected as [`github-require-review-from-specific-teams`](#required-reviewers). `require_last_push_approval` not always injected, see [above](#require-approval-of-the-most-recent-push). Limited code owner support. |
| `merge_queue` (GitHub native) | **Incompatible** | See [below](#github-native-merge-queue-rule) |
| `creation` | Checked when creating batch PRs | May block batch PR creation if Mergify is not a bypass actor |
| `update` | Checked when updating batch PRs | May block batch PR updates if Mergify is not a bypass actor |
| `branch_name_pattern` | Checked on queue branch creation/rename | See [below](#branch-name-pattern) |
| `required_review_thread_resolution` | Injected as conditions | -- |
| `required_signatures` | Checked on queue branch push | See [below](#required-signatures-and-branch-deletion) |
| `deletion` | Checked when queue branches are cleaned up | See [below](#required-signatures-and-branch-deletion) |
| All other rule types | Ignored | See [below](#ignored-rule-types) |

Mergify supports only the ruleset rule types named above. Every other rule
type is ignored: Mergify neither injects it as a condition nor checks it for
compatibility. Do not assume full ruleset parity. Enforce any
unlisted rule through GitHub directly.

:::caution
  Branch protection support has some limitations. For example, GitHub does
  not provide an API to support [code
  owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners),
  which makes it unreliable in certain circumstances.
:::

## Known Incompatibilities

### GitHub-Native Stacked Pull Requests

Merging [GitHub-native stacked pull
requests](/merge-queue/stacks#github-native-stacked-pull-requests) requires
the `exempt` bypass mode. With any other bypass mode, the merge queue refuses
the pull request.

**Resolution:**

- Set Mergify's bypass mode to **Exempt** on every ruleset that applies to
  the base branch.

### GitHub Native Merge Queue Rule

If the `merge_queue` ruleset rule (GitHub's built-in merge queue) is enabled
on the target branch and Mergify is **not** a bypass actor, GitHub blocks
Mergify from merging pull requests -- all merges must go through GitHub's own
queue.

**Resolution:**

- **Preferred:** disable the `merge_queue` ruleset rule on branches where you
  use Mergify's merge queue.

- **Alternative:** add Mergify as a bypass actor on that ruleset with the
  `exempt` bypass mode. This lets Mergify merge directly while GitHub's queue
  is still active for other actors.

### Branch Name Pattern

If a `branch_name_pattern` ruleset rule matches Mergify's queue branches and
Mergify is **not** a bypass actor with the `exempt` or `always` bypass mode,
GitHub blocks Mergify from creating or renaming queue branches. As a result,
Mergify cannot queue or merge pull requests targeting that branch.

Creating and renaming a branch are raw ref operations, which is why
`pull_requests_only` does not unblock them.

Mergify uses two branch prefixes for queue branches:

- `mergify/merge-queue/` -- the final queue branch (customizable via
  `queue_branch_prefix` in
  [`queue_rules`](/configuration/file-format/#queue-rules)).

- `tmp-mergify/merge-queue/` -- the temporary branch Mergify creates during
  setup before renaming it to the final name.

A ruleset that only covers the final prefix still allows the temporary
branch to be created but blocks the subsequent rename, producing the same
error.

**Resolution:**

- **Preferred:** add Mergify as a bypass actor on the ruleset with the
  `exempt` bypass mode.

- **Alternative:** narrow the ruleset pattern so it excludes both
  `mergify/merge-queue/*` and `tmp-mergify/merge-queue/*`. If you customized
  [`queue_branch_prefix`](/configuration/file-format/#queue-rules), substitute
  your prefix and its `tmp-` counterpart.

:::note
  Mergify also periodically deletes leftover queue branches that match these
  prefixes. See [Queue Branch
  Cleanup](/merge-queue/lifecycle#queue-branch-cleanup) for how branches are
  matched and an important caveat about naming your own branches.
:::

### Required Signatures and Branch Deletion

Mergify builds each queue branch locally and pushes it, then deletes it once
the batch is done. Both are raw ref operations, so a ruleset covering the
queue branch prefixes can stop the queue:

- A `required_signatures` rule rejects the push, because the commits Mergify
  composes locally are unsigned. Every queue attempt then fails on branch
  creation.

- A `deletion` rule stops Mergify from removing the final queue branch before
  recreating it, which leaves the queue stuck on that batch.

**Resolution:**

- **Preferred:** add Mergify as a bypass actor on the ruleset with the
  `exempt` or `always` bypass mode. `pull_requests_only` is not enough for
  either operation.

- **Alternative:** narrow the ruleset so it does not cover the queue branch
  prefixes.

### Require Branches to Be Up to Date

The `strict_required_status_checks_policy` setting (labeled *Require branches
to be up to date before merging* in the GitHub UI) is incompatible with
[parallel checks](/merge-queue/performance#parallel-checks) and
[batches](/merge-queue/batches) when using batch PR checks.

Mergify creates temporary batch PRs to test combined changes. The
original pull requests are merged after those checks pass, but GitHub
considers them "not up to date" because they were not the branches that were
tested. This setting blocks the merge.

:::note
  Disabling this setting does **not** mean Mergify tests outdated code.
  Mergify always updates pull requests against the latest base branch before
  testing.
:::

**Resolution:**

- **Preferred:** disable the *Require branches to be up to date before
  merging* setting.

- **Alternative:** add Mergify as a bypass actor on the ruleset with the
  `exempt` bypass mode.

- **Alternative:** use the [`fast-forward` merge
  method](/merge-queue/merge-strategies#fast-forward), which merges the queue
  branch directly and is not affected by this setting.

- **Alternative:** use [in-place checks](/merge-queue/batches#in-place-checks-no-batch-prs),
  which test PRs on their own branch without creating temporary batch PRs.

### Review Requirements and Fast-Forward

The `required_approving_review_count`, `require_code_owner_review`, and
`require_last_push_approval` ruleset rules are incompatible with the
[`fast-forward` merge method](/merge-queue/merge-strategies#fast-forward)
when using batch PR checks (the default for parallel checks and batches).

When Mergify uses batch PR checks, it creates temporary batch PRs
to test changes. These batch PRs do not carry the review approvals from the
original PRs, so GitHub blocks the fast-forward push if review requirements
are enforced.

**Resolution:**

- Add Mergify as a bypass actor on the ruleset that enforces review
  requirements, with the `exempt` bypass mode.

### In-Place Checks and Review Requirements

When using [in-place checks](/merge-queue/batches#in-place-checks-no-batch-prs)
(where Mergify tests a PR on its own branch),
the `pull_request` ruleset rules with review requirements on the PR's head
branch can block Mergify from checking the PR. If these rules are active and
Mergify is not a bypass actor, in-place checks will fail with an
incompatibility error.

**Resolution:**

- Add Mergify as a bypass actor on the ruleset that enforces review
  requirements on queue branches, with the `exempt` bypass mode.

## Ignored Rule Types

The following ruleset rule types are not processed by Mergify. They are
neither injected as conditions nor validated for compatibility. If these
rules are active on your branches, Mergify will not enforce them:

- `required_deployments`

- `required_linear_history`

- `non_fast_forward`

- Pattern and file rules (`commit_message_pattern`, `file_path_restriction`,
  `max_file_path_length`, `file_extension_restriction`)

- `workflows`

- `code_scanning`

If you rely on any of these rules, ensure they are enforced by GitHub
directly on your target branch.

## Configuring Mergify as a Bypass Actor

To add Mergify as a bypass actor on a GitHub ruleset:

1. Go to your repository **Settings > Rules > Rulesets**.
2. Select the ruleset you want to modify (or create a new one).
3. Under **Bypass list**, click **Add bypass**.
4. Search for the **Mergify** app and select it.
5. Choose **Exempt** as the bypass mode.
6. Save the ruleset.

Bypass actors are configured per ruleset, so repeat this on every ruleset
that applies to the branches you queue.