Lorixen.
EN

CODEOWNERS: routing GitHub reviews to the right people

Short answer: A CODEOWNERS file tells GitHub who is responsible for which parts of a repository, so the right people are asked to review a pull request automatically. Put it in .github/, the root or docs/, map file patterns to users or teams with write access, remember that the last matching line wins, and turn on "Require review from Code Owners" in your branch rules if their approval should be mandatory.

Why small teams use it

In a two-person team, everyone reviews everything. Once you have a few developers, an outside agency or contractors, reviews start falling through the gaps. The payments code gets changed without the person who knows it seeing the pull request. The infrastructure folder is edited by someone who meant to fix a typo on the marketing site.

GitHub's code owners feature fixes the routing. Its documentation says code owners are automatically requested for review when someone opens a pull request that modifies code they own. You stop relying on people remembering to tag the right reviewer.

Where the file goes

Create a file called CODEOWNERS (no extension) in one of three places: the .github/ directory, the repository root, or the docs/ directory. GitHub searches those locations in that order and uses the first one it finds, so keep just one.

The file must be on the base branch of the pull request, usually main. A CODEOWNERS file on a feature branch won't route reviews for pull requests into main until it has been merged there.

GitHub also sets a size limit: CODEOWNERS files must be under 3 MB, and a larger file isn't loaded at all. That's rarely a problem for small teams, but it's a reason to use broad patterns rather than listing every file.

Writing the rules

Each line is a file pattern followed by one or more owners, written as @username or @org/team-name:

*                 @acme/dev-team

/web/             @acme/frontend

/api/billing/     @priya @acme/payments

/infra/           @acme/ops
/.github/workflows/ @acme/ops

/.github/CODEOWNERS @acme/leads

A few rules from GitHub's documentation are worth knowing before you start.

Order matters. The last matching pattern takes precedence. In the example above, a change to /api/billing/invoice.js matches both * and /api/billing/, but only the billing owners are requested, because their line comes later. Put the general rule first and the specific ones after it.

Multiple owners go on one line. If two people should own the same path, list them on the same line. Two separate lines with the same pattern means the second replaces the first.

It's like .gitignore, but not exactly. Patterns follow most gitignore rules, but GitHub lists exceptions: you can't negate a pattern with !, you can't use [ ] character ranges, and escaping a # with a backslash doesn't work.

Paths are case-sensitive. GitHub evaluates paths as written, so even if your laptop's file system ignores case, the file must use the correct capitals.

Who can be an owner

GitHub is strict here. Owners must have write permission to the repository. For a team, the team must be visible and must itself have write access, even if every member already has write access some other way. If you list someone who doesn't exist or lacks access, GitHub quietly assigns no owner for that line.

This catches out businesses working with agencies. If the agency's developers are outside collaborators with read access, listing them as owners does nothing.

Checking your file

When you open the CODEOWNERS file on GitHub, errors are highlighted. GitHub skips any line with invalid syntax, so a typo can silently remove ownership for a whole folder. GitHub also exposes the list of errors through its API, which you can check in CI if the file changes often.

After any edit, open a small test pull request that touches a file in each owned area and confirm the right reviewers appear.

Making approval mandatory

On its own, CODEOWNERS only requests reviews. To make code owner approval a merge requirement, edit the branch protection rule or ruleset for your main branch and enable "Require review from Code Owners". Only people with admin or owner permissions can do this.

Two details from GitHub's documentation:

  • An approval from any one of the listed owners for a path satisfies the requirement. If a line lists a team, one approving member is enough.
  • Code owners aren't automatically requested on draft pull requests. They're notified when the draft is marked ready for review.

Practical tips

  • Prefer teams to individuals. People go on holiday and leave. A team keeps reviews flowing.
  • Own the CODEOWNERS file itself. Otherwise anyone can remove themselves from review by editing it.
  • Keep the default owner broad. A * line ensures nothing is left without an owner.
  • Don't over-split. Ten tiny areas with one owner each creates bottlenecks. Group by risk: billing, authentication, infrastructure, and everything else.
  • Combine with other branch rules, such as required status checks, so reviewers see a passing build.

A worked example

A hypothetical Leeds software firm builds a booking platform with an outside design agency. The agency changes templates, the in-house team handles the API, and one senior developer looks after payments. They add a CODEOWNERS file with a default team, the agency team for /web/templates/, and the senior developer plus a backup for /api/payments/. Test pull requests show the agency's team isn't requested, because it only had read access. After giving it write access to the repository and enabling required code owner review on main, payment changes can't merge without one of the two payment owners approving.

FAQ

Does CODEOWNERS work on the free GitHub plan?

GitHub's documentation lists the plans and repository types that support code owners. Check your organisation's plan, especially for private repositories.

Can owners be outside my organisation?

Owners need write access to the repository. Outside collaborators can be owners if they have it.

What happens if no line matches a file?

Nobody is requested automatically. A * default line avoids this.

Can I have different owners on different branches?

Yes. Each branch's own CODEOWNERS file applies to pull requests targeting that branch.

If you'd like help setting up review rules that fit how your team and agency actually work, get in touch about your repository.

Sources

WhatsAppBook a call