What CODEOWNERS is — a file in the repo that maps paths to owners

CODEOWNERS is a single file in the repository whose only job is to answer “who is responsible for this path?”. Every line pairs a path pattern with one or more owners. The file is plain text, lives under version control, and is read by the forge when a pull request touches one of the listed paths.

Where the file lives

Each forge looks in a slightly different place. GitHub searches .github/CODEOWNERS, CODEOWNERS, then docs/CODEOWNERS (first match wins). GitLab searches .gitlab/CODEOWNERS, CODEOWNERS, or a configured path. Bitbucket expects CODEOWNERS at the repo root.

ls .github/CODEOWNERS
cat .github/CODEOWNERS
git ls-files | grep CODEOWNERS

The third command is authoritative: it shows the tracked copy, not whatever happens to exist in a clone. An untracked CODEOWNERS file is invisible to the forge.

What the file contains

Each non-comment line pairs a pattern with one or more owners. A minimal example for an infrastructure repository:

*                  @platform/platform-infra
/terraform/        @platform/platform-infra
/terraform/prod/   @platform/platform-infra @security-team
/prod/secrets.yaml @security-team

The file is data. It does not, by itself, prevent anything. A CODEOWNERS file with no branch protection attached is a file that documents ownership and nothing more.

flowchart LR
    A[Pull request opened] --> B[Forge reads CODEOWNERS]
    B --> C{Path matches a rule?}
    C -->|yes| D[Assign those owners as reviewers]
    C -->|no| E[Fall through to default reviewers]
    D --> F{Branch protection requires code-owner review?}
    E --> F
    F -->|yes| G[Merge blocked until owners approve]
    F -->|no| H[Owners assigned but not required]

How forges interpret the file

All three major forges use CODEOWNERS to assign reviewers, but they differ on whether the assignment is a suggestion or a gate. GitHub consults the file for suggested reviewers by default; the branch protection setting “Require review from Code Owners” promotes the suggestion to a requirement. GitLab uses the file as the source for a codeowners approval rule, which must be promoted in protected-branch settings. Bitbucket routes to owners, and a branch permission decides whether owner approval is required.

In every case the file is a list of paths and owners; what the forge does with the list is configured elsewhere.

Production discipline

A new CODEOWNERS file is a control with three dependencies. The file is tracked. Branch protection requires reviews from Code Owners on every branch that matters. The teams referenced in the file exist, have members, and have members with merge rights. If any of those three is missing, CODEOWNERS is documentation, not a control.

Cross-course references

• Linux for Production Sysadmins - Part XII (RepoSecurity) covers repository trust at the system level; CODEOWNERS is the team-level analogue.
• Ansible for Production Sysadmins - Part XXXVIII (RBACIntegration) covers role-based access patterns that map onto CODEOWNERS teams.

Quiz