Setting up GitHub's CODEOWNERS

github CODEOWNERS shared repository PR review

2 min read | by Jordi Prats

GitHub's CodeOwners file is a tool that helps teams manage and maintain their repositories more effectively when the repository is co-owned by multiple teams. The file allows you to assign code ownership to teams or specific individuals. This will make them responsible for reviewing and approving changes to the code.

To set it up we will need to be have either admin or owner permissions in the repository. The people (or teams) we choose as code owners must have write permissions for the repository. It's worth emphasizing that we'll need to give write permissions to the teams we use, even if all the individual members of the team already have write permissions directly, through organization membership, or through another team membership.

The CODEOWNERS file itself is a plain text file, typically located in the root of a repository or the .github folder. Each file assigns the permissions for a specific branch, making it possible to set different code owners depending on the branch.

A CODEOWNERS file would look like this:

# Owners for all files in the repository
*       @owner1 @owner2

# Owners for all JavaScript files
*.js       @javascript-team

# Owners for all Markdown files in the `docs` directory
docs/*.md      @documentation-team

When a pull request is submitted, GitHub will check the CODEOWNERS file to determine the code owners who should be notified of the change. For example, in the previous example any change in .js would notify the @javascript-team. Similarly, for a Markdown file in the docs directory would notify @documentation-team. And if the pull request affects any other file in the repository, @owner1 and @owner2 will be notified.

Having this file in shared repositories will help teams ensure that changes to the code are reviewed by the appropriate individuals, and that responsibilities are distributed effectively within the organization.

Posted on 02/02/2023