diff --git a/src/content/docs/migrate.mdx b/src/content/docs/migrate.mdx index ceada6536f..756f5763b7 100644 --- a/src/content/docs/migrate.mdx +++ b/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. - Extend GitHub Merge Queue with automation, batching & observability. + Replace GitHub Merge Queue with automation, batching & observability. diff --git a/src/content/docs/migrate/github-merge-queue.mdx b/src/content/docs/migrate/github-merge-queue.mdx index 040c9d94f4..6ab36c8d76 100644 --- a/src/content/docs/migrate/github-merge-queue.mdx +++ b/src/content/docs/migrate/github-merge-queue.mdx @@ -60,7 +60,7 @@ 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. @@ -68,6 +68,16 @@ 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.