feat(stack): drop the Depends-On header once GitHub holds the stack

[jd]

With --github-native, mergify stack push registers the stack with
GitHub's Stacks API, and that registration is the dependency between
two pull requests. The <n> header the CLI writes on top
of it records the same edge a second time, in the copy users actually
read — so it is now left out.

Keyed off the registration, never off the flag. --github-native
degrades silently by design: native_stack::register returns None on
a 404 (old GHES, feature off for the repo), a chain with a hole in it,
or a stack below GitHub's 2-PR floor, and the push carries on as an
ordinary Mergify stack. Dropping the header on the flag alone would
leave those pushes with the edge recorded nowhere at all, and Mergify
reconstructs a stack from Depends-On chains
(engine/stacks/detection.py) — a mid-stack pull request would lose
the gate holding it behind its predecessor.

Registration happens after the bodies are written, so the removal is
optimistic and settled inside the same push: every header the upsert
skips is remembered, and pr_upsert::restore_depends_on writes it back
(body only, no base key) if the stack ends the push unregistered.
That path is fatal on failure — every other way this feature degrades
lands in the state a flag-off push produces, and a stack that is
neither registered nor chained would not.

Nothing writes Depends-On into a commit; it only ever existed in the
rendered PR description, so no commit message changes shape.

What still reads the header, checked against the engine rather than
assumed:

• stacks/detection.py walks CLI stacks by branch chain and the
  marker; its native counterpart stacks/github_native.py walks the
  mirrored stack object instead, and get_stack_predecessor_state
  unions the two. The native half is behind
  GITHUB_STACK_QUEUE_FOR_ORGS, but an org without that flag cannot
  merge a registered stack at all — merge_helpers keeps it off the
  merge-async path and GitHub 403s the classic endpoint for every
  member — so the marker there gates a merge that cannot happen.
• The queue's build_stack_groups and
  find_direct_open_successors_by_head_ref use head/base refs only.
• The browser extension reads its own mergify-stack-data comment.
• The stacks-analytics endpoint detects stack PRs by Change-Id (which
  we still write); only its bottom-vs-upper first-review split reads
  the marker, so native stacks will read as all-bottom there. Metrics
  skew on an opt-in flag, not a merge regression — worth its own fix.

MRGFY-8772

[mergify]

Merge Protections

🟢 All 6 merge protections satisfied — ready to merge.

Show 6 satisfied protections

🟢 🤖 Continuous Integration

• all of:
  • check-success=ci-gate

🟢 👀 Review Requirements

• any of:
  • #approved-reviews-by>=2
  • author = dependabot[bot]
  • author = mergify-ci-bot
  • author = renovate[bot]

🟢 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.

[Copilot]

Pull request overview

This PR updates mergify stack push --github-native so that when a stack is successfully registered with GitHub’s native Stacks API (i.e., GitHub itself holds the ordering), the CLI no longer writes the redundant Depends-On: header into PR descriptions; if registration ends up not happening, the same push restores the suppressed headers to preserve Mergify’s ordering signal.

Changes:

• Suppress Depends-On: rendering during PR upsert when --github-native is enabled, and restore suppressed markers if the stack ends the push unregistered.
• Add pr_upsert helpers to ensure restore renders from the same source used by the upsert (commit message vs existing PR body under --keep-pull-request-title-and-body).
• Update CLI help/docs and extend end-to-end tests to cover header suppression vs restoration behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
skills/mergify-stack/SKILL.md	Documents --github-native behavior change re: Depends-On: and restoration.
crates/mergify-stack/src/pr_upsert.rs	Adds shared description source selection and a body-only PATCH helper to restore Depends-On:.
crates/mergify-stack/src/native_stack.rs	Expands module docs to explain why ordering markers are suppressed for registered stacks.
crates/mergify-stack/src/commands/push.rs	Implements suppression tracking and conditional restoration based on registration outcome.
crates/mergify-cli/tests/stack_push_github_native.rs	Adds tests asserting marker presence/absence under registered vs unregistered outcomes.
crates/mergify-cli/src/snapshots/mergify__tests__cli_schema_golden.snap	Updates CLI schema snapshot to reflect updated --github-native help text.
crates/mergify-cli/src/main.rs	Updates --github-native flag help text to mention ordering + Depends-On: removal.

---

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

[jd]

Revision history

#	Type	Changes	Reason	Date
1	initial	393df6b		2026-08-20 12:33 UTC
2	content	393df6b → e0d7867	address review: correct the 're-rendered from the commit messages' claim for --keep-pull-request-title-and-body (module doc + SKILL.md), narrow description_source/restore_depends_on to pub(crate), an…	2026-08-20 12:33 UTC
3	rebase	e0d7867 → 9ed18bb (rebase only)	rebase onto main: picks up the h2 0.4.17 bump (#1778) that clears RUSTSEC-2026-0258, turning cargo-deny and ci-gate green. No change to this commit's own diff.	2026-08-21 20:07 UTC

[jd]

Pushed the review round: 393db6b→e0d7867.

• Docs claim corrected (module doc + SKILL.md). Both said bodies are "re-rendered from the commit messages every time", which --keep-pull-request-title-and-body contradicts. The conclusion that sentence supported still holds, but for a different reason: create_or_update_pr always renders through format_pull_description(description_source(&input), input.depends_on_number), which strips any existing Depends-On: and re-appends it from the resolved predecessor. The marker is recomputed from the stack every push rather than carried over from the source text, so a re-run settles a stack left neither registered nor chained whichever source the body came from. Both docs now say that and name both sources.
• description_source and restore_depends_on are pub(crate). Only caller is the push orchestrator; nothing outside the crate links against mergify-stack but mergify-cli.
• Renamed the two native-registration tests to depends_on_omitted_when_native_registration_succeeds and depends_on_restored_when_native_registration_does_not_happen. They already pinned both halves — no marker once GitHub holds the order, marker restored when registration did not happen — but under names that did not say so. The pair is the actual contract of this change, so the names now match.

cargo fmt --check, clippy --workspace --all-targets -D warnings, typos and the full workspace suite are green locally.

cargo-deny is red on RUSTSEC-2026-0258 (h2 unbounded empty DATA frames). That is inherited from main, not from this diff — no Cargo.lock, Cargo.toml or deny.toml change here — and #1778 fixes it. ci-gate is just the aggregate over it. Everything else is green.

[jd]

The two red checks here are not from this diff. cargo-deny fails on RUSTSEC-2026-0258 (h2 0.4.14, pulled in transitively through hyper), which is the state of main right now — this branch does not touch Cargo.lock. ci-gate is just the aggregate going red behind it.

#1778 bumps h2 to 0.4.17 and is already green and approved; once it lands, a rebase here turns both green. I am deliberately not duplicating the bump in this branch — two PRs rewriting the same Cargo.lock entry only buys a conflict.

Everything this PR owns is done: 19/21 checks green (including rust and live-tests), all four review threads answered and resolved.

[jd]

Rebased onto main: e0d7867→9ed18bb.

#1778 landed, so Cargo.lock now carries h2 0.4.17 and RUSTSEC-2026-0258 is gone — that was the only thing cargo-deny was red on, and ci-gate was just the aggregate behind it. The diff this PR owns is unchanged; the rebase also pulls in #1775.

cargo test -p mergify-stack -p mergify-cli is green on the rebased tree.

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-08-24 11:51 UTC · Rule: default · triggered by merge protections
• ✅ Checks passed · on draft merge queue: checking main (dee3261) and #1780 together #1783
• ✅ Merged — 2026-08-24 11:59 UTC · at 9ed18bbdb22c4d20e3f0386d96e21c06a7b45979 · squash

This pull request spent 7 minutes in the queue, including 6 minutes 39 seconds running CI.

Required conditions to merge

• github-review-approved [🛡 GitHub branch protection]
  • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
• github-review-approved [🛡 GitHub repository ruleset rule Require pull request for default branch]
  • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
• all of [🛡 Merge Protections rule Enforce conventional commit]:
  • title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:
    • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
• all of [🛡 Merge Protections rule 👀 Review Requirements]:
  • any of:
    • #approved-reviews-by>=2
      • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
    • author = dependabot[bot]
      • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
    • author = mergify-ci-bot
      • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
    • author = renovate[bot]
      • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
• all of [🛡 Merge Protections rule 📕 PR description]:
  • body ~= (?ms:.{48,})
    • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
• all of [🛡 Merge Protections rule 🔎 Reviews]:
  • #changes-requested-reviews-by = 0
    • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
  • #review-requested = 0
    • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
  • #review-threads-unresolved = 0
    • feat(stack): drop the Depends-On header once GitHub holds the stack #1780
• all of [🛡 Merge Protections rule 🤖 Continuous Integration]:
  • all of:
    • check-success=ci-gate