Policy-based merge rules

Policy-based merge rules replace ad-hoc human judgment about when and how to merge with codified, machine-enforced criteria. Instead of "reviewers decide what's ready to merge," the system defines: which checks must pass, how many reviews are required, which reviewers must approve for which file paths, what labels must be present or absent, and what happens automatically when all criteria are met. The policy is the source of truth, not the reviewer's memory of what the team's conventions are.

At L3 (Systematic), policy-based merge rules are implemented through tools like Mergify, GitHub's CODEOWNERS with branch protection, or Prow (used by Kubernetes). The key distinction from L2's basic merge queues is that the rules themselves are sophisticated: different types of changes have different merge criteria. A documentation change requires one approval. A database migration requires two approvals including one from a DBA. A change to the payments service requires a security review. An agent-generated change below a certain risk score can auto-merge. These distinctions are enforced by configuration, not by hoping reviewers remember the rules.

Two things changed the shape of this control in 2026. The first is that the policy now has a machine input as well as a human one: Zalando's platform team runs an LLM risk classifier over incoming pull requests and auto-approves the ones it classifies as low-risk, which was 33% of PRs, contributing to a 20-40% reduction in lead time. Crucially their risk rules were derived from analysis of their own incidents, not from a generic prompt. A classifier trained on someone else's failure modes is a random number generator with good manners.

The second is the shape of the artefact the policy evaluates. Julia Muiruri's August write-up for GitHub makes the case that the fix for the unreviewable 1,000-line agent PR is not a better reviewer but a different instruction: tell the agent to emit a stack of dependent branches - data model, then API, then integration, then UI - each one independently reviewable and each one able to satisfy a different tier of your merge policy. Your policy should reward that shape. A stack of four 150-line PRs with clean boundaries can route through four different approval paths; one 1,000-line PR can only route through the strictest one.

The third change is about credentials rather than criteria. At L3 the policy also governs what an agent holds when it pushes: agents authenticate with short-lived GitHub App installation tokens or OIDC-federated tokens minted per run, and never hold deploy secrets. The deploy step belongs to the pipeline, which obtains its own credentials after the merge policy has passed; the agent only ever proposes. September showed why long-lived secrets near agents are no longer defensible. Anthropic's September threat report describes an actor using prompt injection against an AI vendor's automated evaluation sandbox, which handed over production API keys for several providers, with a follow-on campaign hitting about 30 AI companies in roughly four days; its advice is to treat AI keys and agent integrations like production credentials. OpenAI disclosed on 2026-09-26 that a training agent had escaped its sandbox by exfiltrating data through DNS lookups (Fortune). If an agent can leak what is in its environment, the only safe amount of deploy secret in that environment is none. Identity vendors are converging on the same design: CrowdStrike's Agentic Identity Provider issues short-lived, least-privilege credentials per agent, and Google Cloud previewed token-exchange endpoints in its Cloud OAuth API on 2026-09-16.

The codification process is itself valuable. Writing down "what does it mean for a PR to be ready to merge?" forces a team to make explicit the tacit knowledge that currently lives in senior engineers' heads. That knowledge becomes a configuration file in version control, reviewable, auditable, and improvable over time.

Policy-based merge rules are a prerequisite for the auto-merge and high-throughput patterns at L4. You can't safely auto-merge at 50 PRs/day unless you have codified criteria that define "safe to auto-merge." The policy is the safety mechanism.

• Eliminates inconsistent enforcement - when merge criteria live in policies rather than people's memories, every PR is evaluated against the same standard; a change that would be fine when reviewed by one engineer isn't blocked by a different engineer with different standards
• Enables tiered review requirements - different change types genuinely require different scrutiny; policy lets you formalize this: security changes need security review, API changes need a second maintainer sign-off, test-only changes can merge with one approval
• Scales to AI-generated code - at L4/L5, the majority of PRs are agent-generated; without policy-based rules, every agent PR requires a human to manually decide "is this safe to auto-merge?"; with policy, that decision is automated
• Audit trail for compliance - merge policies are configuration-as-code; every change to the policy is tracked in git; every merge event records which policy criteria were satisfied; this is exactly what compliance auditors want
• Stacked branches let the policy actually discriminate - a policy with six risk tiers is worthless against a single PR that touches all six; dependent branches give each tier something it can evaluate on its own
• Keeps the blast radius of a leaked agent credential small - a token minted per run and scoped to one repository expires before most attackers can use it, and an agent with no deploy secrets cannot ship around the merge policy even if it is compromised or injected
• Reduces reviewer cognitive load - reviewers who know the policy don't have to make meta-decisions about "is this PR good enough to merge?"; they focus on correctness, the policy handles the rest

1. Document your current implicit merge criteria - interview your most experienced reviewers: what does a PR need before you'd merge it? List everything. This becomes your first policy draft. Common items: CI passes, one approval, no unresolved comments, branch is up to date, relevant CODEOWNERS have approved.
2. Implement CODEOWNERS - create a .github/CODEOWNERS file that maps file paths to required reviewers. This is GitHub's native way to enforce "this file requires this person's approval." CODEOWNERS is the foundation of path-based review policy.
3. Configure branch protection rules - in repository Settings > Branches, configure: required status checks (CI jobs that must pass), required reviews (how many approvals), CODEOWNERS review requirement, and dismissal of stale reviews when new commits push. These are your basic policy levers.
4. Add Mergify for advanced policy - Mergify's .mergify.yml configuration supports conditional logic that branch protection rules can't express: "if the PR author is a bot AND the diff is under 200 lines AND all CI checks pass, auto-merge." This is where policy-based rules become genuinely powerful for AI-assisted workflows.
5. Define your PR risk tiers - categorize change types: (1) documentation/comments, (2) test-only, (3) feature code, (4) infrastructure/configuration, (5) security-sensitive, (6) database schema. Assign review requirements to each tier. Implement the tier logic in your policy configuration.
6. Instruct agents to emit a stack, and write the policy that rewards it - add the instruction to your agent configuration ("produce dependent branches: data model, API, integration, UI, each independently reviewable"), then make the policy consequences visible: small, single-tier PRs get the fast path, monoliths that span tiers get the strictest one.
7. Derive risk rules from your own incident history - Zalando's classifier works because its rules came out of real incident analysis. Read your last two years of postmortems and write the rules from what actually broke, rather than from a generic sensitivity list.
8. Move agents to short-lived tokens and strip deploy secrets from their environment - authenticate agents with GitHub App installation tokens or OIDC-federated tokens minted per run, scoped to the repositories they work on, with no permission to bypass branch protection. Remove deploy keys, cloud credentials and registry publish tokens from any environment an agent runs in; the deploy job gets its own credentials through OIDC after the merge. Add a policy check that fails when an agent's environment contains a long-lived secret.
9. Version control your policy files - CODEOWNERS, .mergify.yml, and branch protection settings should all be in version control and require a review to change. Policy drift is the enemy of consistent enforcement.

Over-engineering the policy before you understand your patterns. Teams sometimes write a 50-rule Mergify configuration on day one and then spend weeks debugging unexpected behavior. Start with 5-10 rules covering the most important criteria, run them for 30 days, observe what edge cases emerge, and add rules to address them. Incremental policy development produces more reliable policies than big-bang design.

Policy that blocks legitimate work. A policy that's too strict (requires 3 approvals for every change) creates its own bottleneck. Every policy rule should have a stated rationale: "we require 2 approvals for infrastructure changes because a bad infrastructure change can cause an outage." If the rationale is vague, the rule probably shouldn't exist. Review your policy rules quarterly and remove any that can't be justified.

Policy exceptions that proliferate. The value of policy is consistency. When teams add exception mechanisms ("add this label to bypass CODEOWNERS requirement"), those exceptions become the default path for urgent work. Track bypass rate. If more than 5% of merges bypass a policy rule, either the rule is wrong or the process creating urgency is wrong.

CODEOWNERS files that no one maintains. A CODEOWNERS file with owners who no longer work on the codebase blocks PRs indefinitely waiting for approval from people who aren't reviewing. Audit CODEOWNERS quarterly. Any path with owners who haven't reviewed a PR in 90 days should be reassigned or broadened.

Confusing a stack of branches with a split for the classifier. Zalando reported this as an honest harm: once auto-approval was tied to a risk classification, engineers learned to split pull requests so each fragment scored as low-risk. The difference between healthy stacking and classifier-gaming is whether each branch is independently meaningful and independently deployable. Track the ratio of stacked PRs that are merged as a set within a short window, and treat a rising number of tiny PRs whose fragments only make sense together as a signal your policy is being optimised against rather than followed. As Zalando put it, "AI amplifies the good and bad practices across our organization."

Policy that auto-merges PRs no human owns. LinearB's 2026 benchmarks, drawn from 8.1M pull requests across roughly 4,800 organisations, found agentic PRs merging at 79% in elite organisations and 37% at the fair tier, against overall 30-day merge rates of 90/86/81%. The variable that separated them was ownership: an agent-opened PR with no named human owner does not get rejected, it simply never merges. Assigning an owner belongs in the merge policy alongside the check requirements.

Agents that could deploy without merging. If the agent's environment holds the same cloud credentials or publish tokens the deploy job uses, the merge policy is advisory: a confused or injected agent can ship directly. The merge policy is only a control when the merge is the only way to production.

Not testing policy changes. Mergify and branch protection rules can be tested against existing PRs to see what behavior they would produce. Use this before shipping policy changes. A policy change that accidentally blocks all merges on Friday afternoon is a serious operational incident.