GitHub Rulesets Compatibility

Mergify automatically detects GitHub branch protections and 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.

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. 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 action and the merge queue. For the merge queue, you can control how injection behaves using the setting below.

You can control merge queue injection with the branch_protection_injection_mode 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.

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.

• 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 for the steps.

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 for what each mode covers, and Configuring Mergify as a Bypass Actor for the steps.

With the fast-forward merge method, 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 is the only way to control it, and 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.

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

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

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

Mergify handles each GitHub ruleset rule type as follows.

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.

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

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.

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

• 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, substitute your prefix and its tmp- counterpart.

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.

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

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, which merges the queue branch directly and is not affected by this setting.

• Alternative: use in-place checks, which test PRs on their own branch without creating temporary batch PRs.

The required_approving_review_count, require_code_owner_review, and require_last_push_approval ruleset rules are incompatible with the fast-forward merge method 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.

When using in-place checks (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.

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.

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.