From 879b93c8e8ccdc84239c90a082d20bb1c0114ffb Mon Sep 17 00:00:00 2001 From: mergify-ci-bot Date: Mon, 17 Aug 2026 10:49:27 +0000 Subject: [PATCH] docs(agent): required_signatures and deletion rulesets are checked, not ignored --- src/content/docs/merge-queue/deploy.mdx | 2 +- .../docs/merge-queue/github-rulesets.mdx | 56 +++++++++++++++---- .../docs/merge-queue/scopes/file-patterns.mdx | 19 ++++--- src/content/docs/merge-queue/stacks.mdx | 4 +- 4 files changed, 61 insertions(+), 20 deletions(-) diff --git a/src/content/docs/merge-queue/deploy.mdx b/src/content/docs/merge-queue/deploy.mdx index 38125b6614..47cc9187d3 100644 --- a/src/content/docs/merge-queue/deploy.mdx +++ b/src/content/docs/merge-queue/deploy.mdx @@ -66,7 +66,7 @@ GitHub rulesets and provides the most consistent, automated workflow. ### How to Enable Exclusive Mode -1. Navigate to **Merge Queue > Deploy** in your Mergify dashboard. +1. Navigate to **Merge Queue > Deployment** in your Mergify dashboard. Deploy screen from Mergify dashboard diff --git a/src/content/docs/merge-queue/github-rulesets.mdx b/src/content/docs/merge-queue/github-rulesets.mdx index 0ae482be92..6891e6f3aa 100644 --- a/src/content/docs/merge-queue/github-rulesets.mdx +++ b/src/content/docs/merge-queue/github-rulesets.mdx @@ -37,15 +37,28 @@ option on your queue rules: queue has tested the pull request. - **`none`** -- rules are not injected at all. This mode requires a - `merge_bot_account` on the `queue` action, since Mergify must merge with + `merge_bot_account` on the queue rule, since Mergify must merge with an account able to satisfy the protections itself. ### Bypass Actors If you are using GitHub rulesets (not classic branch protections), add -Mergify as a **bypass actor** on the ruleset and set its bypass mode to -`exempt`. See [Configuring Mergify as a Bypass -Actor](#configuring-mergify-as-a-bypass-actor) for the steps. +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](#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](#configuring-mergify-as-a-bypass-actor) for the steps. ### Required Reviewers @@ -103,6 +116,8 @@ Mergify handles each GitHub ruleset rule type as follows. | `update` | Checked when updating batch PRs | May block batch PR updates if Mergify is not a bypass actor | | `branch_name_pattern` | Checked on queue branch creation/rename | See [below](#branch-name-pattern) | | `required_review_thread_resolution` | Injected as conditions | -- | +| `required_signatures` | Checked on queue branch push | See [below](#required-signatures-and-branch-deletion) | +| `deletion` | Checked when queue branches are cleaned up | See [below](#required-signatures-and-branch-deletion) | | All other rule types | Ignored | See [below](#ignored-rule-types) | Mergify supports only the ruleset rule types named above. Every other rule @@ -150,10 +165,13 @@ queue. ### Branch Name Pattern If a `branch_name_pattern` ruleset rule matches Mergify's queue branches and -Mergify is **not** a bypass actor with the `exempt` bypass mode, GitHub -blocks Mergify from creating or renaming queue branches. As a result, +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 @@ -184,6 +202,28 @@ error. matched and an important caveat about naming your own branches. ::: +### Required Signatures and Branch Deletion + +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. + ### Require Branches to Be Up to Date The `strict_required_status_checks_policy` setting (labeled *Require branches @@ -258,12 +298,8 @@ 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`) diff --git a/src/content/docs/merge-queue/scopes/file-patterns.mdx b/src/content/docs/merge-queue/scopes/file-patterns.mdx index fb64cb1954..ce8f86a129 100644 --- a/src/content/docs/merge-queue/scopes/file-patterns.mdx +++ b/src/content/docs/merge-queue/scopes/file-patterns.mdx @@ -41,9 +41,11 @@ In this example: - Documentation changes get the `docs` scope :::tip -Mergify will intelligently batch PRs with overlapping scopes together. For example, if PR1 affects -`python-api` and PR2 affects both `python-api` and `frontend`, they'll be batched together since -they share a common scope. + When filling a batch, Mergify picks the queued pull request whose scopes overlap the batch's + scopes the most, so changes to the same area of the repository tend to travel together. In + [parallel mode](/merge-queue/queue-modes) the grouping is stricter: pull requests are grouped by + their exact set of scopes, so a pull request scoped to `python-api` alone and one scoped to both + `python-api` and `frontend` go into different batches. ::: ## Pattern Syntax @@ -145,12 +147,15 @@ queue_rules: ``` With this configuration: -- PRs affecting only `frontend` will batch together -- PRs affecting `python-api` will batch together +- PRs affecting only `frontend` batch together +- PRs affecting `python-api` batch together +- PRs affecting `shared-config` batch with each other -- PRs affecting `shared-config` will batch with everything (since config affects all - services) +A scope name carries no special meaning, so `shared-config` does not batch with every other +scope just because it happens to hold shared files. To make a change to shared files affect +every scope, list those files under +[`barrier_files`](/merge-queue/scopes#declaring-a-pull-request-impacts-every-scope) instead. ## Important Behaviors diff --git a/src/content/docs/merge-queue/stacks.mdx b/src/content/docs/merge-queue/stacks.mdx index eea7a66800..86a0552c13 100644 --- a/src/content/docs/merge-queue/stacks.mdx +++ b/src/content/docs/merge-queue/stacks.mdx @@ -100,8 +100,8 @@ PR. For a stack `PR1 → PR2 → PR3`, commenting `@mergifyio queue` on PR3 enqueues PR1, PR2, and PR3 in the right order. While PR3 waits for its predecessors to -join the queue, its checks display the condition -`stack-predecessor-queued` as pending. That's the queue holding PR3 back +join the queue, its Summary check lists one pending `depends-on=` condition +per predecessor, each tagged `[stack]`. That's the queue holding PR3 back until PR1 and PR2 are queued ahead of it. :::tip