CODEOWNERS

CODEOWNERS is a text file in the repo where each line maps a glob pattern to an owner (a team or a user). When a PR is opened, GitHub reads CODEOWNERS, checks the changed files, and automatically adds the owners to the reviewers list.

Location

GitHub looks for the file in three places:

• .github/CODEOWNERS (most common)
• CODEOWNERS in the root
• docs/CODEOWNERS

Keeping it in .github/CODEOWNERS is usually the most convenient: all GitHub-specific configuration lives in one place.

Syntax

Similar to .gitignore, but instead of ignoring, it assigns an owner:

# global fallback

*           @acme/leads

# backend

/backend/   @acme/backend

/backend/db/migrations/   @acme/database

# frontend

/frontend/  @acme/frontend

*.tsx       @acme/frontend

# documentation

*.md        @acme/docs

# a single specific file

/SECURITY.md  @alice @bob

# OR logic: any of the listed owners

/infra/     @acme/devops @acme/sre

An owner can be:

• @username: a specific user
• @org/team-name: a team within an organization
• email@example.com: a valid email linked to a GitHub account

Last-match wins

If a file matches multiple rules, the last match wins. Put general rules at the top and specific ones at the bottom:

*               @acme/leads        # general first

/backend/       @acme/backend      # then backend

/backend/db/    @acme/database     # more specific

The file /backend/db/migration/0042.py belongs to @acme/database, not @acme/backend, because /backend/db/ is defined later and is more specific.

Combined with branch protection

On its own, CODEOWNERS only assigns reviewers. To block merge without their approval, enable "Require review from Code Owners" in branch-protection. Then:

1. A PR touches /backend/db/.
2. @acme/database is assigned.
3. Merge is blocked until someone from that team approves.

Pitfalls

• The team must have access to the repo. If you reference @acme/database in CODEOWNERS but the team is not added under Settings -> Manage access, GitHub skips the assignment.
• Owner is not the same as author. CODEOWNERS records who is responsible now, not who wrote the code. For authorship, see blame.
• CODEOWNERS does not grant permissions. If an owner does not have write access to the repo, their approval does not count. Grant access first (via team or direct grant), then add them to CODEOWNERS.
• Without "Require review from Code Owners" in branch protection, CODEOWNERS is only a hint about reviewers, not a blocker.