CheckOwners

Keep CODEOWNERS aligned with reality.

$ checkowners --offline drift

severity: HIGH (Δmax=1.00)
                                CODEOWNERS Drift                                
┏━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Category ┃ Path       ┃    Δ ┃ Reason                                        ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ changed  │ /payments/ │ 1.00 │ owners diverge on 2 of 2 covered path(s)      │
│          │            │      │ (line 1)                                      │
└──────────┴────────────┴──────┴───────────────────────────────────────────────┘

CheckOwners analyzes git and review history to infer who actually knows each part of your repository, then compares that evidence with your CODEOWNERS policy. Use it to detect stale or incorrect rules, find code with dangerously concentrated knowledge, recommend knowledgeable reviewers, and discover ownership gaps before they become operational risk.

Local-first. Git-native. No source-code upload. No LLM required. The core install is pure git. With no token, CheckOwners sends nothing anywhere. checkowners --offline opens no network connection. PyPI releases use Trusted Publishing. Sigstore signs each distribution.

This is a knowledge-risk tool, not a performance-measurement tool. Using it for individual evaluation is unsupported and harmful.

uvx checkowners drift

Install

Requires Python 3.11 through 3.14 and Git 2.23 or newer.

pip install checkowners               # core CLI (pure git, zero API deps)
pip install "checkowners[graph]"      # + networkx-backed graph / topology / onboard
pip install "checkowners[github]"     # + GitHub API handle/team/review resolution
pip install "checkowners[all]"        # everything

Run

checkowners --offline drift

Exit status is the same for every command: 0 clean, 1 internal error, 2 configuration or usage, 3 findings, 4 git or GitHub failure. checkowners --exit-zero hides findings only. See Exit codes.

CI

Least privilege (job summary only; no pull-request comment):

name: checkowners
on: [pull_request]

jobs:
  drift:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: smusali/checkowners@v0
        with:
          config: .github/checkowners.yml
          comment_on_pr: false

Same-repo comments need pull-requests: write. The comment workflow and the pre-commit hooks are in GitHub Actions and Pre-commit.

CheckOwners treats code ownership as a confidence-scored spectrum rather than a static binary declaration.

No other open-source tool combines git-history inference, per-path ownership scores with evidence quality, pattern-aware drift with severity tiers, and knowledge-risk reporting behind a single CI-native JSON contract.

See it

checkowners --offline drift on a sanitized two-person tree. The committed rule is /payments/ @platform.

The composite Action posts that finding as one comment on same-repo pull requests:

generate --force on the same tree writes examples/sample-CODEOWNERS:

# Generated by checkOwners. Do not edit manually.

/payments/ @alice @bob

How it works

analyze reads git log and git blame and caches an ownership map per repo under ~/.checkowners/.

• Noreply addresses become GitHub @handles locally. Other addresses use the GitHub API when a token is set.
• One person with several emails counts once.
• generate writes CODEOWNERS and collapses a directory of identical owners into one dir/ rule.
• drift matches the committed file with GitHub's CODEOWNERS rules: directories, globs, last match wins.

Other reports use that same map. The table below lists them. In CI, the composite Action writes GITHUB_OUTPUT, a job summary, and one pull-request comment on same-repo pull requests.

Scoring commands accept --json, --as-of, and SOURCE_DATE_EPOCH. The default instant is the HEAD committer time. graph uses --export dot instead of --json.

The full pipeline is in docs/USAGE.md.

Trimmed JSON from this repository is in examples/sample-output.md. Reference configs live under examples/.

Trust

Core inference is local git. checkowners --offline opens no network connection. With no token, CheckOwners sends nothing anywhere.

PyPI releases use Trusted Publishing. The publish workflow authenticates with a GitHub OIDC token and does not store a PyPI API token. Sigstore signs each distribution.

Each GitHub release also carries a CycloneDX SBOM and a signed build-provenance attestation.

This repository moved here from a previous GitHub organization; Sigstore attestations for 0.5.0 and earlier record that earlier publisher. 0.5.1 and later are published from smusali/checkowners.

Inference is deterministic git analysis; the scoring heuristics live in analyze.py and are auditable. The codebase has been built with agent assistance. Every AI-assisted change is human-reviewed, tested, and signed off.

What the tool reads, what leaves the machine, what the cache holds, how tokens are handled, and which permissions are required is in docs/PRIVACY.md.

Documentation

• docs/USAGE.md: full configuration reference, ownership scoring formula, drift severity tiers, GitHub Actions integration, comparison table.
• docs/METHODOLOGY.md: formulas, prior art, terminology, and project principles.
• docs/GLOSSARY.md: one-sentence definitions of the terms used in reports.
• docs/limitations.md: when the tool can be wrong, and what repository evidence cannot prove.
• docs/FAQ.md: identity (usernames vs emails, teams + subteams), GitHub API access, file locations, tuning, troubleshooting.
• docs/PRIVACY.md: what is read, what leaves the machine, the cache, cache purge, and the threat model.
• docs/CONTRIBUTING.md: dev setup, commands, conventional commits, code conventions, PR workflow.
• Good first issues · Discussions

License

MIT