Syntax and patterns — the line format, glob rules, and the order trap

A CODEOWNERS file is a sequence of lines, most of which pair a pattern with one or more owners. The format is deliberately small: anything you can do in CODEOWNERS, you can do in a few dozen lines. What makes the format hard to get right is the order rule and the semantics of leading slashes.

The line format

Each line is <pattern> <owner1> [<owner2> ...]. Comments start with #. Blank lines are ignored. On GitHub an optional [Section] header in brackets starts a new section but has no semantic effect.

# Default owners for everything in the repo
*                        @platform/platform-infra
/terraform/              @platform/platform-infra
/terraform/prod/         @platform/platform-infra @security-team
/prod/secrets.yaml       @security-team

A line with only a pattern and no owner is invalid; the forge will report it on push. A line that references a user or team that does not exist will silently fail to assign that owner - which is one of the ways CODEOWNERS becomes documentation.

Pattern semantics

Three rules govern matching:

• A pattern without a leading slash matches anywhere in the repo. *.tf matches main.tf at the root and also modules/vpc/main.tf deep in the tree.
• A pattern with a leading slash is anchored at the repo root. /main.tf matches only the file main.tf at the root; modules/vpc/main.tf is not matched by /main.tf.
• A pattern ending with / matches directories recursively. /terraform/ matches every file under /terraform/.

Glob characters are * (single path segment), ** (any sequence of segments), ? (single character), and [abc] (character class).

cat .github/CODEOWNERS

A worked example, given terraform/prod/iam/main.tf:

*.tf            @platform/platform-infra
/terraform/     @platform/platform-infra
/terraform/prod/ @platform/platform-infra @security-team
main.tf         @platform/platform-infra

The file is matched by the first three lines and not by the fourth. All matching owners accumulate.

The order rule

When two lines match the same path, the last matching line wins. This is the rule that produces the most subtle bugs.

/terraform/     @platform/platform-infra
/terraform/prod/ @security-team

For a file under /terraform/prod/, both lines match; the second wins, so the owners are @security-team. For a file under /terraform/staging/, only the first line matches, so the owner is @platform/platform-infra.

flowchart LR
    A[Path under review] --> B[Walk CODEOWNERS top to bottom]
    B --> C{Line matches?}
    C -->|yes| D[Add owners to running set]
    D --> E{More lines?}
    E -->|yes| B
    E -->|no| F[Final set of owners]
    C -->|no| E

The “last match wins” rule applies to the primary assignment in GitLab semantics; on GitHub all matching lines accumulate owners. The semantic differences between forges matter and are revisited in the next lesson.

Validating the file

There is no canonical codeowners-lint, but every forge reports syntax errors on push. The practical validation is to open a PR that touches one path per rule, confirm the right reviewers are assigned, and confirm the merge is blocked until they approve.

git ls-files | grep CODEOWNERS

Production discipline

Treat CODEOWNERS changes as code changes: open a PR, get two reviewers, run a test PR through the forge, and confirm the reviewer list matches the expectation. A CODEOWNERS rule that has never been exercised against a real PR is a rule that has not been validated.

Cross-course references

• Ansible for Production Sysadmins - Part XXXIX (InventoryPatterns) covers glob matching against inventory; CODEOWNERS globs are the same shape.

Quiz