Merge pull request #11 from vyos/agents-md-T8595

T8595: add AGENTS.md + Copilot symlink for the vyos-org central Mergify baseline

2 files changed, 47 insertions, 0 deletions

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 120000
index 0000000..be77ac8
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1 @@
+../AGENTS.md
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1137785
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,46 @@
+# AGENTS.md
+
+## Project purpose
+
+Central [Mergify](https://mergify.com/) configuration baseline for the `vyos` (public) GitHub organisation. `.mergify.yml` here is referenced from every `vyos/<repo>/.mergify.yml` via `extends: mergify`. Holds shared defaults (notably `defaults.actions.backport.ignore_conflicts: true` with conflict labelling and author assignment), shared commands restrictions, and the PR title + commit-message format rule that replaces the GHA `check-pr-message.yml` workflow.
+
+Sibling — **not** twin — of [VyOS-Networks/mergify](https://github.com/VyOS-Networks/mergify). The two repos diverge in the PR-message rule shape and per-org annotations (see "Cross-repo context"); never blindly mirror changes across.
+
+## Tech stack
+
+- One YAML config (`.mergify.yml`) validated against `https://docs.mergify.com/configuration/file-format/`.
+- No build, no tests, no scripts. Default branch `production`.
+
+## Build / test / run
+
+No local execution. Validate edits with `yaml-language-server` (honours the in-file `$schema` directive) or by opening a draft consumer PR — Mergify re-reads the parent config on every event from a consumer repo.
+
+## Repository layout
+
+- `.mergify.yml` — the org-wide baseline.
+- `README.md` — minimal pointer; this file is the authoritative source.
+
+## Cross-repo context
+
+- Inheritance semantics (from `docs.mergify.com/configuration/sharing`):
+  1. Parent (this file) loads first; per-repo file is merged afterwards. Same-name rules in the child replace the parent's.
+  2. `defaults` and `commands_restrictions` are merged; remote defaults apply unless the child already sets the same key locally.
+  3. `shared` is NOT merged — define YAML anchors locally only.
+- **Divergences from [VyOS-Networks/mergify](https://github.com/VyOS-Networks/mergify):**
+  - PR-message format rule is implemented here as a **single rule with an `or:` condition** (title OR commit-message regex) so one `label: toggle` action manages the `invalid-title` label in both directions. The Networks side uses two separate rules pointing at the same label.
+  - Both shapes are functionally valid; the unified-rule shape is preferred here because Mergify's `toggle` docs frame the action as a single-rule pattern — two separate `toggle` rules on the same label can issue conflicting add/remove operations when one surface conforms and the other does not.
+  - All header comments reference `vyos/<repo>` consumer paths.
+
+## Conventions
+
+- Default branch: `production`. Visibility: public.
+- Commit / PR title format: `T<num>: <description>` (or `scope: T<num>: <description>`); this very rule is enforced by the rule defined in this file.
+- `defaults.actions.backport.ignore_conflicts: true` with `label_conflicts: backport-conflict` and `assignees: ["{{ author }}"]` — Mergify opens a conflict-workspace PR, applies the `backport-conflict` label, and assigns the source author for resolution. Silent merge is blocked via `merge_protections`. `ignore_conflicts: false` was tried first but eliminated the in-PR workspace; the current shape restores it while making the conflict impossible to miss. Driving incident: backport of vyos/vyos-documentation#1994 (2026-05-12).
+- Any change merged to `production` affects every consumer's next Mergify event immediately. No staging.
+
+## Notes for future contributors
+
+- Authority: [T8782](https://vyos.dev/T8782) (parent rollout), [IS-432](https://vyos.atlassian.net/browse/IS-432). Confluence: page `849477640`.
+- Rollback: `git revert` the offending commit, or empty the `pull_request_rules` / `defaults` sections — consumers fall back to per-repo `.mergify.yml` alone.
+- `unqueue` was removed from Mergify (replaced by `dequeue`) — never list it in `commands_restrictions`. Mergify's command set is split across two docs pages and the two lists differ; `requeue` is gateable in `commands_restrictions` but is not an end-user `@Mergifyio` command.
+- Caller authorization: `@Mergifyio` slash commands fire only when the comment author is a Maintainers-team member. Outside that team, commands are silently dropped. Multi-branch backports: one space-separated command (e.g. `@Mergifyio backport circinus sagitta`).