docs(agent): product-change watch — 2026-07-24 to 2026-08-07

[mergify-ci-bot]

🤖 Opened by the scheduled docs agent —
mission change-watch, scope change-watch.

This is a draft on purpose. Nothing in it has been read by a human
and every claim in it was written by a model. Read the diff, then mark it
ready for review. The agent that wrote this holds no GitHub credentials:
it cannot push, comment, approve or merge.

What I looked at

Product-change watch over 2026-07-24 → 2026-08-07, comparing what shipped against
what the docs say.

Sources, in the order the mission ranks them:

• Schema diff (primary signal): public/mergify-configuration-schema.json,
  public/api-schemas.json and public/cli-schema.json diffed from
  4b21236c (last commit before 2026-07-24) to HEAD. 555 insertions,
  788 deletions across the three files. I read it for added keys, removed keys,
  changed defaults, changed enums and changed descriptions, and diffed the API
  schema structurally (paths, methods, component schemas) rather than by text.

• Changelog (context only, read-only): the 7 entries in the window.

• Engine source for every claim the schemas did not settle: command
  restriction defaults, the from-fork attribute, queue-checking, the
  allow_queue_branch_edit validator and its migration, and the whole
  conflict-deferral path including its user-facing check-run copy.

The window's shape confirmed the method. Every one of the 7 changelog entries
is already covered by the docs — the Time Breakdown Avg/P95/Max selector and
the Batches Saved chart in merge-queue/monitoring.mdx, "No runner setup
required" in ci-insights/runners.mdx, the Depends On panel and
depends_on_pull_requests in merge-protections/builtin.mdx, the flaky-test
prevention and detection pages under test-insights/, and the github_actions
deprecation with its migration guide. All three fixes below came from the
schema diff, and none of the three has a changelog entry.

The API schema gained 8 component schemas and lost none; no path or method was
removed. The CLI schema changed only its version string.

What I changed

3 files, 142 lines added, 0 removed.

• src/content/docs/merge-queue/lifecycle.mdx — new "Conflicts with a Pull
  Request Ahead" section. A pull request that conflicts with one ahead of it is
  no longer dequeued on the spot: while the blocker is still queued, it is held,
  its check run reports deferred checks, and the status comment names the
  blockers. Evidence: the new action.queue.conflict_deferred event type and
  EventQueueConflictDeferred schema in api-schemas.json, plus the engine's
  deferral gate. The two outcomes (blocker leaves → checks resume; blocker
  merges → dequeued as a base-branch conflict) are taken verbatim from the
  engine's own check-run sub-bullets, which is also what corrected my first
  draft — I had written that the conflict usually resolves itself, which is
  backwards.

• src/content/docs/merge-queue/lifecycle.mdx — new "Queue Labels" section
  documenting checking_label alongside queued_label and dequeued_label.
  checking_label is new in the window (added to MergeQueue in the config
  schema, default null) and had no prose anywhere. Evidence: the schema, and
  the engine rule that toggles the label on the internal queue-checking
  attribute, which is true exactly while the pull request is attached to a
  batch.

• src/content/docs/commands/restrictions.mdx — prose for the "Default
  Restrictions" section, which was a bare generated table. The defaults for
  update, rebase, squash and refresh changed in the window: the author
  clause is now sender = {{author}} and from-fork rather than
  sender = {{author}}. Evidence: the four default blocks in
  CommandsRestrictionsRulesModel, and the engine's shared default-restriction
  helper. The page now explains why the fork clause is there (those commands
  rewrite the head branch, and a same-repository head branch is a branch of your
  repository) and shows how to opt back in. I wrote it as product behavior and
  rationale only — the engine's justification cites a private security report,
  which does not belong in published docs.

• src/content/docs/merge-queue/merge-strategies.mdx — new "Editing the
  Batch Branch" section. allow_queue_branch_edit: true now requires
  merge_method: merge-batch or merge_method: fast-forward and is rejected
  otherwise. Evidence: the expanded schema description on both QueueRuleModel
  definitions, and the engine's validator and its rejection message. Written
  dateless per the repo's rule against dated migration notices.

Proofreading pipeline ran (all five subagents, >10 lines changed). The technical
pass reversed one claim of mine and tightened two others; I re-verified both
reversals against the engine before keeping them. pnpm check,
pnpm check:config-examples (120 examples valid) and pnpm check:internal-leaks
(143 files, clean) all pass.

What I skipped and why

• Everything in the changelog. All 7 entries are already documented. Nothing
  to do — this is the reportable result, not an omission.

• from-fork as a condition attribute. It renders automatically in the
  generated <PullRequestAttributesTable /> on /configuration/conditions. I
  link to it from the restrictions page rather than duplicating it.

• The workflow field now accepting a numeric workflow id (github_actions
  action). Renders automatically in the generated ActionOptionsTable on the
  action's page.

• The queue-dequeue-reason enum restructuring and the
  x-has-data-type → x-mergify-has-data-type /
  x-enum-descriptions → x-mergify-enum marker rename. Presentation metadata
  for the docs site's own generated tables; this repo already switched to the
  namespaced markers in commit e6f51144. No enum value was added or removed.

• The queue_branch_merge_method description reversal (it used to say
  fast-forward "only works when merge_method is set to merge"; it now says
  the behavior applies whatever merge_method is). No docs prose mentions this
  deprecated key, so nothing was stale; the corrected text renders in the
  generated table.

• The rename-detection clarifications to files, added-files,
  modified-files, removed-files, scope and the scopes barrier filter.
  Already documented in configuration/conditions.mdx,
  merge-queue/scopes.mdx and merge-queue/scopes/file-patterns.mdx.

• batch_size gaining an explicit default: 1. The docs already describe
  batching as opt-in; no page claimed a different default.

• The ~30 configuration keys that render only in generated OptionsTables
  with no prose. Known debt, out of scope. I only wrote prose for the two keys
  that changed in this window.

NEEDS A HUMAN

1. Four command defaults were narrowed with no changelog entry. In
   public/mergify-configuration-schema.json, the default restriction for
   update, rebase, squash and refresh changed from
   ["sender-permission >= write", "sender = {{author}}"] (as an or) to
   or: [sender-permission >= write, and: [sender = {{author}}, from-fork]].
   The practical effect: a contributor with read-only access who opened a pull
   request from a branch of your own repository can no longer run these four
   commands on it. Nothing in src/content/changelog/ announces this. The
   engine's rationale is a security fix, so silence may well be deliberate — but
   it is a user-visible change to a default, and the decision on whether to
   announce it belongs to a human. The changelog is generated outside this
   repository and I cannot write to it. I have documented the new behavior on
   src/content/docs/commands/restrictions.mdx.

2. The checking_label description in the configuration schema is imprecise,
   and now disagrees with the docs page. The schema says the label applies
   "from the moment they enter a batch until they leave the queue". The second
   half is wrong: the engine toggles the label on the internal queue-checking
   attribute, which is true exactly while the pull request is attached to a
   batch. Any return to the waiting list — a conflict deferral, re-batching after
   a failure ahead, a queue reset — removes the label while the pull request is
   still queued. I wrote the accurate behavior into
   src/content/docs/merge-queue/lifecycle.mdx, but
   /configuration/file-format renders the schema's own wording in its
   generated MergeQueue table, so the same site now says two different things.
   The schema is synced in from outside this repository; the fix has to happen at
   the source.

3. allow_queue_branch_edit was silently turned off on existing
   configurations, with no changelog entry. The option now requires
   merge_method: merge-batch or merge_method: fast-forward. Configurations
   using it with merge, squash or rebase are not rejected — the engine
   migrates them by disabling the option, restoring the default behavior where an
   externally edited batch branch dequeues its pull requests and reports a
   failure. Anyone relying on it under those three merge methods has had that
   behavior change without being told, and there is no entry in
   src/content/changelog/. (The option was never doing anything useful there —
   the edit was already being dropped at merge time — but the dequeue it
   suppressed is a visible difference.) I documented the constraint on
   src/content/docs/merge-queue/merge-strategies.mdx.

4. Merge-queue conflict deferral shipped with no changelog entry. The API
   schema gained EventQueueConflictDeferred,
   EventQueueConflictDeferredMetadata and the
   action.queue.conflict_deferred event type, and the engine gained a whole
   deferral path: a pull request conflicting with one ahead of it in the queue is
   now held rather than dequeued. This is a behavior change to the merge queue's
   most user-visible failure mode and it is worth announcing. Nothing in
   src/content/changelog/ mentions it. I documented the behavior on
   src/content/docs/merge-queue/lifecycle.mdx.

5. from-fork is a new pull request condition attribute with no changelog
   entry. It was added to the attributes list in the configuration schema. It
   renders automatically in the generated attributes table, so there is no docs
   gap — but a new condition attribute is normally something users are told
   about, and this one is load-bearing for the default command restrictions in
   item 1.

6. Someone should decide whether the docs site documents dashboard UI at all.
   This window is unusually clean on that front — every dashboard-facing
   changelog entry (Time Breakdown percentiles, Batches Saved, the Depends On
   side panel, automatic runner tracking) already has prose. But that prose
   describes screens I cannot see, and I have no way to tell whether it still
   matches them. src/content/docs/merge-queue/monitoring.mdx in particular
   carries a Statistics page screenshot next to a widget list that has grown
   since; if the image predates the Avg/P95/Max selector or the Batches Saved
   chart, it now shows a page that no longer exists. I did not touch it and
   cannot verify it. Treat this as a shot-list item for whoever can log in.

[mergify]

Merge Protections

🔴 2 of 6 protections blocking · waiting on 👀 reviews

	Protection	Waiting on
🔴	👀 Review Requirements	👀 reviews
🔴	🔎 Reviews	👀 reviews
🟢	🤖 Continuous Integration	—
🟢	Enforce conventional commit	—
🟢	📕 PR description	—
🟢	🚦 Auto-queue	—

🔴 👀 Review Requirements

Waiting for

• #approved-reviews-by >= 2

This rule is failing.

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

🔴 🔎 Reviews

Waiting for

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

This rule is failing.

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

---

Show 4 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:
    • -head-repo-full-name~=^Mergifyio/
    • check-success=Cloudflare Pages

🟢 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)(?:\(.+\))?!?:

🟢 📕 PR description

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

🟢 🚦 Auto-queue

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

[jd]

needs proper PR title and body

[Copilot]

Pull request overview

Updates the Mergify documentation to reflect recent product behavior/configuration changes detected by the change-watch agent (merge queue behavior and labels, queue batch branch editing constraints, and updated default command restrictions).

Changes:

• Documented the allow_queue_branch_edit constraint and its implications when using merge-batch / fast-forward.
• Added merge-queue lifecycle guidance for “conflict deferral” and documented checking_label alongside existing queue labels.
• Added prose explaining the default commands_restrictions behavior for author-triggered commands on fork PRs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/content/docs/merge-queue/merge-strategies.mdx	Adds guidance for editing batch branches and required merge methods for allow_queue_branch_edit.
src/content/docs/merge-queue/lifecycle.mdx	Documents conflict deferral behavior and introduces the new checking_label queue label semantics.
src/content/docs/commands/restrictions.mdx	Explains default command restriction logic and provides examples for customizing author permissions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.