merge queue: checking #12748 on main (4b828c1)

src/content/docs/migrate.mdx

@@ -16,7 +16,7 @@ Thinking about switching? Pick your current tool below to see how to migrate to
 		Replace Bors queues and try/staging flows with Mergify Merge Queue.
 	</Docset>
 	<Docset title="GitHub Merge Queue" path="/migrate/github-merge-queue" icon="simple-icons:github">
-		Extend GitHub Merge Queue with automation, batching & observability.
+		Replace GitHub Merge Queue with automation, batching & observability.
 	</Docset>
 </DocsetGrid>
 

src/content/docs/migrate/github-merge-queue.mdx

@@ -60,14 +60,24 @@ Queue features:
 
 ## Minimal equivalent configuration
 
-If today you rely on a protected `main` with a GitHub Merge Queue, no
+If today you rely on a protected `main` with a GitHub Merge Queue, no Mergify
 configuration is needed. Mergify automatically injects your ruleset or branch
 protections into the queue system. Type [`@mergifyio
 queue`](/commands/queue) to queue a pull request.
 
 This reproduces the same invariant: every PR merged only after re‑validation on
 the latest `main`.
 
+:::caution
+  While a `merge_queue` ruleset rule is active on `main` and Mergify is not a
+  bypass actor on that ruleset, GitHub refuses every merge Mergify performs
+  outside its own queue, and Mergify's queue reports a configuration error
+  instead of merging. Either remove that rule from the ruleset, or add Mergify
+  as a bypass actor with the `exempt` bypass mode, which lets Mergify merge
+  directly while GitHub's queue stays active for everyone else. See [GitHub
+  Rulesets Compatibility](/merge-queue/github-rulesets#github-native-merge-queue-rule).
+:::
+
 ## Batching & parallelism
 
 Increase throughput by validating multiple PRs together. Start conservatively:
@@ -118,24 +128,35 @@ Use this data to tune batch size, break down monolithic checks, or add
 ## Incremental migration strategy
 
 1. If needed, add the `.mergify.yml` configuration file with a `queue_rules`
-   block (leave GitHub Merge Queue enabled)
+   block
+
+2. Add Mergify as a bypass actor with the `exempt` bypass mode on the ruleset
+   carrying the `merge_queue` rule, so Mergify can merge while GitHub's queue
+   stays active for everyone else
 
-2. Queue a low‑risk PR using `@mergifyio queue`
+3. Queue a low‑risk PR using `@mergifyio queue`
 
-3. Compare timing & merge behavior
+4. Compare timing & merge behavior
 
-4. Disable GitHub Merge Queue once satisfied and rely solely on Mergify
+5. Remove the `merge_queue` rule once satisfied and rely solely on Mergify
 
-5. Layer in batching, priorities, additional rules
+6. Layer in batching, priorities, additional rules
 
-Rollback is trivial: toggle GitHub’s native queue back on; no destructive state.
+Rollback is a settings change: drop the bypass actor entry, or put the
+`merge_queue` rule back if you already removed it, and every merge goes through
+GitHub's queue again. Your branch protections and required checks are never
+rewritten, so nothing has to be restored.
 
 ## FAQ
 
 **Does Mergify require removing branch protections?** No. Keep them; Mergify
 injects their conditions into the queue itself, so you do not have to restate
 them. Listing the same check in both a branch protection and `queue_conditions`
-is harmless: it does not make the check run twice.
+is harmless: it does not make the check run twice. The `merge_queue` ruleset
+rule is the exception, along with a handful of other rules the queue cannot work
+under; [GitHub Rulesets
+Compatibility](/merge-queue/github-rulesets#known-incompatibilities) lists them
+and what to do about each.
 
 **Do I lose the merge squash/rebase options?** No. Configure `merge_method` per
 rule; you can still vary merge strategies across PR subsets.