--- 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 them 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`** -- no injection at all. This mode requires a [`merge_bot_account`](/configuration/file-format/#queue-rules) with at least maintain permission. Use this only if you manage all conditions explicitly in your Mergify configuration. ### Bypass Actors and Injection If you are using GitHub rulesets (not classic branch protections), you can add Mergify as a **bypass actor** on the ruleset. The bypass mode determines whether injection still happens: - **`always` bypass mode** -- Mergify can bypass the rules, but it still injects them as conditions in your queue. - **`pull_requests_only` bypass mode** -- Mergify can bypass the rules only in the pull request context, not for direct pushes. This means Mergify can bypass when merging PRs but not when performing fast-forward pushes. - **`exempt` bypass mode** -- Mergify skips injection entirely for that ruleset. Use this when you want Mergify to ignore specific ruleset rules. ## 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 | Limited code owner support | | `required_deployments` | Used by [Merge Protections](/merge-protections) | -- | | `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 | | `required_review_thread_resolution` | Injected as conditions | -- | | All other rule types | Ignored | See [below](#ignored-rule-types) | :::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 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 `always` bypass mode. This lets Mergify merge directly while GitHub's queue is still active for other actors. ### 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/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 `always` 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/parallel-checks#inplace-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 `always` bypass mode. ### In-Place Checks and Review Requirements When using [in-place checks](/merge-queue/parallel-checks#inplace-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 `always` 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_linear_history` - `required_signatures` - `non_fast_forward` - `deletion` - 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 the bypass mode: - **Always** -- Mergify can bypass the rules but still injects them as merge conditions (recommended for most cases). - **Pull requests only** -- Mergify can bypass the rules in the pull request context only, not for direct pushes (e.g., fast-forward). - **Exempt** -- Mergify bypasses the rules **and** skips injecting them as conditions. Use this when you want Mergify to fully ignore specific rules. 6. Save the ruleset. :::tip If you only want to exempt Mergify from specific rules (e.g., `merge_queue`) but still enforce others (e.g., `required_status_checks`), create separate rulesets for each group and set different bypass modes. :::