CODEOWNERS Enforcement Mode

CODEOWNERS Enforcement Mode posts a GitHub Check Run on every pull request. When a PR touches files that have a declared CODEOWNERS owner but has not received a review from that owner, the check fails and blocks the merge.

How enforcement works

When enforcement is enabled for a repository, Koalr subscribes to pull request events via the GitHub webhook. Each time a PR is opened, synchronized (new commits pushed), or marked ready for review:

1. Koalr reads the CODEOWNERS rules for the repository.
2. Koalr determines which files changed in the PR and looks up the owner for each changed file.
3. Koalr checks the PR's review history to see whether each required owner has submitted an approving review.
4. Koalr posts (or updates) a GitHub Check Run with the result.

The check run is named Koalr / CODEOWNERS Review and appears in the PR's Checks tab alongside other CI checks.

Check run outcomes

Check passes

The check run shows a green checkmark with the message:

All changed files have been reviewed by their CODEOWNERS.

The PR can be merged normally (subject to any other branch protection rules).

Check fails

The check run shows a red X with details about which files are missing owner reviews, for example:

3 files require CODEOWNERS review:

• src/billing/stripe.ts — requires review from @payments-team
• src/billing/invoice.ts — requires review from @payments-team
• infra/terraform/prod.tf — requires review from @platform-team

The PR cannot be merged until the required reviews are added, assuming you have branch protection configured to require all checks to pass.

Enabling enforcement per repository

Enforcement is off by default. To enable it for a repository:

1. Go to CODEOWNERS in the left sidebar.
2. Find the repository in the list.
3. Toggle Enforcement mode from off to on.

The toggle takes effect immediately. The next pull request event on that repository (or a manual sync) will cause Koalr to post a check run.

Branch protection requirement

For the check run to actually block merges, you must configure GitHub branch protection on your default branch to require the Koalr / CODEOWNERS Review check to pass before merging. Koalr cannot enforce this automatically because branch protection changes require GitHub admin access.

To configure branch protection:

1. In your GitHub repository, go to Settings → Branches.
2. Edit or add a branch protection rule for your default branch (e.g., main).
3. Enable Require status checks to pass before merging.
4. Search for and select Koalr / CODEOWNERS Review.
5. Save the rule.

Alert mode vs enforcement mode

Koalr offers two modes for handling CODEOWNERS violations:

Mode	What it does
Alert mode (default)	Sends a Slack notification when a PR is merged without the required CODEOWNERS review. Does not block the merge.
Enforcement mode	Posts a failing GitHub Check Run that prevents the merge until the required review is added.

Alert mode is suitable for teams that want visibility without hard blocks. Enforcement mode is recommended for teams with compliance requirements or repositories containing sensitive code.

You can run both modes simultaneously — enforcement blocks the merge while alert mode sends a Slack notification to the owner who needs to review.

Handling unowned files

Files with no entry in CODEOWNERS are considered unowned. By default, Koalr does not fail the check for unowned files — the check only fails when a file has a declared owner who has not reviewed the PR.

If you want the check to also fail for unowned files (requiring all code to have an owner), enable Require all files to be owned in the enforcement settings for that repository.