fix(docs): simplify ruleset bypass guidance to one recommendation

[kozlek]

The page explained how the three bypass modes interact with condition
injection, which a reader does not need in order to configure Mergify. It
also got that explanation wrong: it claimed exempt makes Mergify skip
injection, which is no longer what the engine does.

Say what to configure instead: add Mergify as a bypass actor and set the mode
to exempt, everywhere the page used to recommend always. That also covers
GitHub-native stacked pull requests, which need exempt specifically, so one
recommendation now fits every case.

Rename the section to "Bypass Actors" now that it no longer covers injection,
and point it at the step-by-step section further down.

Part of MRGFY-8578

[kozlek]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	fix(docs): simplify ruleset bypass guidance to one recommendation	#12362	👈
2	feat(docs): document Merge Queue support for GitHub-native stacks	#12361

[mergify]

Merge Protections

🟢 All 6 merge protections satisfied — ready to merge.

Show 6 satisfied protections

🟢 🤖 Continuous Integration

• all of:
  • check-success = build
  • check-success = lint
  • check-success = test
  • any of:
    • check-success = test-broken-links
    • label = ignore-broken-links
  • any of:
    • check-success=Cloudflare Pages
    • -head-repo-full-name~=^Mergifyio/

🟢 👀 Review Requirements

• any of:
  • #approved-reviews-by >= 2
  • author = dependabot[bot]
  • all of:
    • author = mergify-ci-bot
    • -head ~= ^docs-agent/

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:

🟢 🔎 Reviews

• #changes-requested-reviews-by = 0
• #review-requested = 0
• #review-threads-unresolved = 0

🟢 📕 PR description

• body ~= (?ms:.{48,})

🟢 🚦 Auto-queue

When all merge protections are satisfied, this pull request will be queued automatically.

[kozlek]

Revision history

#	Type	Changes	Reason	Date
1	initial	6525eed		2026-08-12 13:42 UTC
2	content	6525eed → a1c8491		2026-08-12 13:42 UTC
3	content	a1c8491 → c8cec50		2026-08-12 13:54 UTC
4	content	c8cec50 → 0714c93		2026-08-12 13:59 UTC
5	content	0714c93 → 7f215a4		2026-08-12 14:12 UTC
6	content	7f215a4 → 83b0f8d		2026-08-12 16:36 UTC
7	content	83b0f8d → f0af7cd		2026-08-12 16:48 UTC
8	content	f0af7cd → fd6c677		2026-08-12 17:02 UTC

[Copilot]

Pull request overview

This PR updates the GitHub Rulesets Compatibility documentation to reflect how Mergify behaves with GitHub ruleset bypass modes, especially for GitHub-native stacked pull requests that merge via GitHub’s stack merge API.

Changes:

• Rewrites the “Bypass Actors and Injection” guidance to recommend exempt and clarify how bypass mode relates to rule injection.
• Adds a new “Known Incompatibilities” entry explaining why stacked PR merges require exempt on applicable rulesets.
• Updates the “Configuring Mergify as a Bypass Actor” steps to align with the revised recommendation and cross-link the rationale.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Pull request has been modified.

[kozlek]

Removed that clause, and took the simplification further across the page per your steer — the reader should not need to know how the system works, only what to set.

• Bypass Actors section is now two sentences: add Mergify as a bypass actor, set the mode to exempt. The three-mode descriptions are gone.
• Step 5 of the setup steps is now just "Choose Exempt as the bypass mode."
• The GitHub-native stacks note drops the merge-API explanation and states the requirement plus what happens without it.
• Branch Name Pattern loses the pull_requests_only aside.
• always and pull_requests_only no longer appear anywhere on the page.

Two consequences worth knowing:

1. I renamed the section to Bypass Actors, since it no longer covers injection. That changes its anchor from #bypass-actors-and-injection to #bypass-actors. Nothing in the docs repo linked the old one, but the published configuration schema links it twice (https://docs.mergify.com/merge-queue/github-rulesets/#bypass-actors-and-injection), so those two fragments need updating engine-side. They still land on the right page in the meantime.

2. The page no longer says anything about what a bypass mode does to condition injection, in either direction. The incorrect claim is gone, which was the point, but so is the correction. Flagging in case support starts seeing "I set exempt, why are my conditions still enforced".

[mergify]

Queued — the merge queue status continues in this comment ↓.

[kozlek]

@Mergifyio queue

[mergify]

queue

🛑 The pull request cannot be checked because of an incompatibility with branch protections

Details

Mergify's bypass mode is not Exempt on repository rulesets Allow only Mergify and eng-mgr to update default branch, Do copilot_code_review on pull request, Require pull request for default branch. A GitHub stack is merged through GitHub's asynchronous Merge API, which honors only the Exempt bypass mode: an actor bypassing at Always or Pull requests only is evaluated as if it had no bypass at all, even though that same actor merges an ordinary pull request under the very same ruleset without trouble.
The fix is to set Mergify's bypass mode to Exempt on Allow only Mergify and eng-mgr to update default branch, Do copilot_code_review on pull request, Require pull request for default branch.

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-08-13 07:55 UTC · Rule: default · triggered by merge protections
• ✅ Checks passed · on draft merge queue: checking main (cee05bd) and #12362 together #12379
• ✅ Merged — 2026-08-13 08:00 UTC · at fd6c677afb46443e88ddd10fb16fe2084ac13373 · squash

This pull request spent 4 minutes 51 seconds in the queue, including 3 minutes 19 seconds running CI.

Required conditions to merge

• github-review-approved [🛡 GitHub repository ruleset rule Require pull request for default branch]
  • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
• schedule=Mon-Fri 09:00-17:30[Europe/Paris]
• all of [🛡 Merge Protections rule Enforce conventional commit]:
  • title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:
    • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
• all of [🛡 Merge Protections rule 👀 Review Requirements]:
  • any of:
    • #approved-reviews-by >= 2
      • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
    • author = dependabot[bot]
      • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
    • all of:
      • author = mergify-ci-bot
        • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
      • -head ~= ^docs-agent/
        • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
• all of [🛡 Merge Protections rule 📕 PR description]:
  • body ~= (?ms:.{48,})
    • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
• all of [🛡 Merge Protections rule 🔎 Reviews]:
  • #changes-requested-reviews-by = 0
    • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
  • #review-requested = 0
    • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
  • #review-threads-unresolved = 0
    • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
• all of [🛡 Merge Protections rule 🤖 Continuous Integration]:
  • all of:
    • check-success = build
    • check-success = lint
    • check-success = test
    • any of:
      • check-success = test-broken-links
      • label = ignore-broken-links
        • fix(docs): simplify ruleset bypass guidance to one recommendation #12362
    • any of:
      • check-success=Cloudflare Pages
      • -head-repo-full-name~=^Mergifyio/
        • fix(docs): simplify ruleset bypass guidance to one recommendation #12362