CODEOWNERS Alternative
Beyond CODEOWNERS.
Review policy as code.
CODEOWNERS defines who owns files. CODEREVIEW.toml adds approval thresholds, request limits, team routing, and scoped rules.
About CODEOWNERS
What is a CODEOWNERS file?
A CODEOWNERS file tells your Git host who is responsible for specific files and directories in a repository. When a pull request changes files that match a pattern, the matching owners are automatically requested for review.
On GitHub, the file can live at .github/CODEOWNERS, in the repository root, or in docs/.
Bitbucket has a similar concept through its Code Owners feature in premium plans.
CODEOWNERS file syntax
The format is one rule per line — a glob pattern on the left, one or more GitHub usernames or team names (prefixed with @) on the right.
Lines starting with # are comments.
The last matching pattern wins, so more specific rules should go at the bottom of the file.
.github/CODEOWNERS
# Security team owns security-related files
src/core/security/** @security-team
config/tsec-*.json @security-team
# Frontend team owns UI code
src/components/** @frontend-team
src/styles/** @frontend-team
# General code — fallback owners
src/** @alice @bob @carol
How CODEOWNERS works
When a pull request is opened or updated, GitHub scans the changed files against the CODEOWNERS patterns from bottom to top. The last matching pattern determines who gets requested for review. If the matched owners include a team, all members of that team are notified.
CODEOWNERS can also enforce required reviews through branch protection rules — if an owner is matched, their approval is required before the PR can be merged. This is how most teams use CODEOWNERS to define code ownership on GitHub.
This works well for simple ownership mapping. But as teams grow and review requirements become more nuanced, CODEOWNERS hits its limits.
The problem
Where CODEOWNERS falls short
CODEOWNERS was designed for ownership, not review policy. Once you need more than "notify these people," you start working around it.
No approval thresholds
You can't require "2 of 4 security reviewers." CODEOWNERS assigns owners, but the approval count is a single repo-wide setting.
No request limits
Every listed owner gets assigned. If a scope has 8 owners, all 8 are requested — there's no way to request only 2.
No scoped rules
Security-critical paths and documentation use the same approval rules. There's no way to require stricter review for sensitive areas.
No author-based routing
If an owner opens the PR, their approval still counts (or doesn't, depending on repo settings). There's no per-scope author handling.
No alternates or backups
If an owner is on vacation, the PR stalls. CODEOWNERS has no concept of backup reviewers who can be escalated when needed.
Last-match-wins only
Only the last matching pattern applies. You can't have overlapping scopes where both security and general reviewers are required on the same file.
Comparison
CODEOWNERS vs CODEREVIEW.toml
The same security + general review scenario, expressed in both formats.
.github/CODEOWNERS
# Security
src/core/security/** @alice @bob @carol @dave
# General
src/** @alice @bob @carol @eve @frank
All 4 security owners assigned. No threshold. No backups. Same approval count for security and general code.
CODEREVIEW.toml
v5[[scopes]]
name = "security"
paths = ["src/core/security/**"]
reviewers = ["alice", "bob", "carol", "dave"]
require = 2
request = -1
author_value = 1
[[scopes]]
name = "general"
paths = ["src/**"]
reviewers = ["alice", "bob", "carol", "eve", "frank"]
alternates = ["grace"]
require = 1
request = 1
author_value = 1
Security requires 2 of 4. General requests only 1 reviewer. Author counts toward approval. Grace is a backup if needed.
What you get with CODEREVIEW.toml
| Feature | CODEOWNERS | CODEREVIEW.toml |
|---|---|---|
| File ownership by path | ✓ | ✓ |
| Auto-assign reviewers | ✓ | ✓ |
| Per-scope approval thresholds | — | ✓ |
| Request limits | — | ✓ |
| Overlapping scopes | — | ✓ |
| Author-based routing | — | ✓ |
| Alternate / backup reviewers | — | ✓ |
| Large-scale change rules | — | ✓ |
| Line-based ownership | — | ✓ |
| Reusable aliases | — | ✓ |
| Version controlled config | ✓ | ✓ |
Teams
Flexible reviewer groups and aliases
Define reusable groups at the top of your config and reference them across scopes. When team membership changes, update one place.
CODEREVIEW.toml
v5[aliases]
"$security" = ["alice", "bob", "carol", "dave"]
"$frontend" = ["eve", "frank", "grace"]
"$global-approvers" = ["alice", "bob"]
[[scopes]]
name = "security"
paths = ["src/core/security/**"]
reviewers = ["$security"]
require = 2
[[scopes]]
name = "ui"
paths = ["src/components/**", "src/styles/**"]
reviewers = ["$frontend"]
require = 1
request = 1
Migrate from CODEOWNERS in minutes
Point an AI coding agent at the PullApprove agent prompt and it will generate a CODEREVIEW.toml from your existing CODEOWNERS. No account required. Free for public repos, 14-day trial for private.