checkowners 0.1.0

Infer and maintain CODEOWNERS from git history. Drift detection, CI-native JSON output, and GitHub Actions integration.

checkowners

Infer and maintain CODEOWNERS from git history. Drift detection, CI-native JSON output, and GitHub Actions integration.

Installation

pip install checkowners

Quick Start

# Infer ownership from git commit history
checkowners analyze

# Generate .github/CODEOWNERS from inference
checkowners generate

# Detect drift between inferred and current CODEOWNERS
checkowners drift

# Validate CODEOWNERS syntax
checkowners validate

All commands support --json for structured output.

Commands

Command	Description
checkowners analyze	Infer file ownership from git history
checkowners generate	Write .github/CODEOWNERS from inferred ownership
checkowners print	Print inferred owners to stdout
checkowners validate	Validate existing CODEOWNERS syntax (no git access)
checkowners drift	Compare inferred vs. current CODEOWNERS
checkowners notify	POST webhook on drift events
checkowners sync	Generate CODEOWNERS and commit the result

Configuration

Create .github/checkowners.yml in your repository:

analysis:
  lookback_days: 180        # How far back to analyze
  min_commits: 3            # Minimum commits to qualify as owner
  top_n_owners: 2           # Max owners per path

paths:
  exclude:
    - "*.lock"
    - "dist/**"
    - "vendor/**"

output:
  header: "# Generated by checkOwners. Do not edit manually."
  include_unowned: false    # Show paths with no inferred owner

drift:
  mode: commit              # commit | repo | both
  compare_to: auto

notifications:
  webhook_url: ""           # POST here on drift events
  include_unchanged: false

All fields are optional. Defaults are shown above.

Drift Detection Modes

• commit: detect paths in the inferred map that are missing from CODEOWNERS
• repo: detect CODEOWNERS entries that are stale or have changed owners
• both: run both checks

GitHub Actions

- name: Check CODEOWNERS drift
  run: |
    pip install checkowners
    checkowners drift --json

Set drift.mode: both in your config and fail the step when drift_detected is true.

Development

hatch run test              # pytest with coverage
hatch run lint              # ruff check + mypy --strict
hatch run fmt               # ruff format

License

MIT