GitHub + CODEOWNERS Setup Guide

This guide walks you through the complete workflow for connecting GitHub to Koalr and setting up CODEOWNERS governance. By the end, you will have ownership rules synced from all your repositories, drift detection running daily, enforcement blocking non-compliant merges, and Slack alerts notifying your team when violations occur.

Time to complete: 15--20 minutes.

Plan requirement: CODEOWNERS features require the Business plan or higher.

---

Prerequisites

Before you begin, confirm the following:

• You have an active Koalr account with Admin or Owner role.
• Your GitHub organization uses CODEOWNERS files (typically at .github/CODEOWNERS in each repository). If you do not have CODEOWNERS files yet, you can still connect GitHub and add them later.
• You have a GitHub Personal Access Token (PAT) with repo, read:org, and read:user scopes. Create one at github.com/settings/tokens.

---

Step 1: Connect GitHub

1. In Koalr, navigate to Integrations in the left sidebar.
2. Find the GitHub card and click Connect GitHub (or go directly to /integrations/github/connect).
3. Enter your Organization Name -- the GitHub org or user account name (e.g., acme-corp).
4. Paste your Personal Access Token.
5. Click Connect GitHub.

Koalr will validate the token, fetch your repositories, and begin the initial data sync. This typically takes 1--3 minutes depending on the number of repositories.

After connecting, verify your repositories appear under Integrations in the connected repositories list.

---

Step 2: Sync CODEOWNERS files

Once GitHub is connected, navigate to CODEOWNERS in the left sidebar.

1. Click Sync from GitHub in the top-right corner.
2. Koalr scans all connected repositories for CODEOWNERS files in three standard locations: .github/CODEOWNERS, CODEOWNERS (root), and docs/CODEOWNERS.
3. When the sync completes, you will see a summary message like: "Synced 12/14 repos, 87 rules found."

The CODEOWNERS dashboard now shows:

• Repos with CODEOWNERS -- how many of your repositories have ownership files.
• Total Rules -- the aggregate number of ownership patterns across all repos.
• Unique Owners -- distinct GitHub users and teams referenced in your rules.
• Teams Matched -- how many CODEOWNERS entries map to Koalr teams.

Expand any repository row to see individual CODEOWNERS entries, including the file pattern, assigned owners, and the line number in the CODEOWNERS file.

After the initial sync, Koalr keeps ownership data current automatically. Every push to a connected repository triggers a webhook, and if the push modified a CODEOWNERS file, Koalr re-syncs within 60 seconds.

For more details on how sync works, see Syncing CODEOWNERS Files.

---

Step 3: Review your Ownership Health Score

Below the repository list, the Ownership Health Score card shows a composite score from 0 to 100 with a letter grade (A through F). The score is computed from several factors:

• Coverage ratio -- what percentage of files have at least one owner.
• Team vs individual ownership -- files owned by teams score higher than files owned by individual users (individual ownership creates single points of failure).
• Drift delta -- how much declared ownership diverges from actual commit patterns.
• Staleness -- CODEOWNERS files that have not been updated in over 180 days relative to directory changes receive a penalty.

A score of 80 or above (grade A or B) is considered healthy. If your score is below 60, review the Ownership Coverage section to identify repos without CODEOWNERS files and the highest-priority gaps.

---

Step 4: Enable drift detection alerts

Drift detection runs automatically every day at 3 AM UTC. Koalr compares declared owners in your CODEOWNERS files against the engineers who have actually committed to those files in the past 90 days. When declared owners account for less than 20% of recent commits, a drift event is created.

To receive Slack notifications when drift is detected:

1. Ensure Slack is connected (see Slack Setup).
2. Navigate to Automations in the left sidebar.
3. Create a new automation rule:
   • Trigger: CODEOWNERS drift detected
   • Action: Post to Slack channel
   • Channel: Select your engineering or platform team channel
4. Save the rule.

You will now receive a Slack message whenever high-severity drift is detected -- for example, when a declared owner has made zero commits to the affected files in 90 days.

For the full drift detection model, see Drift Detection.

---

Step 5: Turn on enforcement mode

Enforcement mode posts a GitHub Check Run on every pull request. When a PR modifies files that have a declared CODEOWNERS owner but has not received an approving review from that owner, the check fails.

1. Navigate to CODEOWNERS in the left sidebar.
2. Locate the CODEOWNERS Enforcement card.
3. Toggle the switch to Active.

The toggle takes effect immediately. The next pull request event on any connected repository will trigger a check run.

Configure GitHub branch protection

For the check run to actually block merges, you must add it to your branch protection rules in GitHub:

1. In your GitHub repository, go to Settings then 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.

Repeat for each repository where you want enforcement.

When a PR scores a failing check, the PR author sees exactly which files need owner review and which teams need to approve.

For full details on enforcement options (alert mode vs enforcement mode, handling unowned files), see Enforcement Mode.

---

Step 6: Set up compliance violation alerts

In addition to drift alerts, you can receive Slack notifications when a PR is merged without the required CODEOWNERS approval:

1. Navigate to Automations.
2. Create a new rule:
   • Trigger: CODEOWNERS compliance violation
   • Action: Post to Slack channel
   • Channel: Select the relevant team channel
3. Save the rule.

This is particularly useful when running enforcement in alert mode (non-blocking) -- you get visibility into violations without hard-blocking merges while your team adjusts.

---

Verification checklist

After completing this guide, confirm each item:

• GitHub integration shows Active under Integrations.
• CODEOWNERS dashboard shows your repositories and parsed rules.
• Ownership Health Score is visible with a letter grade.
• A test PR to a connected repository triggers the Koalr / CODEOWNERS Review check run (if enforcement is enabled).
• Slack channel receives a test message from the automation rule you created.

---

What to do next

• Fix coverage gaps -- the CODEOWNERS dashboard highlights repos without ownership files. Add CODEOWNERS files to your highest-traffic unowned repos first.
• Map owners to Koalr teams -- when CODEOWNERS references @org/team-name, Koalr matches these to your Koalr teams. Set up teams at Team Setup Best Practices.
• Connect to Deploy Risk -- CODEOWNERS compliance is a core signal in Koalr's deploy risk scoring. See the Deploy Risk Setup Guide to enable risk scoring.