Generate a polished, interactive HTML report for CODEOWNERS coverage, ownership gaps, and GitHub-parity validation. Run it locally for investigation or in CI to fail when files are uncovered.

See how ownership coverage looks in practice with this interactive report for the nodejs/node repository.

CODEOWNERS is great for review routing, but it is hard to quickly answer:

• How much of this repository is actually covered?
• Which directories have the biggest ownership gaps?
• Which specific files have no matching owner rule?
• Which CODEOWNERS rules look valid in git, but are ignored or ineffective on GitHub?

codeowners-audit scans a repository, applies practical CODEOWNERS resolution, and produces a single self-contained HTML report you can open locally, archive in CI, or upload to a public link.

• Self-contained interactive HTML report
• Coverage drill-down by repository, directory, file, and resolved owner
• CI-friendly defaults that can fail builds when files are uncovered
• GitHub-parity validation for ignored CODEOWNERS files, missing paths, invalid owners, oversized files, and fragile coverage
• Optional team suggestions for uncovered directories based on git history
• Works on local repositories or remote GitHub repositories with a single command

Run without installing:

npx codeowners-audit

For repeat use in a repository or CI, add it as a dev dependency:

npm install --save-dev codeowners-audit

Common first runs:

Generate a report for the current repository:

npx codeowners-audit

Fail in CI without writing HTML:

npx codeowners-audit --no-report

Audit a remote GitHub repository:

npx codeowners-audit watson/codeowners-audit

codeowners-audit [repo-or-path] [options]

The executable name is codeowners-audit. If you are running it without installing it as a dependency, prefix commands with npx.

[repo-or-path] is optional and can be:

• A remote repository URL such as https://github.com/owner/repo
• GitHub shorthand such as owner/repo
• A local directory path such as ~/code/my-repo
• Omitted, in which case the current working directory is used

By default, the tool:

• analyzes tracked files from git ls-files
• writes the report to a temporary path
• prompts you to press Enter before opening the report in your default browser

When standard input is non-interactive (no TTY, for example in CI), the command automatically behaves as if --no-open --list-unowned --fail-on-unowned were specified:

• it never prompts to open a browser
• it prints all unowned file paths to stdout
• it exits non-zero when uncovered files exist

Use --output or --output-dir for deterministic artifact paths, or --no-report to skip writing HTML entirely. In interactive mode, --no-report implies --list-unowned so the command still produces useful output.

Generate a report and open it after pressing Enter:

codeowners-audit

Write a report to a known path without opening a browser:

codeowners-audit --output codeowners-gaps-report.html --no-open

Run against a repository from another directory:

codeowners-audit ~/code/my-repo

Audit a remote GitHub repository:

codeowners-audit watson/codeowners-audit

Upload a report and print the public URL:

codeowners-audit --upload

Validate only a subset of files:

codeowners-audit --glob "src/**/*.js" --glob "test/**/*.js"

Suggest teams for uncovered directories:

codeowners-audit --suggest-teams

Most CI systems, including GitHub Actions, run in a non-interactive environment. In that mode, codeowners-audit automatically:

• disables browser prompts with --no-open
• prints unowned files to stdout with --list-unowned
• exits 1 when uncovered files exist with --fail-on-unowned

Exit code behavior:

• Exit code 0: all matched files are covered by CODEOWNERS, and no enabled validation policy failed
• Exit code 1: at least one enforced policy failed, including uncovered files and any enabled --fail-on-* validation rule
• Exit code 2: runtime or setup error, for example not being in a git repository, missing CODEOWNERS, or invalid arguments

Validate all tracked files:

codeowners-audit

Validate all tracked files without writing HTML:

codeowners-audit --no-report

Validate and write a report artifact to a known path:

codeowners-audit --output codeowners-gaps-report.html

Validate and write reports into an artifact directory:

codeowners-audit --output-dir artifacts

Validate only a subset, for example spec files:

codeowners-audit --glob "**/*.spec.js"

- name: Verify CODEOWNERS coverage
  run: npx codeowners-audit --no-report

• Follows GitHub CODEOWNERS discovery order: .github/CODEOWNERS, CODEOWNERS, then docs/CODEOWNERS
• Uses standard last-match-wins behavior, including ownerless overrides when the last matching rule has no owners
• Resolves patterns from the repository root, regardless of which supported CODEOWNERS location is active
• Optionally validates @username and @org/team owners against GitHub with --validate-github-owners
• Reports extra or ignored CODEOWNERS files, missing paths, fragile coverage, and unsupported syntax that GitHub would not honor

• git available on PATH

zenbin currently rejects request payloads around 1 MiB and larger. Very large repositories can produce HTML reports beyond that limit, in which case --upload will fail with a clear size error. Use the generated local HTML file directly when this happens.

MIT