Syncing CODEOWNERS Files

How Koalr reads and syncs CODEOWNERS files from your repositories and what the ownership health score measures.

Koalr reads CODEOWNERS files from your GitHub repositories and keeps ownership data current using real-time webhook events. This page explains where Koalr looks for CODEOWNERS files, how sync works, and what the ownership health score measures.

CODEOWNERS file locations

Koalr reads CODEOWNERS files from three standard locations within each repository, in priority order:

.github/CODEOWNERS — the most common location, recommended by GitHub
CODEOWNERS — root of the repository
docs/CODEOWNERS — alternative location supported by GitHub

If multiple CODEOWNERS files exist in the same repository, Koalr uses the same file that GitHub uses: .github/CODEOWNERS takes priority over the root CODEOWNERS, which takes priority over docs/CODEOWNERS.

CODEOWNERS files that do not exist yet (for newly created repositories) are treated as having no ownership rules — all files in that repository appear as unowned.

Automatic sync via GitHub webhook

Every push to any branch in a connected repository triggers a GitHub webhook event. Koalr processes this event and, if the push modified any CODEOWNERS file, re-syncs the ownership rules for that repository.

The latency between a CODEOWNERS file change being pushed to GitHub and the update appearing in Koalr is less than 60 seconds under normal conditions. This near-real-time sync means CODEOWNERS enforcement and drift detection always reflect the current state of your files.

Manual sync

If you need to force a re-sync immediately (for example, after troubleshooting a webhook issue), you can trigger a manual sync from the CODEOWNERS dashboard:

Go to CODEOWNERS in the left sidebar.
Select the repository you want to re-sync.
Click Sync now in the top-right corner.

Manual sync re-reads the CODEOWNERS file from GitHub and updates Koalr's ownership index within a few seconds.

What Koalr parses from CODEOWNERS files

Koalr parses the full CODEOWNERS format supported by GitHub, including:

File patterns — glob patterns matching files and directories (e.g., src/api/**)
Owner references — GitHub usernames (@username), team slugs (@org/team-name), and email addresses
Multiple owners per pattern — when a pattern has multiple owners, all are recorded
Comment lines — lines beginning with # are ignored
Pattern precedence — later rules in the file override earlier rules, matching GitHub's own precedence behavior

Ownership health score

Each repository receives an ownership health score from 0 to 100. This is a composite score measuring how complete and current your CODEOWNERS coverage is. The score is computed from several factors:

Factor	Description
Coverage ratio	Percentage of files in the repository that have at least one owner. A repository where 90% of files are owned scores higher than one where only 50% are owned.
Team vs individual ownership	Files owned by teams score higher than files owned by individual users. Individual ownership creates single points of failure when that person leaves.
Drift delta	If Koalr's drift detection identifies significant discrepancy between declared owners and actual recent committers, the score is reduced.
Staleness	CODEOWNERS files that have not been updated in more than 180 days relative to significant directory-level changes receive a staleness penalty.

A score of 80 or above is considered healthy. Scores below 60 typically indicate either large areas of unowned code or significant ownership drift.

The health score for each repository is shown in the CODEOWNERS dashboard table and in the service catalog entry for that repository.

Drift Detection — how Koalr identifies when CODEOWNERS diverges from actual ownership patterns
Enforcement Mode — block merges on PRs that touch code without an owner review