GitHub CODEOWNERS: How the CODEOWNERS File Works

GitHub CODEOWNERS is a file in your repository that maps file paths to the people or teams responsible for them, so GitHub automatically requests their review when a pull request changes code they own. Combined with the branch protection option "Require review from Code Owners," it also decides whose approval a pull request needs before it can merge.

CODEOWNERS is simple to write and easy to get subtly wrong: a misordered line or a team without write access fails quietly, with no error on the pull request. This guide covers where the file lives, the syntax, required code owner reviews, common mistakes, and how CODEOWNERS fits with AI code review. Every description of GitHub behavior here follows GitHub's own documentation, About code owners.

TL;DR: GitHub CODEOWNERS

• What it is. A file named CODEOWNERS that pairs path patterns with owners (@username, @org/team-name, or an email address).
• Where it goes. .github/, the repository root, or docs/. GitHub checks them in that order and uses the first one it finds.
• How patterns work. Mostly gitignore rules, but no ! negation, no [ ] ranges, and the last matching line wins.
• How to enforce it. Turn on required reviews in branch protection, then enable "Require review from Code Owners." Approval from any one listed owner satisfies it.
• With AI review. Keep owners on risky paths; let Macroscope's Approvability handle low-risk PRs.

What is a GitHub CODEOWNERS file?

A GitHub CODEOWNERS file defines the individuals or teams responsible for code in a repository, and GitHub uses it to request their review automatically. When someone opens a pull request that modifies files matching a pattern, the owners on that line are added as requested reviewers.

Two rules from GitHub's documentation shape everything else:

• Owners need write permission. A code owner must have write access to the repository. A team must also be visible and have write access as a team, even if every member already has write access some other way.
• Draft pull requests are skipped. Code owners are not automatically requested on drafts. They are notified when the draft is marked ready for review.

Where does the CODEOWNERS file go in a GitHub repository?

Put a file named exactly CODEOWNERS in the .github/ directory, the repository root, or the docs/ directory, on the branch where you want the owners to apply. If more than one exists, GitHub searches .github/, then the root, then docs/, and uses the first file it finds.

1. Ownership is per branch. Each CODEOWNERS file assigns owners for a single branch, so different branches can have different owners.
2. The base branch decides. For code owners to receive review requests, the CODEOWNERS file must be on the base branch of the pull request, the branch the PR will merge into. Forks follow the same rule.

The file must also be under 3 MB, or GitHub does not load it.

What is the CODEOWNERS syntax?

Each line of a CODEOWNERS file is a path pattern followed by one or more owners, and the patterns follow most of the same rules as .gitignore. Lines starting with # are comments. Owners are written as @username, @org/team-name, or an email address attached to a GitHub account.

Here is an example for a typical web service:

# Default owners for everything not matched below
*                       @acme/platform

# All TypeScript files
*.ts                    @acme/frontend

# Any "migrations" directory, at any depth
**/migrations/          @acme/data

# The billing service at the repo root, two owning teams
/services/billing/      @acme/payments @acme/security

# Files directly inside docs/, but not nested folders
docs/*                  @acme/docs

# Infrastructure, with a subfolder left unowned
/infra/                 @acme/sre
/infra/sandbox/

# Protect the CODEOWNERS file itself
/.github/CODEOWNERS     @acme/eng-leads

What each pattern does, according to GitHub's documented semantics:

• * matches every file, so it sets default owners. Because later lines win, it belongs at the top.
• **/migrations/ matches a migrations directory at any depth.
• /services/billing/ with a leading slash is anchored to the repository root and covers everything beneath it.
• docs/* matches files directly inside docs/ but not deeper nested files such as docs/guides/setup.md.
• apps/ without a leading slash (not shown above) matches an apps directory anywhere in the repository.
• /infra/sandbox/ with no owner leaves that subfolder unowned. Changes there can be approved by anyone with write access instead of a code owner.

Which gitignore rules do not work in CODEOWNERS?

Three gitignore features are not supported in CODEOWNERS: ! negation, [ ] character ranges, and escaping a leading # with a backslash. If you are used to writing !vendor/ in a gitignore file, the CODEOWNERS equivalent is a later line that assigns a different owner, or no owner, to that path.

How does CODEOWNERS precedence work?

The last matching pattern in the file takes precedence. GitHub does not merge owners from several matching lines; it uses the final line that matches the file. That is why a catch-all * goes at the top and the most specific rules go at the bottom.

It also means two owners for one pattern must be on the same line; repeating the pattern on a second line replaces the first.

Are CODEOWNERS paths case sensitive?

Yes, CODEOWNERS paths are case sensitive, even if your laptop's file system is not. GitHub evaluates the file, and GitHub uses a case-sensitive file system, so /Docs/ and /docs/ are different paths on macOS too.

How do you require code owner review on GitHub?

Enable required pull request reviews in a branch protection rule for the branch, then turn on "Require review from Code Owners." From then on, a pull request that changes owned files cannot merge until an owner of those files approves.

The steps:

1. Make sure a CODEOWNERS file exists on the target branch (usually your default branch).
2. Open the repository settings and edit the branch protection rule for that branch.
3. Enable required reviews before merging.
4. Enable Require review from Code Owners.

Three behaviors to know before you rely on it:

• Any one owner is enough. When a line lists several owners, an approval from any one of them satisfies the requirement. Listing @acme/payments @acme/security does not mean both teams must approve.
• Protect the file itself. To guard against someone quietly changing who owns what, GitHub recommends keeping CODEOWNERS in .github/ and assigning an owner to the file or the whole directory, for example /.github/CODEOWNERS @owner.
• Rulesets are an alternative. GitHub's docs describe rulesets as an alternative to branch protection rules, and several can apply at once.

If you also want automated checks to block merges, the companion guide on how to make AI code review a required check on GitHub covers required status checks, the other half of a merge gate.

What are the most common GitHub CODEOWNERS mistakes?

Most CODEOWNERS problems come from owners who lack write access, lines in the wrong order, or a file on the wrong branch, and none of them produce an error on the pull request. GitHub skips invalid lines rather than failing, so a broken rule simply assigns nobody.

The mistakes worth checking for:

• Owners without write access. If a user or team does not exist or has insufficient access, no code owner is assigned for that line. Teams need explicit write access as a team.
• Catch-all at the bottom. A trailing * @acme/platform overrides every specific rule above it, because the last match wins.
• Using ! or [ ]. Both are unsupported, so the line does not behave as it would in a gitignore file.
• Wrong branch. The file must be on the PR's base branch. A CODEOWNERS file that exists only on main does nothing for PRs into release.
• Expecting every owner to approve. With code owner review required, one listed owner's approval is sufficient.
• Unprotected CODEOWNERS. If anyone can edit the file and approve their own change, ownership is advisory.

To find broken lines, open the CODEOWNERS file in the GitHub web interface, where syntax errors are highlighted, or use the REST API endpoint that lists CODEOWNERS errors.

Does CODEOWNERS slow down pull request approvals?

CODEOWNERS routes by path, not by risk, so on its own it can turn owners into a bottleneck for changes that do not need them. The owner of /services/billing/ is requested for a typo fix in a comment and for a change to proration logic with the same urgency.

It is still the right foundation for accountability. The problem is that every owned change, however trivial, lands in the same human queue. The guide to speeding up pull request approvals safely walks through the full set of levers; the short version is to route by risk, and let automation handle the routine slice.

How does GitHub CODEOWNERS work with AI code review?

Use CODEOWNERS to decide who must look at risky paths, and use AI code review to decide which pull requests are low-risk enough not to need a human at all. The two answer different questions, and they work best together.

Three parts of Macroscope's AI code review connect directly to code ownership.

Approvability: auto-approving low-risk pull requests

Macroscope's Approvability check evaluates whether a pull request is safe to approve without a human reviewer. It clears three hurdles before approving:

• Ownership (off by default). When enabled, the PR author must own the changed files according to the repository's CODEOWNERS file. If the PR looks safe but ownership fails, the verdict is "Recommend Approval," which tells a code owner that only their +1 is needed.
• Eligibility. An agent classifies the change. Documentation, tests, code behind a disabled feature flag, simple bug fixes, mechanical renames and minor CI tweaks are eligible by default.
• Correctness. If the correctness review finds a MEDIUM-or-higher issue, the PR is not approved.

The default policy escalates security, auth, billing, infrastructure, breaking schema changes and major refactors to a human, plus edits to CODEOWNERS itself unless the author owns that file. Approvability is off by default, and teams usually start in the informational "Would Approve" mode.

One interaction to plan for: GitHub's docs describe code owners as users and teams with write access. On paths where you require code owner review, a listed human or team owner still has to approve. A practical split is to keep "Require review from Code Owners" on your genuinely sensitive paths and let Approvability clear the low-risk changes elsewhere.

Check Run Agents: path-specific rules that need judgment

CODEOWNERS can say who reviews /services/billing/. It cannot say what that reviewer should check. Check Run Agents fill that gap: each one is a plain-English markdown file in .macroscope/check-run-agents/, read from the default branch, that runs as its own GitHub check run on every pull request. An agent can say "if this PR touches services/billing/, verify every new charge path is idempotent," and with conclusion: failure and input: full_diff it can block the merge.

One caution: an agent scoped with include patterns does not run outside those paths, so a required one can leave GitHub waiting. Put path logic in the instructions of required agents.

Pricing is usage-based with no per-seat fees: code review, including Approvability, is $0.05 per KB of diff reviewed (10 KB minimum), Check Run Agents bill under Agent usage, and every new workspace gets $100 in usage credit. See pricing.

Frequently Asked Questions

What is a CODEOWNERS file in GitHub?

A CODEOWNERS file is a plain-text file in a GitHub repository that maps path patterns to the users or teams responsible for that code. When a pull request changes matching files, GitHub automatically requests a review from those owners. With "Require review from Code Owners" enabled in branch protection, an owner's approval is also required before the pull request can merge.

Where does the CODEOWNERS file go?

Name the file CODEOWNERS and put it in the .github/ directory, the repository root, or the docs/ directory. GitHub searches those locations in that order and uses the first file it finds. The file must be on the base branch of the pull request for review requests to work.

How do I require code owner review on GitHub?

Edit the branch protection rule for your target branch, enable required reviews before merging, and turn on "Require review from Code Owners." A pull request that changes owned files then needs approval from one of the listed owners before it can merge. Rulesets are an alternative to branch protection rules.

Do all code owners need to approve a pull request?

No. When a line lists several owners, an approval from any one of them satisfies the code owner requirement. If you need approvals from two different groups, that requires a different mechanism than listing both on one CODEOWNERS line.

Why is my CODEOWNERS file not requesting reviewers?

The usual causes are an owner without write access, a team that is not visible or lacks write access as a team, a later line overriding the one you expected, a case mismatch in the path, the file not existing on the PR's base branch, or the PR being a draft. Open the file on GitHub to see highlighted syntax errors.

Does CODEOWNERS support negation with an exclamation mark?

No. CODEOWNERS does not support ! negation, [ ] character ranges, or escaping a leading #. To carve out a subfolder, add a later line for that path with a different owner, or with no owner at all.

How do I leave a path without a code owner?

Write the path on its own line with no owners after it, below the broader rule that would otherwise match. Changes to that path can then be approved by anyone with write access to the repository rather than a code owner.

Can I use an email address in CODEOWNERS?

In most cases, yes. You can reference a user by an email address that has been added to their GitHub account. GitHub's docs note that this does not work for managed user accounts in Enterprise Managed Users.

Can AI code review approve pull requests that CODEOWNERS covers?

An AI check can approve, but it does not replace a required code owner. Macroscope's Approvability posts a GitHub APPROVE review on low-risk pull requests, and it can optionally require that the author owns the changed files per CODEOWNERS. On paths where branch protection requires code owner review, a listed owner still needs to approve.