T8782: Document Depends-On built-in merge protection in central config

[andamasov]

Summary

Adds a documentation comment block above the existing merge_protections: block so contributors reading the central Mergify config can discover the Depends-On: PR-body feature without spelunking Mergify's built-in-protections docs.

The protection is built-in — Mergify parses Depends-On: lines from the PR description and blocks merge until every referenced PR has merged. No YAML is required to enable it, so this is a docs-only change.

What the block covers

• The three accepted reference syntaxes (#N, owner/repo#N, full PR URL)
• The same-org + Mergify-enabled-repo constraints (both vyos/* and VyOS-Networks/* have the Mergify app installed org-wide per data/github.md "GitHub App installations")
• The cross-branch @Mergifyio refresh caveat, quoted to match the wording in the Pull Request Dependencies Header section
• Hypothetical merge-queue interaction — explicitly marked theoretical, since no consumer repo in either org defines queue_rules as of 2026-05-15
• Explicit note that no condition attribute exposes dependency satisfaction (only the list of declared references), so pull_request_rules cannot label PRs by dependency state

Companion PR

To be mirrored byte-identical to VyOS-Networks/mergify in a paired PR. Same pattern as prior central-config pairs:

• vyos/mergify#7 + VyOS-Networks/mergify#5 (backport-conflict workspace)
• vyos/mergify#8 + VyOS-Networks/mergify#6 (auto-update opt-in)

Verification

• python3 -c "import yaml; yaml.safe_load(open('.mergify.yml'))" → OK
• Pre-push coderabbit review --base origin/production --agent → 0 findings
• Mergify Configuration-changed check on the PR head
• Adversarial review post-CodeRabbit-resolution (auto)

Backport

Not applicable — central config only lives on production.

🤖 Generated by robots

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 58c36204-ded2-41d7-bbd3-bc2b02248e8f

📥 Commits

Reviewing files that changed from the base of the PR and between bec48f5 and f6337de.

📒 Files selected for processing (1)

• .mergify.yml

📜 Recent review details

🧰 Additional context used

🔍 Remote MCP Context7

Additional Context Found

Based on my research of Mergify documentation and features, I've gathered relevant information to help with the PR review:

Mergify Depends-On Feature: Official Specifications

The Depends-On feature supports three reference syntaxes: #123, https://github.com/org/repo/pull/123, and org/repo#123. All referenced PRs must be in repositories with Mergify enabled and belong to the same organization. Cycles are ignored (a PR depending on itself or circular chains).

Mergify waits for the linked pull requests to be merged before merging any pull request with a Depends-On: header.

Cross-Branch Dependency Caveat (Critical Detail)

If the dependency happens between pull requests targeting different branches, the evaluation of the dependent will not be automatic. You might need to use the refresh command to make Mergify realize the dependency has been merged. This aligns with the PR's documented cross-branch @Mergifyio refresh caveat.

Merge Queue Interaction Context

If PR #3 depends on #1 and #2 succeeding, Mergify builds that speculative state and tests against it. This indicates Mergify's merge queue has built-in awareness of PR dependencies, though the PR author correctly notes this interaction is theoretical for VyOS repos (no queue_rules currently defined as of the PR date).

Built-in/Automatic Nature

These protections are automatically interpreted — no configuration required. This confirms the documentation-only nature of the PR—no functional configuration changes are needed for the Depends-On feature to work.

Key Review Observations

The documentation in this PR accurately reflects Mergify's official behavior: the three supported syntaxes, same-organization/Mergify-enabled constraints, cycle handling, and the cross-branch refresh requirement. The PR appropriately marks the merge queue interaction as theoretical since VyOS doesn't currently use queue_rules, and correctly notes that dependency satisfaction is not exposed as a condition for pull_request_rules labeling.

🔇 Additional comments (1)

.mergify.yml (1)

214-256: LGTM!

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Expanded configuration documentation with details on merge dependency syntaxes, constraints, and merge queue interactions.

Walkthrough

This PR adds a documentation-only comment block to .mergify.yml (lines 214–256) explaining the built-in Depends-On: PR dependency merge protection feature. The block documents supported syntax formats, constraints (same-org repositories with Mergify enabled), cycle and self-reference behavior, and merge-queue interactions. No functional configuration rules or behaviors are modified.

Changes

Mergify Depends-On Documentation

Layer / File(s)	Summary
Depends-On feature documentation .mergify.yml	Added a 43-line comment block explaining Depends-On: syntax, constraints, cycles, self-references, and merge-queue interaction before the merge_protections section.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title directly references the main change (documenting Depends-On feature) and ticket (T8782), clearly summarizing the primary objective.
Description check	✅ Passed	Description comprehensively explains the documentation-only change, covers all points in the block, references companion PR pattern, includes verification steps, and directly relates to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/trusting-wilbur-da436c

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[andamasov]

@copilot review

[Copilot]

@copilot review

Reviewed the current PR head (b1737bd) and re-validated the config parse (python3 -c "import yaml; yaml.safe_load(open('.mergify.yml'))"), with no additional changes needed. Screenshot: N/A (no UI changes in this PR).