A pull request can be easy to review and still reach the wrong people. CODEOWNERS gives a repository a path-based map of who should review which area. It is particularly useful when documentation, service code and automation belong to different maintainers. The map routes reviews; a separate merge rule determines whether an owner's approval is required. This lesson builds a small ownership policy and works through its results. The example handles are fictional: replace them with eligible users or visible teams that have explicit write access before testing on GitHub.
Start with a review responsibility map
List the areas of the project and the people who can maintain them. Choose teams when responsibility should survive an individual person's absence, but check that the team is visible and has the necessary repository access. A team name in a text file does not grant that access. Keep the initial map small enough that a newcomer can explain it. A useful ownership policy should make review routing clearer rather than encode every historical contributor as an owner.
Separate ownership from expertise and from administrative authority. An owner is a requested reviewer for matching files, not the only person permitted to read or edit them. A contributor can still propose changes to an owned path. Your collaboration process should explain what to do when the owner is unavailable and how a replacement is selected. Avoid letting the ownership file become the only place where responsibilities are documented; reviewers also need enough project context to make a good decision.
Work through ordered patterns
GitHub finds CODEOWNERS in .github, the repository root or docs, in that search order, and uses the first file found. Keep one intentional location so contributors do not edit an ignored copy. Paths are case-sensitive on GitHub even if a developer's local filesystem is forgiving. Place broad defaults before specific rules because the last matching pattern supplies the owners for a path. A later match replaces the earlier owners rather than automatically accumulating them.
When a path needs two potential owners, put both on the same matching line. In the example, documentation security files list the security and documentation teams together. Writing two separate lines with the same pattern would let the final one win. CODEOWNERS resembles ignore-pattern syntax but does not support every gitignore feature, including negation and bracket character ranges. Test representative paths on GitHub and inspect the file's highlighted errors instead of assuming that a complex local glob behaves identically.
Use the base branch as the policy source
A pull request uses the CODEOWNERS policy on its base branch. A proposed ownership change in the pull request therefore does not immediately redefine who reviews that same request. This is useful when reviewing a contribution that attempts to change the review policy itself. Read the branch context when comparing results across a release branch and the default branch; each branch may intentionally have a different ownership map.
Protect the CODEOWNERS path with an explicit owner entry and the repository's review rules. That makes policy edits visible to the maintainers responsible for the review process. A broad default alone can accidentally be overridden by a later .github rule, so inspect the final matching line for the ownership file itself. Treat workflow and ownership changes as consequential project changes: their diff may be small, but they influence who reviews or executes later contributions.
Make enforcement a separate reviewed choice
Automatic review requests do not by themselves make approval a merge condition. Configure the applicable branch protection or ruleset to require the intended reviews and code-owner approval where supported. Consider how ordinary reviewer counts, stale approvals and other checks interact. If several owners appear on one line, do not assume every listed person must approve; the configured review requirement determines what satisfies the gate.
Test the policy with a small pull request against the intended base branch. Verify which reviewers are requested and which merge conditions are shown. Draft pull requests do not automatically request owner review in the same way as ready requests, so test the ready state as well. If a user or team is not assigned, inspect spelling, access, visibility, pattern order and syntax errors. Keep availability assumptions explicit, because supported enforcement depends on repository visibility, account plan and the specific feature.
Sources and prerequisites
Start with code review, pull requests and teams. Consult GitHub's CODEOWNERS reference, review reference, protected branch settings and repository API.
GitHub CODEOWNERS Patterns and Review Requirements Summary
- Use final-match precedence and keep owners together on one line.
- The pull request's base branch supplies its ownership policy.
- Test automatic requests and required approvals as separate behaviors.
GitHub CODEOWNERS Patterns and Review Requirements Examples
Each example shows the code, the output it produces and what each part does.
A complete small ownership file
Create .github/CODEOWNERS with the following content in a practice repository. The output is a worked prediction of path ownership after evaluating the rules, not terminal output or evidence of a live GitHub review request. Replace demo-org teams with real eligible teams and confirm the result on the intended base branch.
The security path has both teams because they appear together on its final matching line. It does not additionally inherit maintainers from the wildcard rule. Review these four paths on GitHub after the policy is present on the base branch, then inspect whether merge rules actually require the intended approval.
# Broad default first
* @demo-org/maintainers
# Documentation subtree
/docs/ @demo-org/docs
# A later, more specific rule replaces the default docs owner
/docs/security/ @demo-org/security @demo-org/docs
# Review changes to the policy itself
/.github/CODEOWNERS @demo-org/maintainerssrc/server.js -> @demo-org/maintainers
docs/start.md -> @demo-org/docs
docs/security/access.md -> @demo-org/security @demo-org/docs
.github/CODEOWNERS -> @demo-org/maintainersCommon GitHub CODEOWNERS Patterns and Review Requirements Mistakes
Assuming owner lists require unanimous approval
Listing multiple owners supplies eligible ownership reviewers. It does not by itself specify that every listed team must approve. Inspect and test the separate repository review settings when you need a precise approval policy.
GitHub CODEOWNERS Patterns and Review Requirements in Real Projects
Add an API documentation team to CODEOWNERS
Add an API-documentation team while preserving documentation involvement for that subtree. The worked solution is the full file, with the new rule after the general docs rule. Predict the owner set for an API page and a non-API page before checking the two results.
* @demo-org/maintainers
/docs/ @demo-org/docs
/docs/api/ @demo-org/api @demo-org/docs
/docs/security/ @demo-org/security @demo-org/docs
/.github/CODEOWNERS @demo-org/maintainersdocs/api/endpoints.md -> @demo-org/api @demo-org/docs
docs/start.md -> @demo-org/docsIf the new rule appeared before /docs/, the later general docs rule would replace its result. That ordering mistake is easy to make when arranging a file alphabetically. Organize rules by intended precedence and keep a few representative path cases in the policy review.
GitHub CODEOWNERS Patterns and Review Requirements FAQ
Why did my more specific CODEOWNERS rule have no effect?
Check the order as well as the pattern. GitHub uses the last matching rule, so a later broad rule can replace an earlier specific one. Also confirm the file location, base branch, path case and syntax. Work through one actual changed path from top to bottom and identify its final match. Then check that the named users or teams exist and have the necessary repository access.
Can a contributor change who reviews their own pull request?
A pull request's owner requests use the CODEOWNERS file from its base branch. Proposed changes to the file are reviewed as changes rather than immediately becoming that request's routing policy. Keep an ownership rule for CODEOWNERS itself and require appropriate review through repository settings. This creates a visible policy-change process, although administrators and configured bypass actors still need to be accounted for in the repository's governance.
Why does a listed team receive no owner review request?
Verify that the team is visible and has explicit write access, then check its organization and slug. Individual members having access is not necessarily the same as the team having the required access. Inspect pattern matching and syntax errors too, and ensure you are testing a ready pull request against the branch containing the intended file. A plausible-looking handle alone does not establish valid ownership.
Does adding CODEOWNERS stop unapproved merges immediately?
No. The file defines ownership routing, while an applicable merge rule must require code-owner approval if that is your intent. Configure and test the review requirement separately alongside checks and other restrictions. Review any bypass permissions and feature availability for your repository. Use a practice pull request to observe the actual merge conditions rather than treating the existence of a CODEOWNERS file as proof of enforcement.
GitHub CODEOWNERS Patterns and Review Requirements Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
In the main ownership file, which teams own docs/security/access.md?
GitHub CODEOWNERS Patterns and Review Requirements Quiz
2 questions to check what you learned.
Which CODEOWNERS version routes a pull request's owner review requests?
- Always the version from the contributor's laptop
- The newest file found in any fork
- The version on the pull request's base branch
What turns code-owner approval into a merge requirement?
- An applicable repository review rule
- Only adding a wildcard owner line
- Renaming the file to lowercase