AGENTS.mdlast updated 2026-08-21
the merge policy of a repo, versioned inside it. one file, a handful of directives, read by the server at landing time — from the base commit, never from the branch asking to enter.
what this file is
AGENTS.md is the file agents already read to learn the house rules of a repo. kudu gives a few of its lines teeth: a quorumline and require-check lines become server-enforced policy. the rest of the file stays yours — roles, escalation paths, style notes, anything an agent should know. the server ignores what it does not recognize, and never executes any of it: the file is data.
what the server reads
| directive | enforced | effect |
|---|---|---|
quorum: N | yes | N distinct approvals required before a merge lands. digits only (quorum: two is ignored — the server does not guess words). 0 to 9; the first quorum line wins. : or =, any case, list bullets tolerated. |
require-check: provider/name, … | yes, fail closed | each entry names a check by its exact provider/name. the latest run of each must be green on the candidate sha, reported by a ci credential that is still active. a check that never reports blocks the merge forever — that is the point. |
require: … | declared | free-text intent. recorded, shown on the policy page, not enforced. use it for rules a human should hold you to. |
block: … | declared | same: displayed intent, no enforcement. |
bounds, so a pathological file cannot cost anything: lists are comma separated, 12 entries and 120 characters each at most; the server reads the first 64 kB and 500 lines. plural forms (requires:, require-checks:, blocks:) parse the same.
resolution rules
- no file, or no directive — platform default: quorum 0, the owner lands merges alone. the quorum is a commitment a repo makes itself; nothing is imposed.
- the file wins. a caller may request a quorum when opening a merge, and that request can only raise the bar above the default. the moment AGENTS.md declares a quorum — including an explicit
quorum: 0— the file is the policy and the request is ignored. rules are versioned and reviewed, not chosen per merge. - read errors fail closed. an unreadable AGENTS.md at landing time aborts the landing; it is never treated as "no policy". only a genuinely absent file falls back to the default.
- read at the base commit. the policy comes from the main the candidate would extend — a stale index cannot serve yesterday's rules, and your branch cannot propose its own.
a full example, annotated
the enforceable minimum is two lines:
check what the server actually resolved, for any repo: GET /api/repos/:owner/:name/policy answers with the applied quorum, the enforced checks, the declared lines, and the source it read them from.
changing the policy
edit the file, push a branch, open a merge — the change lands under the current policy, then governs the next merge. that is the security property, and it cuts both ways: raising quorum above what you can staff has no override today. if the reviewers of aquorum: 2 repo lose their tokens, nothing lands anymore, including the fix. declare a bar you can actually clear.
on this page
note
this reference matches the parser line for line. anything not listed here is prose: kept, displayed, never interpreted.