lockstep
3 min readNaman Jain

CODEOWNERS file examples (GitHub) and the mistakes to avoid

GitHub CODEOWNERS file examples for monorepos, teams, and sensitive paths: where the file goes, pattern rules, last-match-wins, and common mistakes.

A change to the payments service merges with one approval from someone on the search team. Nothing in the repository said payments changes needed a payments engineer. A CODEOWNERS file would have requested the right reviewer automatically.

This guide gives examples and the rules that catch people out, from GitHub's code owners documentation, checked on 16 November 2026.

How it works

  • Code owners are automatically requested for review when a pull request changes files they own. Draft pull requests don't trigger requests.
  • With required reviews on, admins can require a code owner's approval before merging.
  • Owners must have write access. Teams must be visible and have write access.
  • The file goes in .github/, the repository root, or docs/, on the branch it applies to. Pull requests use the file from their base branch.
  • The file must be under 3 MB. Invalid lines are skipped, and GitHub highlights errors when you view the file.

Syntax rules

Patterns follow most gitignore rules, followed by owners as @username, @org/team-name, or an email address.

RuleDetail
Last match winsLater lines override earlier ones for the same file
One line per pattern's ownersOwners on separate lines for the same pattern: only the last line applies
No negation!pattern doesn't work
No character ranges[a-z] doesn't work
No escaped #\# to start a pattern doesn't work
Case-sensitiveEven on macOS
Empty ownerA pattern with no owners removes ownership for that path

Example: a typical service repository

# Default owners for everything
*                       @acme/platform

# Frontend
/web/                   @acme/frontend

# Payments needs payments review, plus security for webhooks
/services/payments/     @acme/payments
/services/payments/webhooks/  @acme/payments @acme/security

# Infrastructure and CI
/infra/                 @acme/sre
/.github/workflows/     @acme/sre

# Database migrations always need a DBA
**/migrations/          @acme/data-platform

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

Order matters: * comes first so every later, more specific line overrides it.

Example: a monorepo

*                         @acme/eng-leads

/packages/ui/             @acme/design-systems
/packages/api-client/     @acme/api
/apps/web/                @acme/web
/apps/mobile/             @acme/mobile
/apps/admin/              @acme/internal-tools

# Shared config affects everyone
/package.json             @acme/eng-leads @acme/platform
/tsconfig.base.json       @acme/platform

Example: removing ownership for a subfolder

From GitHub's docs: owners for /apps/, except one subfolder anyone with write access can approve:

/apps/          @octocat
/apps/github

Common mistakes

  • Specific rules above *. The catch-all at the bottom overrides them all.
  • Owners split across lines. Only the last line's owners count.
  • Teams without write access. The rule silently assigns nobody.
  • Using ! to exclude. It doesn't work; use an empty-owner line instead.
  • Wrong case in paths. /Services/ doesn't match /services/.
  • No owner for the file itself. Anyone can change who reviews what.

CODEOWNERS and AI-written code

As AI coding agents open more pull requests, CODEOWNERS becomes the routing layer that sends each change to someone accountable. It also tells an agent who owns a path, if you surface it: an agent about to change /services/payments/ should know the payments team owns it and what they've decided about it. See AI code review best practices.

Where Lockstep fits

CODEOWNERS says who reviews a path. Lockstep holds what the owners decided about it: captured from PRDs, Slack, and pull requests, approved by each decision's owner, and briefed to Claude Code sessions working on that code, so the agent knows the payments team's rules before the review request goes out.

See how it works.

Sources checked 16 November 2026

For what reviewers should check, see the code review checklist. For ownership of work rather than code, see the RACI chart template.

Frequently asked questions

What is a CODEOWNERS file?
A GitHub file that defines which individuals or teams are responsible for code in a repository. Code owners are automatically requested for review when a pull request modifies files they own, except on draft pull requests.
Where does the CODEOWNERS file go?
In the .github/, root, or docs/ directory, on the branch where you want it to apply. Pull requests use the CODEOWNERS file from their base branch. Each file assigns owners for one branch.
How does CODEOWNERS ordering work?
The last matching pattern takes precedence. Put broad defaults like * at the top and more specific paths below. A pattern with no owners after it removes ownership for that path.
How do I assign multiple owners to one path?
Put them all on the same line, separated by spaces. GitHub's docs warn that if owners for the same pattern are on separate lines, only the last one applies.
Can CODEOWNERS require approval before merging?
Yes. An admin can enable required reviews and optionally require approval from a code owner before a pull request can be merged, through branch protection or rulesets.

Keep reading