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.

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

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.