Policy-based merge rules

Policy-based merge rules replace ad-hoc human judgment about when and how to merge with codified, machine-enforced criteria.

·Policy-based merge rules are enforced (OPA, branch protection, or equivalent)
·Deterministic merge ordering with conflict detection prevents concurrent merge failures
·PRs require a maximum of 2 CI rounds before merge (Stripe benchmark)

·Merge rules are versioned as code and reviewed when changed
·PRs exceeding 2 CI rounds are flagged for investigation

Evidence

·Policy-as-code configuration (OPA rules, branch protection API config)
·CI round count per PR metrics showing 2-round maximum adherence
·Merge ordering logs showing deterministic processing

What It Is

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.

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.

Why It Matters

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

Getting Started

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

Tip

Start simple and add complexity incrementally. A policy with 20 rules that people don't understand is worse than a policy with 5 rules that everyone knows. Ship your first policy as a minimum viable configuration covering your three highest-priority concerns (usually: CI must pass, required reviewers per path, no self-merge). Add rules as you observe gaps.

6 steps to get from here to the next level

Common Pitfalls

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.

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob has different standards for different change types but no way to enforce them consistently. Security-adjacent changes are supposed to require a security review, but sometimes they slip through without one because the reviewer didn't notice the change touched authentication code. Bob has no visibility into whether his team's merge policies are actually being followed.

What Bob should do: Bob should start by auditing the last 90 days of merges for security-adjacent changes (any PR that touches src/auth/, src/payments/, or config/security.yml). How many were reviewed by someone with security expertise? How many were not? This audit converts "we probably have a policy gap" into "we have a measurable gap in N% of security changes." From there, Bob should commission a CODEOWNERS implementation for high-risk paths and a Mergify rule that blocks merge on those paths without the required reviewer. A one-sprint investment in policy infrastructure delivers ongoing audit compliance.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah wants to understand the variance in PR cycle time across the team. She sees that some PRs merge in 2 hours and others take 3 days, and can't explain the difference. Her hypothesis is that the variance comes from inconsistent application of review criteria.

What Sarah should do: Sarah should tag the last 90 days of PRs by change type (documentation, feature, infrastructure, security) and compare cycle time by category. If security PRs take 3x longer than feature PRs, the question is: is that appropriate (security review takes longer) or wasteful (security reviewers don't know they're needed until someone asks)? Policy-based rules solve the second problem: CODEOWNERS automatically routes security PRs to the right reviewers at PR open time, eliminating the 24-hour lag between "PR opened" and "right reviewer notified." Sarah should quantify the notification lag and present it as the latency that policy automation eliminates.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor has been writing Mergify configurations for his own repositories and knows the tool deeply. He wants to implement a tiered auto-merge policy: agent-generated PRs that touch only test files can auto-merge; agent-generated PRs touching source code require one human approval; agent-generated PRs touching infrastructure require two approvals. This would let his parallel agent setup ship more work without manual per-PR approval.

What Victor should do: Victor should implement the tiered auto-merge policy as a working prototype on a non-critical service, run it for 30 days, and measure: how many PRs auto-merged? How many auto-merged PRs caused issues? How much review time was saved? The data from the pilot is the proposal to the team. Victor should also document the Mergify configuration as a template: other teams can adopt the same tiered policy for their agent workflows by copying the config and adjusting the path patterns. Making the pattern reusable is how a single prototype becomes a team-wide standard.

What Victor should do - role-specific action plan