On this page
A CODEOWNERS file maps path patterns to the people or teams who are responsible for that code, so that GitHub and GitLab can request their review automatically on every change. The last matching pattern wins, and the file only blocks a merge when you turn on code owner approval for the branch.
This guide covers the syntax and precedence checked against the GitHub and GitLab docs on 15 November 2026, the mistakes that silently break the file, and a way to draft or audit one from git history so it reflects who actually changes each path.
Where does the CODEOWNERS file go?
GitHub looks for CODEOWNERS in .github/, the repository root, then docs/, and uses the first one it finds (as of November 2026, per GitHub's code owners docs). Each file applies to one branch, and for review requests it must exist on the pull request's base branch. Files must be under 3 MB or GitHub does not load them.
GitLab checks a different order: ./CODEOWNERS, then ./docs/CODEOWNERS, then ./.gitlab/CODEOWNERS, and ignores the rest (per GitLab's code owners docs). Code owners is a Premium and Ultimate feature on GitLab.
| GitHub | GitLab | |
|---|---|---|
| Lookup order | .github/, root, docs/ | root, docs/, .gitlab/ |
| Precedence | Last matching pattern wins | Last matching entry wins, per section |
| Sections | No | Yes, [Section], ^[Optional], [Section][2] |
| Owners | @user, @org/team, email | Users, groups, sections with default owners |
| Enforcement | Branch protection: Require review from Code Owners | Protected branch with Code Owner approval enabled |
Scroll the table sideways to see every column.
What is the CODEOWNERS syntax?
Each line is a gitignore-style pattern followed by one or more owners. Lines starting with # are comments.
# Default owner for everything
* @acme/platform
# Any file with this extension, anywhere
*.sql @acme/data
# A directory and everything under it
/billing/ @acme/payments @dana
# Files directly in docs/, not nested ones
docs/* docs@acme.com
# Nested files too
/web/src/**/*.tsx @acme/frontend
# Protect the file itself
/.github/CODEOWNERS @acme/eng-leads
Patterns follow most gitignore rules. A leading / anchors to the repository root, a trailing / matches a directory, * matches within one path segment and ** crosses segments. Paths are case-sensitive, even on case-insensitive systems such as macOS. Three gitignore features do not work in GitHub's version: escaping a leading #, negating with !, and character ranges with [ ].
How does CODEOWNERS precedence work?
The last matching pattern takes precedence, so order the file from general to specific. Put the * default at the top and the narrow rules below it. If /billing/ appears before *, the default overrides it and the billing team never gets a request.
* @acme/platform # applies to everything not matched below
/billing/ @acme/payments # wins for anything under billing/
A file under billing/ has one owner entry in effect, @acme/payments. It does not accumulate owners from every matching line. To require two groups for the same path, list both owners on the same line.
GitLab applies the same last-match rule inside each section, and a path that matches entries in several sections picks up the last match in each. That is how GitLab expresses "payments and security both review this": two sections, each with its own owner. Section names are case-insensitive, same-named sections are merged, and approval counts, optional sections and default owners apply to protected branches only.
[Payments][2] @acme/payments
/billing/
^[Docs] @acme/docs
/docs/
In that file, /billing/ needs two approvals from the payments group, and the optional ^[Docs] section asks for review without blocking the merge request.
What are the most common CODEOWNERS mistakes?
Most broken CODEOWNERS files fail silently, because GitHub skips invalid lines and shows the problem only if you open the file. These are the usual ones.
| Mistake | What happens | Fix |
|---|---|---|
| Owners on separate lines for the same pattern | Only the last line applies | Put all owners on one line |
Default * placed at the bottom | It overrides every rule above it | Put * first |
| Team without write access | The team is not assigned as an owner | Grant the team write access on the repo |
| Owner is a user who left the org | Pattern has no effective owner | Audit owners against current members |
docs/* expected to cover subfolders | Nested files are unowned | Use docs/ or docs/** |
Using ! to exclude a path | Not supported, line ignored or wrong | Add a later, more specific pattern with another owner |
| Branch protection not enabled | Owners are requested but cannot block the merge | Enable Require review from Code Owners |
| CODEOWNERS only on a feature branch | No owners requested for PRs into main | Merge it to the base branch |
| Nobody owns CODEOWNERS | Anyone can change who reviews what | Add /.github/CODEOWNERS with an owner |
Scroll the table sideways to see every column.
GitHub highlights errors when you view the file in the web UI and exposes them through the REST API. Check it after every edit. Approval from any one listed owner satisfies the requirement on GitHub, so two owners on a line means either, not both.
How do you generate a CODEOWNERS file from git history?
Start from who actually changes each path, not who the org chart says should. A hand-written CODEOWNERS file reflects intent on the day it was written. Git history reflects what happened since: the engineer who rewrote the billing module, the one who owns every migration, the owner who left a year ago.
Count commits per author for a path over the last 12 months:
git log --since="12 months ago" --no-merges --format='%aN <%aE>' -- billing/ \
| sort | uniq -c | sort -rn | head -5
Run it per top-level directory and write a draft. This script prints the top committer's email for each directory, and GitHub accepts an email address as an owner when it is added to the person's account (not for managed user accounts):
#!/usr/bin/env bash
since="12 months ago"
echo "# Draft generated from git history ($(date +%F)). Review before committing."
for d in $(git ls-tree -d --name-only HEAD); do
top=$(git log --since="$since" --no-merges --format='%aE' -- "$d" \
| sort | uniq -c | sort -rn | awk 'NR==1{print $2}')
[ -n "$top" ] && echo "/$d/ $top"
done
We ran it on the repowise.dev frontend repository on 15 November 2026. The output, with the emails replaced:
# Draft generated from git history (2026-11-15). Review before committing.
/.github/ owner@example.com
/__tests__/ owner@example.com
/blogs/ owner@example.com
/content/ owner@example.com
/docs/ owner@example.com
/public/ owner@example.com
Treat this as a first draft. Replace emails with @handles or teams (a team is better than a person, since people leave), and add a * default at the top. Then audit an existing file the same way: for each pattern, compare the declared owner with the top committer, and flag lines where the declared owner made no commits in 12 months.
git log --since="12 months ago" --no-merges --format='%aN' -- billing/ \
| sort | uniq -c | sort -rn
If the declared owner is not in that list, the line is stale.
How does repowise help with code ownership?
repowise computes ownership for every file from git history during indexing, so you do not have to script it. It records the primary owner (by surviving lines from git blame), the recent owner over the last 90 days, each owner's commit share, and the file's bus factor.
pip install repowise
repowise init --yes --no-prose
repowise context billing/invoice.py --include ownership
The output includes primary_owner, owner_pct, recent_owner and bus_factor, the same fields agents get from the get_context MCP tool. Where the primary owner and the recent owner differ on a file that is still changing, repowise flags a knowledge_loss finding, which is exactly the file whose CODEOWNERS line is probably wrong. get_risk also lists up to five recommended reviewers for a set of changed files, ranked by how many of them each person owns.
repowise also reads declared owners from CODEOWNERS (GitHub, and GitLab with sections) when it maps components, so declared and observed ownership sit side by side. Ownership data is the input; you still decide what goes in the file, and the team handle is the part only you know.
Across 195 popular open-source repositories (1,000+ stars, November 2026, production code only), the median repo had a bus factor of 1 on 60% of its files, and 25% of hotspot files (34% pooled across all hotspot files) had a bus factor of 1 as well. The method and tables are in the state of open-source code health report. If one person made 80% or more of the commits on a path, a CODEOWNERS line naming a single user there is accurate and fragile at once. See what is bus factor for how to read that number.
For the full workflow, see code ownership analysis from git history, and for other tools compared, best code ownership and bus factor tools.
FAQ
- What is a CODEOWNERS file?
- A CODEOWNERS file is a plain-text file in a repository that maps file path patterns to users or teams. GitHub and GitLab use it to request review from the matching owners on pull requests and merge requests, and can require their approval before merging.
- Where do I put the CODEOWNERS file on GitHub?
- Put it in
.github/, the repository root ordocs/. GitHub checks them in that order and uses the first one it finds. The file must be on the pull request's base branch for review requests to work. - Does the last or first matching pattern win in CODEOWNERS?
- The last matching pattern wins on both GitHub and GitLab. Put broad rules such as
*at the top and specific paths below them. An owner on a broad rule that sits below a specific one will override it. - Can CODEOWNERS use teams and email addresses?
- Yes. GitHub accepts
@username,@org/team-nameand, for most accounts, an email address attached to a user. Every owner needs explicit write access to the repository, and a team must be visible. Owners without it are not assigned. - Does CODEOWNERS block merges?
- Only if you enforce it. On GitHub, turn on Require review from Code Owners in a branch protection rule; approval from any one listed owner satisfies it. On GitLab, the target branch must be protected with Code Owner approval enabled.
- How do I generate a CODEOWNERS file automatically?
- Count commits per author for each directory with
git logandgit shortlog, take the top committer or team per path, and write them as owner lines. Then review the draft by hand. A tool like repowise gives you primary owner, recent owner and bus factor per file to start from.

