Extra CODEOWNERS is a self-hosted GitHub App for teams that trust automation to approve routine pull requests. It publishes a required check that accepts either a human CODEOWNER approval or an approval from an explicitly enrolled GitHub App.
People and teams stay in GitHub's standard CODEOWNERS file. A separate
policy says which Apps may cover which owners and paths.
Warning
Extra CODEOWNERS is pre-release software. Don't use it to enforce production merges yet. The public container preview is also unsupported; don't deploy, mirror, or redistribute it. The project status lists the remaining enforcement and release blockers.
GitHub's Require review from Code Owners rule understands people and teams. It doesn't let a GitHub App stand in for them.
That becomes awkward when an App such as
Stampbot already knows that a pull
request is routine. Stampbot can approve a policy-compliant uv.lock update,
for example, but GitHub still waits for a human code owner.
Extra CODEOWNERS replaces that one decision with a check. It evaluates each distinct effective owner set separately:
appropriate human CODEOWNER approval
OR
enrolled App approval + matching delegation
│
▼
Extra CODEOWNERS / approval
Every owner set represented by an owned path must pass. One pull request may use a human approval for one owner set and an App approval for another. An App approval qualifies only when all of these are true:
- the organization enrolled that exact App identity
- the repository opted in
- the delegation covers the changed path and effective CODEOWNER
- any required labels are present
- the approval applies to the current pull-request head
- no organization or built-in guardrail makes the path human-only
A pull request that mixes delegated and undelegated owned paths still needs
human coverage for each undelegated owner set. A path with no effective
CODEOWNERS match creates no code-owner requirement, although the repository's
ordinary approval count and other rules still apply.
Keep your ordinary pull-request rules: minimum approval count, stale-review handling, signed commits, and unrelated required checks. Extra CODEOWNERS is intended to replace only Require review from Code Owners.
GitHub's public contract doesn't say whether a third-party App review counts toward the ordinary approval minimum. Test that combination in a disposable repository before you rely on it. A nonzero minimum may still require a human even when the Extra CODEOWNERS check succeeds; the native CODEOWNERS comparison explains the open contract and links to the live probe.
The App doesn't submit reviews, merge pull requests, grant another App access,
or edit CODEOWNERS. It reads GitHub evidence and publishes one Check Run.
This composition still needs live provider testing before production use. Check Runs belong to commits, while labels, changed paths, and reviews belong to pull requests. Issue #1 tracks the shared-commit edge cases and other GitHub contracts that must be proven.
Extra CODEOWNERS deliberately requires two policy scopes.
| Source | Decides |
|---|---|
CODEOWNERS |
Which people or teams own each path |
| Organization policy | Which Apps are trusted at all, plus paths no App may cover |
| Repository policy | Which enrolled App may cover which owner and path in this repository |
The repository policy can narrow organization policy, but it can't enroll an App or weaken an organization guardrail.
Here is the smallest useful repository policy:
schema_version = 1
enabled = true
[[delegations]]
app = "example-automation"
paths = ["/uv.lock"]
for_owners = ["@example-org/platform"]
required_labels = ["automation-approved"]The app value is an alias from the organization policy's [apps.<alias>]
table. That organization entry binds the alias to the App's immutable numeric
ID, public slug, and bot-user ID. The names above are examples; use the
validated files under examples/policy/ as your starting
point. The configuration guide covers both scopes,
path matching, labels, built-in protected files, and the insecure escape hatch.
There is no production install command yet. You can inspect the code and run
the local suite from a clean checkout with Bash, Git, and
mise installed:
git clone https://github.com/stampbot/extra-codeowners.git
cd extra-codeowners
mise trust
mise install
mise run bootstrap
mise run testRead mise.toml before mise trust; that command records a local trust
decision. A successful run ends with the test suite passing. It doesn't
register a GitHub App or prove the live GitHub contracts.
To publish a check in a disposable organization, follow the first-check tutorial. Keep GitHub's native code-owner rule enabled anywhere that matters.
These are the shortest routes into the manual:
| I want to… | Read |
|---|---|
| Find out what works today | Project status |
| Decide whether the trust model fits | Native CODEOWNERS comparison and threat model |
| Run a disposable live test | First-check tutorial |
| Enroll an App and delegate paths | Configuration guide |
| Diagnose a check | Troubleshooting guide |
| Review deployment and operations | Deployment guide and operations guide |
| Contribute | Contributor guide |
The full manual is on Read the Docs.
Use the support policy for questions and operational incidents. Report vulnerabilities privately under the security policy. The project also publishes its governance, changelog, and maintainer documentation.
Extra CODEOWNERS is licensed under the Apache License 2.0.