> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Code Review With a Codeowners File
> Explains GitHub CODEOWNERS files assigning ownership of files and directories to auto-request reviewers, pattern rules, placement options, and branch protection effects.
What is a CODEOWNERS file?
A `CODEOWNERS` file defines which people or teams are responsible for specific files, directories, or patterns within a GitHub repository. By assigning ownership, you ensure that changes touch the right subject matter experts and that required code reviews are requested automatically when those files change. This improves review quality, speeds up onboarding, and helps enforce governance through branch protection rules.
Where to put the CODEOWNERS file
GitHub recognizes a `CODEOWNERS` file when placed in any of these repository locations:
* The repository root
* The `.github/` folder
* The `docs/` directory
A typical repository layout with `CODEOWNERS` files might look like this:
```text theme={null}
my-project-repo/
├── .github/
│ └── CODEOWNERS
├── docs/
│ └── CODEOWNERS
├── src/
│ └── app.py
├── LICENSE
└── CODEOWNERS
```
Recommended locations and behaviors
| Location | Purpose | Notes |
| ---------: | -------------------------------- | ------------------------------------------ |
| Root | Global rules for the repository | Applied to most repos; easy to find |
| `.github/` | Centralized repo configuration | Useful for shared config across many repos |
| `docs/` | Documentation-specific ownership | Scope ownership to docs-only changes |
Assigning owners using patterns
`CODEOWNERS` uses pattern matching similar to `.gitignore`. Patterns can target extensions, filenames, or directories. Owners are GitHub users or teams in the form `@username` or `@org/team`.
Examples:
```text theme={null}
# All JavaScript files require review from @sidd-harth-2
*.js @sidd-harth-2
```
```text theme={null}
# Multiple owners: individual and an organization team
src/components/*.py @alice @my-org/frontend-team
```
Pattern rules and precedence:
* Patterns are evaluated top-to-bottom; the last matching pattern wins.
* Use directory-level rules (for example, `docs/`) to reduce maintenance overhead.
* Prefer teams (`@org/team`) to avoid single-person bottlenecks.
Behavior in pull requests
When a pull request modifies files that match a `CODEOWNERS` pattern, GitHub automatically requests reviews from the designated owners. If branch protection is configured to require code-owner approvals, the pull request will be blocked from merging until a required owner submits an approved review.
This can result in a pull request appearing blocked even when all other checks (CI, status checks) have passed. For example, a PR that modifies `*.js` and has `*.js @sidd-harth-2` in `CODEOWNERS` will request a review from Siddharth; the PR remains blocked until he approves.
This pull request is currently blocked, and to unblock this, a user named Siddharth must review the changes and submit an approved review.
Once an owner submits an approved review, the required review check will be satisfied and the pull request will be unblocked. Keep in mind branch protection can enforce additional conditions such as multiple required approvers or passing CI checks, so code-owner approval may be one of several merge requirements.
Best practices: Keep `CODEOWNERS` concise and focused. Favor directory-level patterns over many file-level entries, add organization teams (`@org/team`) where possible, and remember that the last matching pattern in the file takes precedence. For more advanced branch protection and review settings, see the GitHub documentation.
Links and references
* [GitHub CODEOWNERS documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
* [GitHub Branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-protected-branches)