A modern guide to CODEOWNERS
Tags: github, codeowners
Published: 2023-11-01 18:51:17

---
title: A modern guide to CODEOWNERS
published: true
date: 2023-10-31 15:24:47 UTC
tags: github,codeowners
canonical_url: https://www.aviator.co/blog/a-modern-guide-to-codeowners/?utm_source=rss&utm_medium=rss&utm_campaign=a-modern-guide-to-codeowners
---

![](https://www.aviator.co/blog/wp-content/uploads/2023/10/CODEOWNERS-1024x650.jpeg)

In software development, numerous people touch the same code, and it’s crucial to keep track of who is responsible for what. This is where `CODEOWNERS` come into play.

The `CODEOWNERS` feature allows you to specify individuals or teams who are responsible for code in a repository, making it easier to manage your projects. This feature can streamline the review process, enhance security, and make sure the right people are responsible for the right code.

In this guide, you’ll learn all about why you need `CODEOWNERS` and how to effectively use this feature in your software development workflow.

## Why you need CODEOWNERS

In order to outline who is responsible for different sections of a codebase, you need to create a `CODEOWNERS` file in your repository. When a pull request (PR) is opened that touches files listed in the `CODEOWNERS` file, the designated code owner is automatically asked to review that section of the code. Several popular code hosting platforms support this feature, including [GitHub](https://github.com/), [GitLab](https://gitlab.com/), and [Bitbucket](https://bitbucket.org/).

Following are some of the reasons why you should consider implementing `CODEOWNERS` into your software project:

- **Enhanced security measures:**  Defining `CODEOWNERS` creates a safeguard, ensuring that only designated users or teams can sign off on changes to specific areas of the codebase. This reduces the likelihood of unauthorized or accidental alterations to the code.
- **Streamlined review mechanism:**  When you use `CODEOWNERS`, you automate the process of identifying the most appropriate reviewers for each PR. This minimizes delays and ensures that each PR is examined by someone with domain-specific knowledge, elevating the quality of the review.
- **Increased sense of accountability:**  Allocating certain code sections to specific maintainers not only speeds up the review process but also instills a greater sense of responsibility. When you’re a named code owner, you’re more likely to be proactive about code quality, documentation, and other best practices.
- **Automated processes for greater efficiency:**  When you incorporate `CODEOWNERS` into your continuous integration, continuous delivery (CI/CD) workflows, you automate the initial step of code review. This means that the right eyes are reviewing the code quickly, which is crucial for rapid development cycles and high-velocity teams.

When you implement `CODEOWNERS`, you’re not merely inserting a file into your repository; you’re fundamentally improving how your project is managed, secured, and maintained.

## Getting started with CODEOWNERS

If you have a repository without a `CODEOWNERS` file, any member can review a PR without restrictions. This means that critical pieces of code can be modified without proper oversight.

To avoid this situation, you need to create a `CODEOWNERS` file using the following steps:

Create a new file named `CODEOWNERS` inside a `docs` folder at the root of your project. Then add your first entry like this:

```
* @your-username

```

When someone opens a PR, `@your-username` will be asked to review it.

In this scenario, let’s assume you have a sample [GitHub repository](https://github.com/See4Devs/sample-codeowners-test) with the following structure:

```
sample-codeowners-test/
|-- docs/
| |-- CODEOWNERS
|
|-- src/
| |-- hello.py
|
|-- tests/
| |-- test_hello.py
|
|-- README.md

```

> **Please note:**  Putting the `CODEOWNERS` file in the `docs` folder applies to both GitHub and GitLab. Additionally, make sure you replace the `@your-username` with your username.

To enable or disable `CODEOWNERS` in your GitHub repository, you need to define a rule set. To do so, you need to go to your repository  **Settings**  and click on  **Rules > Rulesets**  in the left navigation bar. Then enable  **Require a pull request before merging**  and  **Require review from Code Owners** :

![Enable GitHub CODEOWNERS](https://i.imgur.com/TiHA3dA.png)

If you’re using GitLab, you can enable `CODEOWNERS` on a protected branch. For more information on how to do this, refer to this [GitLab documentation](https://docs.gitlab.com/ee/user/project/protected_branches.html#require-code-owner-approval-on-a-protected-branch):

![Enable GitLab CODEOWNERS](https://i.imgur.com/PzZX2KM.png)

## Disabling CODEOWNERS

If you disable the  **Require review from Code Owners**  option in your GitHub  **Settings**  or if you remove the  **Require approval from code owners**  in GitLab, then the PR can be merged without a review from the designated code owners. While this can speed up the merge process, it does so at the expense of code quality and security:

![Disable CODEOWNERS](https://i.imgur.com/SXd8li9.png)

For all the following examples, this option is enabled.

## Avoiding common pitfalls with the CODEOWNERS file

Navigating the complexities of repository management can be challenging. Avoiding missteps in the `CODEOWNERS` file setup is crucial for streamlined code reviews.

### Create a CODEOWNERS file, but leave it empty

If you create a `CODEOWNERS` file but leave it empty, no one is assigned to review PRs. While this won’t block the PR process, you lose the advantages of having specified reviewers, which is generally not recommended.

In this scenario, any user with write access can approve code before it’s merged.

### Define a path without any users assigned

When setting up a CODEOWNERS file, it’s essential to assign users or teams to specific paths. However, consider this improper configuration:

```
src/*
tests/*

```

Here, you define two paths in your `CODEOWNERS` file: `tests/*` and `src/*`. But you don’t assign any users or teams to it. In this scenario, no one is automatically assigned to review PRs affecting files in the `tests` and `src` directories. This contradicts the purpose of using a `CODEOWNERS` file and should be avoided.

### Create a team without any members in it

In organizational setups, there may arise a need to initialize a team structure even before members are allocated. Let’s assume the `CODEOWNERS` file has the following content:

```
* @your-org/your-empty-team

```

If you define a team in your `CODEOWNERS` file (_ie_ `@your-org/your-empty-team`) but that team has no members, the PR will not have any automatic reviewers. In this case, the merge is blocked unless you add a member to the team. It’s best to make sure that each team has at least one member before adding it to your `CODEOWNERS` file:

![Team without a member](https://i.imgur.com/dJ2r5Wt.png)

## Using the CODEOWNERS file properly

Effective codebase management requires a deep knowledge of the tools available. This is why it’s crucial to understand how to properly utilize the `CODEOWNERS` file, as it facilitates precise delegation of responsibility.

### Basic ownership

If you have a simple team and want one or two people to be responsible for all code, your `CODEOWNERS` file might look like this:

```
# The user @your-username is the code owner for the entire repository
* @your-username

```

Any PR related to changes in your code needs the approval of `@your-username`:

![Code owner required to review](https://i.imgur.com/xfHSiHm.png)

### Department-based ownership

In a larger organization, you might have different departments responsible for different aspects of the code, like this:

```
# The Engineering department is responsible for all source code
src/* @Your-Org/EngineeringTeam

# The Quality Assurance team is responsible for all tests
tests/* @Your-Org/QATeam

# The Documentation team is responsible for the README file
/README.md @Your-Org/DocumentationTeam

```

Any PR related to changes under the `src` folder requires the approval of a member from the `@EngineeringTeam`. The changes in the `tests` folder require approval from a member of the `@QATeam`, and the `README.md` file require approval from the `@DocumentationTeam`:

![Team review required](https://i.imgur.com/rDouc94.png)

> **Please note:**  When specifying a team, you need to make sure that this team has `write` access to your repository. To define the team’s name, you need to put the organization name followed by a forward slash as well as the team’s name: `@Your-Org/QATeam`.

### Multilevel ownership

Sometimes, you’ll have a hierarchy of responsibilities. In this scenario, you can specify multiple code owners like this:

```
# The Core team is responsible for the entire codebase
* @Your-Org/CoreTeam

# But specific modules have additional specialized owners
src/hello.py @Your-Org/PythonExperts @Your-Org/CoreTeam

# The tests have their own owners, in addition to being under the CoreTeam
tests/* @Your-Org/TestTeam @Your-Org/CoreTeam

```

Here, a change to `src/hello.py` requires approval from someone in either `@Your-Org/PythonExperts` or `@Your-Org/CoreTeam`; whereas changes to something in the `tests` folder requires approval from either `@Your-Org/TestTeam` or `@Your-Org/CoreTeam`.

### Exclusion rules

You can also negate ownership for specific files or folders like this:

```
# The Core team is responsible for the entire codebase
* @Your-Org/CoreTeam

# Except for the hello.py, which is maintained by the Python team
/src/hello.py @Your-Org/PythonTeam

```

In this scenario, the `@Your-Org/CoreTeam` is responsible for everything except `src/hello.py`, which is the sole responsibility of the `@Your-Org/PythonTeam`.

By choosing the right setup for your team’s needs, you can use the `CODEOWNERS` file to enforce code quality and ensure that the right people are reviewing changes to different parts of your codebase.

## How team and user permissions affect CODEOWNERS

When managing code, understanding permissions is imperative. In simple terms, permissions decide who can do what in a project. Features like `CODEOWNERS` use these permissions to decide who can review and approve code changes. In order to use `CODEOWNERS` effectively, you need to know how these permissions are set and what they mean.

In GitHub, you can set permissions at an organization level, at the repository level, or within teams. Your `CODEOWNERS`settings are affected by these permissions. For instance, if a user doesn’t have write access to a repo, they can’t be a code owner.

The `CODEOWNERS` feature doesn’t operate in isolation; it’s tied to the permissions model of the platform you’re using. Say you set a team as a code owner, but individual members of that team don’t have the necessary repository-level permissions. In this case, the `CODEOWNERS` setting won’t function as expected, and the [team members won’t be able to act on the PR in the capacity of a code owner](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#codeowners-file-location). The same applies to users.

In GitLab, the permission model is similar but uses different naming conventions. You have to be at least a `Maintainer` in a project to become a code owner. Similar to GitHub, GitLab also demands a certain level of permissions for a user to be named as a code owner. Notably, the `Maintainer` role allows for a broad set of permissions, including the ability to merge code and manage the repository. This is essential for code owners to effectively review and approve code changes.

If you designate a `Developer` in GitLab as a code owner, the setting will not take effect because the user doesn’t possess the requisite permissions to enforce code ownership rules. For more information on how it works, check out the [GitLab documentation](https://docs.gitlab.com/ee/user/project/codeowners/).

Regardless of the platform you’re using, understanding the interplay between `CODEOWNERS` and permissions is critical for setting up an effective and secure code review process.

## Conclusion

In this article, you learned about the importance of implementing `CODEOWNERS` in your projects. Not only does it offer an extra layer of security by designating who can approve changes, but it also streamlines the PR review process and fosters a sense of ownership among project maintainers.

Additionally, integrating a `CODEOWNERS` file can bring about a cultural shift within your development team. It encourages clear accountability, ensuring that specific individuals or teams are responsible for particular codebases. This clarity can help prevent code rot since everyone knows who to go to for improvements or bug fixes, enhancing long-term maintainability.

Moreover, `CODEOWNERS` can serve as an excellent documentation tool. New team members can immediately understand which parts of the codebase are owned by which teams, easing the onboarding process and enhancing project transparency. It can also help external contributors identify whom they should contact for code-specific queries or clarifications, which fosters a more collaborative environment.

## [Aviator](https://www.aviator.co/): Automate your cumbersome processes

[![](https://blog.aviator.co/wp-content/uploads/2022/08/blog-cta-1024x727.png)](https://aviator.co/)

Aviator automates tedious developer workflows by managing git Pull Requests (PRs) and continuous integration test (CI) runs to help your team avoid broken builds, streamline cumbersome merge processes, manage cross-PR dependencies, and handle flaky tests while maintaining their security compliance.

There are 4 key components to Aviator:

1. **MergeQueue**  – an automated queue that manages the merging workflow for your GitHub repository to help protect important branches from broken builds. The Aviator bot uses GitHub Labels to identify Pull Requests (PRs) that are ready to be merged, validates CI checks, processes semantic conflicts, and merges the PRs automatically.
2. **ChangeSets**  – workflows to synchronize validating and merging multiple PRs within the same repository or multiple repositories. Useful when your team often sees groups of related PRs that need to be merged together, or otherwise treated as a single broader unit of change.
3. **TestDeck**  – a tool to automatically detect, take action on, and process results from flaky tests in your CI infrastructure.
4. **Stacked PRs CLI**  – a command line tool that helps developers manage cross-PR dependencies. This tool also automates syncing and merging of stacked PRs. Useful when your team wants to promote a culture of smaller, incremental PRs instead of large changes, or when your workflows involve keeping multiple, dependent PRs in sync.

[Try it for free.](http://aviator.co/)

The post [A modern guide to CODEOWNERS](https://www.aviator.co/blog/a-modern-guide-to-codeowners/) first appeared on [Aviator Blog](https://www.aviator.co/blog).

The post [A modern guide to CODEOWNERS](https://www.aviator.co/blog/a-modern-guide-to-codeowners/) appeared first on [Aviator Blog](https://www.aviator.co/blog).