Programmatic Codeowners Edits

Jordon Peterson released codeowners-tool v1, a programmatic tool for making safe, provable edits to GitHub CODEOWNERS files across 100+ repositories, including regulated environments. The tool treats ownership as a property of files rather than lines, validates policies as JSON, and refuses to write anything it cannot prove correct against the repo's actual files. It supports github.com and GitHub Enterprise Server, and is available via Homebrew, CI actions, and other installation methods.

Make safe, provable changes to GitHub CODEOWNERS files — in one repo, or across a hundred. Designed for rolling out programmatic CODEOWNERS changes across 100+ repositories, including regulated environments. This enables: - platform teams to control platform-owned files - AI agents to self-approve specific files when GitHub's required CODEOWNERS review setting is enabled Behavior is covered by an extensive edge-case test suite. The problem. CODEOWNERS is written in lines , but what anyone cares about is who owns which file . The two are connected by rules that surprise people: the last matching line wins, and owner sets don't combine — appending /x/ @team-2 replaces the owners of /x/ , it doesn't add to them. So you write down the ownership you want — " @org/platform should co-own /services/api/ " — and this tool works out the lines, checks its work against every file in your repo, and refuses to write anything it can't prove correct. It also reads: snapshot for who owns what today, audit for what has rotted. Works with github.com and GitHub Enterprise Server. brew install jordonpeterson/tap/codeowners-tool In CI, uses: jordonpeterson/codeowners-tool@v1 . Every other route — curl | sh with build-provenance verification, direct download, go install , GHES, upgrading, uninstalling — is in docs/INSTALL.md . A policy is a JSON file stating the ownership you want. It is reviewable as a diff, it runs unchanged against one repo or a hundred, and everything that changes what gets written lives inside it rather than in a shell line nobody kept. { "version": 1, "name": "api co-ownership", "ops": "add owner /services/api/, @org/platform ", "add owner /docs/, @org/docs-team " } Validate, then preview. check reads no repository at all — the cheapest way to catch a broken policy before repo 1 — and nothing is written until you drop --dry-run : bash $ codeowners-tool check --policy ownership.json ok: ownership.json — 2 op s , no policy errors $ codeowners-tool sync --policy ownership.json --dry-run applied: 2 op s applied, 0 skipped; 2 line change s , 2 path s change owners ops 0 applied proven: tree ops 1 applied proven: tree proven: tree means the claim was checked against the repo's real files, not just reasoned about. Dropping --dry-run writes it, and the file becomes: bash $ cat .github/CODEOWNERS @org/everyone /docs/ @org/everyone @org/docs-team /services/api/ @org/api-team @org/platform Notice what happened. @org/everyone was carried onto the new /docs/ line — they owned it via , and add owner means co-own, so the new rule restates them or they'd be dropped. Each line went directly after the rule it narrows , and /services/api/ kept its spacing. Runs are idempotent, and every untouched byte survives.Beyond ops , a policy carries create permission to write a CODEOWNERS where a repo has none , on empty , max paths changed , defaults and a lint block — every field in POLICY-FILE.md /jordonpeterson/codeowners-tool/blob/main/docs/POLICY-FILE.md policy-file-fields . One-off changes. --op 'add owner /docs/, @org/docs-team ' runs a single op with no file. It is for exploring; anything you'd want reviewed, or run twice, belongs in a policy. Ownership is a property of files, not lines. .go @org/eng is not a fact; the fact is that services/api/main.go is owned by @org/eng — unless some later line also matches it, in which case that line wins outright and @org/eng is simply gone. This tool works in terms of files, and treats the lines as an implementation detail it derives for you. Each entry in ops is one intent. Scope is a directory, file path, or glob in CODEOWNERS pattern syntax; a space or a comma is escaped with a backslash docs/release\ notes.md , /a\,b/ . Where an op takes an owner it also takes a bracketed list — add owner /services/api/, @org/platform, @org/sre — one line change rather than two, and for remove owner the only always-correct spelling /jordonpeterson/codeowners-tool/blob/main/docs/OPERATIONS.md naming-several-owners-in-one-op-r-33-r-39 . | Op | What it means | |---|---| add owner scope, owner | Owner — or owners , or an owners array in the policy — becomes a co-owner. Every pre-existing owner of every path in scope is kept. | set owners scope, owners | This exact set — the list, or an owners array — owns every path in scope, displacing whoever owned it. is legal and deliberately un-owns the scope. | remove owner scope, owner | Owner — or owners , or an owners array — stops owning every path in scope. If that would empty a rule, you must say what happens — see on empty | rename owner old, new | Global identifier substitution — the only op that is safe as plain text replacement. | add owner and set owners are the two you'll use most, and picking the wrong one is the mistake this tool exists to prevent. Against /services/api/ @org/api-team : | The op in your policy | The line afterwards | |---|---| add owner /services/api/, @org/team-1 | /services/api/ @org/api-team @org/team-1 | set owners /services/api/, @org/team-1 | /services/api/ @org/team-1 | @org/api-team survives the first and is gone from the second — which is what set owners was asked for, explicitly. By hand both look like the same one-line edit, and that's the trap: adding /services/api/ @org/team-1 at the bottom of a file silently performs the second. Ops can also carve out sub-paths with an . /jordonpeterson/codeowners-tool/blob/main/docs/OPERATIONS.md except--carving-paths-out-of-a-scope-r-26r-32 except clause Two invariants hold on every write , or the write doesn't happen: INV-1 — every path in scope ends up owned exactly as the op says. INV-2 — every path out of scope ends up owned exactly as it was. This is the product. Anything it can't prove → it refuses and writes nothing. Refusing is a normal outcome for some repos, not a bug — GUIDE.md /jordonpeterson/codeowners-tool/blob/main/docs/GUIDE.md when-it-refuses shows what to do. Pattern note. README.md is unanchored, so like gitignore it matches a README.md atanydepth. Write /README.md if you mean only the one at the root. snapshot and audit write nothing and are safe against anything. Write your policy against what they tell you, not against what the file looks like: bash $ codeowners-tool snapshot | jq .ownership { "services/api/main.go": "@org/api-team" , "services/web/app.ts": "@org/everyone" } snapshot answers the question CODEOWNERS itself doesn't. means a rule matches and deliberately assigns no owners, null that no rule matches at all. It reads the file committed at --branch — what GitHub sees — so commit first. audit reports what's broken or rotten and lint repairs a subset. Offline it checks the git tree: dead patterns, case-only mismatches, shadowed rules, unowned paths. With a token it also checks that owners exist, are in the org, and have explicit write access — the check that catches the most real rot. Exit 4 means findings, 0 means clean — your CI gate. Exit 5 means a check was inconclusive: the audit fails closed and never proposes a removal it can't verify. Full check table: docs/LINTING.md . --repo points at any local clone, and the policy path stays relative to where you are — so one reviewed artifact sits outside every repository it governs. The tool never clones; that stays in your script. { "version": 1, "name": "org baseline", "ops": { "op": "add owner /services/api/, @org/platform ", "on zero match": "skip" }, { "op": "add owner /services/web/, @org/web-team ", "on zero match": "skip" } } bash $ codeowners-tool sync --repo clones/api-service --policy baseline.json applied: 1 op s applied, 1 skipped; 1 line change s , 1 path s change owners ops 0 applied proven: tree ops 1 skipped: scope "/services/web/" matches zero tracked files and on zero match=skip R-21 $ codeowners-tool sync --repo clones/web-app --policy baseline.json applied: 1 op s applied, 1 skipped; 1 line change s , 1 path s change owners ops 0 skipped: scope "/services/api/" matches zero tracked files and on zero match=skip R-21 ops 1 applied proven: tree Same bytes, two repos, each converging on what it actually has. skip means " if this repo has it"; the default require treats a scope matching nothing as a problem with this repo and exits 2 — what you want when every repo really should have the path. Exit 3 means the policy is broken everywhere, so a fleet stops rather than recording it a hundred times, which is why check --policy is worth running before repo 1. The rollout script and the jq habits that stop a silent no-op looking like success: docs/FLEET.md . — worked end-to-end changes: bootstrap a file, modify one, review a change, understand a refusal. GUIDE.md /jordonpeterson/codeowners-tool/blob/main/docs/GUIDE.md — the lookup tables: flags, policy fields, op semantics, JSON fields, exit codes, audit checks, guarantees. REFERENCE.md /jordonpeterson/codeowners-tool/blob/main/docs/REFERENCE.md — audit and repair, and every error they can print. LINTING.md /jordonpeterson/codeowners-tool/blob/main/docs/LINTING.md — rolling one policy across many repos. FLEET.md /jordonpeterson/codeowners-tool/blob/main/docs/FLEET.md — glossary, and habits that save you. CONCEPTS.md /jordonpeterson/codeowners-tool/blob/main/docs/CONCEPTS.md — generated from the tests; every BEHAVIOR.md /jordonpeterson/codeowners-tool/blob/main/docs/BEHAVIOR.md R- , S- , INV- and A- id is looked up here.— what the suite proves; TESTING.md /jordonpeterson/codeowners-tool/blob/main/docs/TESTING.md — every install route, provenance, GHES. INSTALL.md /jordonpeterson/codeowners-tool/blob/main/docs/INSTALL.md · CONTRIBUTING.md /jordonpeterson/codeowners-tool/blob/main/CONTRIBUTING.md · SECURITY.md /jordonpeterson/codeowners-tool/blob/main/SECURITY.md CHANGELOG.md /jordonpeterson/codeowners-tool/blob/main/CHANGELOG.md The test suite is the specification and BEHAVIOR.md is generated from it — what that proves, and how: docs/TESTING.md . MIT — see LICENSE , and for vendored-code attribution.