If a pull request says “Code owner review required” or “Waiting on code owner review from” a user or team, the branch has Require review from Code Owners turned on, and you changed a file that a CODEOWNERS line assigns to someone. To unblock it, get an approving review from one of the owners named for that file. If nobody valid owns it, fix the CODEOWNERS line on the base branch.
Why does GitHub say code owner review required?
Two settings combine to produce it. The first is a CODEOWNERS file in .github/, the repository root, or docs/, which maps file patterns to users or teams. The second is a branch protection rule or ruleset on the target branch with Require a pull request before merging and Require review from Code Owners selected. Per GitHub’s protected branches docs, any pull request that affects code with a code owner must then be approved by that code owner before it can merge.
This is separate from the approval count. A pull request can already have the required number of approvals and still be blocked, because none of those approvals came from an owner of the files it touches. If the message you see is about approvals in general, read at least 1 approving review is required instead.
How to find which code owner needs to review
The merge box names the owners it is waiting on, and GitHub requests them as reviewers automatically when the pull request opens. Draft pull requests are the exception: owners are not requested until the draft is marked ready for review. To see why a specific file is owned by someone, open the file in the repository and hover the shield icon next to it. Per GitHub’s code owners docs, the tooltip shows who owns the file and which CODEOWNERS line made them the owner, which is the line to fix if the wrong person is named.
Last matching pattern wins in CODEOWNERS
GitHub reads the file top to bottom, and the last pattern that matches a file decides its owner. A broad rule placed below a specific one overrides it:
/billing/ @acme/payments
*.ts @acme/frontendHere a change to /billing/invoice.ts waits on @acme/frontend, not the payments team, because *.ts matched last. Put catch-all owners at the top and specific paths below them. Paths are also case sensitive, and some gitignore syntax does not work in CODEOWNERS: ! negation and [ ] character ranges are not supported. A line with invalid syntax is skipped, and GitHub highlights the errors when you open the file in the repository.
Why a code owner team can’t approve: write access
Individual owners must have write permission on the repository. A team owner must be visible and must have write permission itself, even when every member already has write access through some other route. If a user or team does not exist or has insufficient access, GitHub doesn’t assign them as an owner at all, with no error. You see a pull request whose expected reviewers never show up. Give the team write access in the repository’s access settings, or make a secret team visible.
The CODEOWNERS file also has to be on the base branch of the pull request. Editing it on your feature branch doesn’t change who owns the files in that same pull request, so fix it on the base branch first.
How to unblock a pull request waiting on code owner review
- Ask the named owner to approve. Any one owner listed for a file is enough.
- If you opened the pull request and you are the only owner, you need a co-owner, since authors can’t approve their own pull requests.
- If an owner approved and the approval vanished, it was probably Dismiss stale pull request approvals when new commits are pushed. A commit that changes the diff removes earlier approvals, the owner’s included, so they approve again.
- If the wrong owner is named, fix the pattern order on the base branch.
- If nobody was requested, check the owner’s write access and visibility.
- In a real emergency, admins and roles with bypass permission can merge past branch protection, unless the rule has Do not allow bypassing the above settings. Tell the team when you do.
Keep code owners from becoming a bottleneck
Most of the time the right owner exists and just hasn’t looked yet. Teams as owners spread the load, and one person listed on every path means one inbox holds up the whole repository. Our CODEOWNERS best practices covers how to lay out the file, and stop losing review requests covers making sure owners see the requests at all. Pyor’s pull request lists filter by Reviewer and Review state, a quick way to find the ones stuck on an owner.
Frequently asked questions
Do all code owners have to approve the pull request?
No. When Require review from Code Owners is on, an approval from any one of the owners listed for a changed file is enough. If the pull request touches files owned by different owners, each of those files still needs an approval from one of its own owners.
Can I approve my own pull request as a code owner?
No. GitHub does not let pull request authors approve their own pull requests, so if you are the only owner of a path you changed, someone else listed as an owner of that path has to approve it. Adding a team as the owner, instead of one person, avoids this.
Why is a code owner not being requested for review?
The usual causes: the CODEOWNERS file is not on the base branch of the pull request, the owner or team lacks write permission, the team is secret rather than visible, the line has invalid syntax and was skipped, or the pull request is still a draft. GitHub skips owners it cannot assign instead of failing.