Introduction

The CODEOWNERS file in GitHub is a special file that allows you to define code owners for specific files or directories in a repository. Code owners are individuals or teams responsible for maintaining and reviewing code changes in those files or directories.

Permissions for CODEOWNERS

Individuals or teams must have write permissions for the repository could create or edit the CODEOWNERS file and should be listed as code owners. People with admin or owner permissions could require that any Pull Requests must be approved by code owners before they can be merged.

The individuals you choose as code owners must have write permissions for the repository. When the code owner is a team, that team must be visible and it must have write permissions, even if all the individual members of the team already have write permissions directly, through organization membership, or through another team membership. It helps to automate the assignment of code owners for review and ensures that the specified individuals or teams are notified as reviewers when changes affect their assigned files or directories. If you want to match two or more code owners with the same pattern, all the code owners must be on the same line. If the code owners are not on the same line, the pattern matches only the last mentioned code owner.

Each CODE OWNERS file assigns the code owners for a single branch in the repository. Hence, you could assign different code owners for different branches.

Roles of CODEOWNERS file in GitHub

Code owners are automatically requested for review when someone creates a pull request and mark it as ready for review. At any point, if you mark or convert a Pull Request (PR) to the draft state again, then the individual or people who are already subscribed to notifications are not automatically unsubscribed.

When someone with admin or owner permissions has enabled required reviews, they also can optionally require approval from a code owner before the author can merge a pull request in the repository.

Different CODE OWNERS could be assigned to different types of files. For example, if any modifications are made in JavaScript (.js) files the approval request goes to a particular person or team while if any modifications are made in Cascading Style Sheet (.css) files then the approval should go to some different person or team having expertise in the respective field.

Location of CODEOWNERS file in GitHub

To use a CODE OWNERS file, create a new file called CODEOWNERS in the root, docs/ or under .github/ directory of the repository, in the branch where you would like to add the code owners.

For code owners to receive review requests, the CODEOWNERS file must be on the base branch of the pull request. For example, if you assign @user1 as the code owner for JavaScript (.js) files on the DEV branch of your repository, then @user1 would receive review requests when any Pull Request with changes made in JavaScript (.js) files is opened between the head branch and DEV branch.

Syntax of CODEOWNERS file in GitHub

# This is an example of CODEOWNERS file 
# You could assign code owners for specific files or directories
/path/of/the/file @user1 @user2 @team1
/path/of/the/directory @user2 @team2

# Default code owners for any changes
*  @globalUser

# For any specific files
*.js  @jsExpertUser

# Any team could also be assigned as code owner as below (say for any .txt files)
*.txt  @repo-org/teamName

# You could also assign code owner for any specific directory (say images). Please note, this would not match any nested files like images/web/icon.png rather it would be only applicable for images/icon.png
images/*  @imagesUser

# To apply code owner at the nested level for any directory (say '/css' directory)
/css/  @cssExpertUser1 @cssExpertUser2

# To make any user (say @logUser) for any log files located any in your repository
**logs  @logUser

# If you want to exclude any sub-directory from code owners, just left out the code owner for that directory hierarchy.
/folder/  @user1 @user2
/folder/sub-folder

File size of the CODEOWNER in GitHub

CODEOWNERS files must be under 3 MB in size and over this limit, the file would not be loaded properly, which means that code owner information is not shown and the appropriate code owners would not be requested to review changes in a Pull Request (PR).

It is highly recommended to use wildcard patterns to consolidate multiple entries into a single entry to reduce the size of your CODEOWNERS file.

Conclusion

The CODEOWNERS file in GitHub helps us to establish a clear ownership and review process for code changes within a GitHub repository. It specifies who should be notified or assigned to review the Pull Requests that modify specific files or directories. It would streamline the code review process, ensure the appropriate individuals or teams are involved in reviewing specific code changes, and promote accountability within a GitHub repository.