In this article we will present the Code Owners concept from top to bottom, dive into the details with more advanced use cases and give you best practices and Code owners tips to enhance and secure your review processes.
Table of Contents
- What is code owners and why do I need it?
- When do I need code ownership?
- How do I implement it for my teams?
- Real life challenges
- How do I get started with Code Owners in an existing code base?
- Takeaways
What is code owners and why do I need it?
What compliance tells us about secure code review processes
The bodies responsible for setting industry standards or managing certifications with regards to secure software like SOC2, PCI DSS, OWASP and SAFECode provide general guidelines for a secure code review process.
Overall, a secure process can be broken down into these 4 steps:
- A well-built Pull Request (delimited scope and purpose, well-written code, clear title and description)
- A relevant set of reviewers
- Guidelines and best practices for code review
- Safeguards to ensure no changes are merged without proper review
What are relevant reviewers?
According to the OWASP Code Review Guide, reviewers should be people that have...
What could be an ideal combination of reviewers?
It depends on the size of the company and the industry regulation. This is not a one size fit all situation.
The level of scrutiny each Pull Request should go through can of course differ from a small company that may want a pair of reviewers, to a bigger company that may need several reviewers focused on different aspects of the Pull Request.
For a company looking to comprehensively cover functional and security aspects, a common configuration could be to include two types of reviewers:
Identifying the relevant set of reviewers for each specific Pull Request can be a real challenge, even more so to do it repeatedly. So how do you pick a relevant set of reviewers consistently and at scale? Introducing the concept of Code Owners.
What are code owners?
Code Owners are users or shared groups responsible for specific code parts.
They are usually experts with the parts of the codebase they own, and ensure that any changes meet the quality, style, and functionality standards.
Example:
The idea is for Code Owners to be automatically requested for review when someone opens a Pull Request that modifies code that they own.
Example:
Who came up with the idea of Code Owners?
Here is a short history of the concept:
- 2015: First introduced in Open Source Project Chromium. We recommend this post from 2015 by Monica Dinculescu about the owners feature for Chromium.
- 2017: Introduced in GitHub
- 2018: Introduced in GitLab
- 2023: Introduced in Bitbucket
Is Code Owners incompatible with the agile practice of Share/Collective Code Ownership?
This is an interesting point as the agile methodology promotes a shared approach of code ownerships where all users should be able to review each part of the codebase. Is Code Owners an anti-pattern then?
Well we think not because:
- Every team member is still allowed to contribute, Code Owners just act as gatekeepers and knowledge experts to keep quality high.
- The shared ownership principle makes sense for small codebases, but has its limits for larger code bases. It is nearly impossible to know and be efficient with every part of a large code base.
- Code Owners mostly relies on team/group ownership rather than individual ownership, which still allows to share the knowledge among several individuals.
When do I need code ownership?
Whatever your organization and the level of scrutiny you want for your Pull Requests, you can adapt the Code Owners rules to fit your needs. Code Owner rules can cover a lot of different use cases and code coverage policies.
Customers usually define the followings types of code ownership:
- Targeted ownership - specific review teams/individuals for specific:
- Overall ownership for key stakeholders
Example of a possible Code Owners configuration
This very simple example shows how you could define rules per type of ownership.
A real life example
A number of open source projects use Code Owners. As an illustration we took the php-docs-sample repository from Google Cloud Platform.
The need for Code Owners can stem here from the various type of resources maintained in this repository that has over 150 contributors.
In this example, one reviewing team is the default one and different types of samples are owned by specific teams or individuals.
How do I implement it for my teams?
Good news: a standardized implementation across platforms
Whatever platform you are using (GitHub, GitLab, Bitbucket), the rules are defined in a similar way.
In terms of format and location, they are defined in a plain text file.
The rules are defined using a pattern syntax in line with the .gitignore standards.
Here is how it works:
Example that works for GitHub, GitLab and Bitbucket:
docs/* @tech-writer-team
*.rb @dev-team
CODEOWNERS @cto
CODEOWNERS files can be committed at the root of a repository or in specific folders depending on the platform.
Example with GitHub
Here is an example CODEOWNERS file and the results in the GitHub Pull Request UI.
# Lines starting with '#' are comments.
# Each line is a file pattern followed by one or more # owners.
# These owners will be the default owners for
# everything in the repo.
* @defunkt
# Order is important. The last matching pattern has
# the most precedence.
# So if a pull request only touches javascript files,
# only these owners will be requested to review.
*.js @octocat @github/js
# You can also use email addresses if you prefer.
docs/* docs@example.com
Enforcing reviews
Great, I can assign reviewers automatically with Code Owners. What now?
Well next, you want to secure your review process with merge checks.
The goal is for all your changes to go through an actual review and a validation from your code owners.
If we take our previous example from GitHub:
Real life challenges
So we can assign reviewers and enforce the review. Are we all set? Not quite, in a real life usage you might end up with the following challenges:
- what if reviewers are absent?
- what if I have a monorepo with a lot of different applications and teams working in silos for each of them?
- what if I have 20 members in a review group and they all get added and bothered for each PR?
- what if I want to have more flexible merge checks?
Let's see together how we can tackle these challenges.
What if reviewers are absent?
So if my Code Owners are absents, how can my Pull Request be reviewed and approved?
Solution
Repository owners and administrators can merge a Pull Request even if it hasn't received an approving review.
This can be done in GitHub, GitLab and Bitbucket.
Going further
With Bitbucket: The plugin Code Owners for Bitbucket has a feature allowing to auto assign fallback reviewers counted in merge checks quota
@@@FallbackOwners @paul @monica
What if have a monorepo?
What if I have a monorepo and a pattern should have different reviewers depending on the app?
Solution
You can use the file/ folder path for reviewer assignment.
/apps/app1/ui/ @UX_TEAM1
/apps/app2/ui/ @UX_TEAM2
This can be done in GitHub, GitLab and Bitbucket.
Going further
With GitLab: GitLab implemented sections to easily organize the reviewers rules.
[app1]@TEAM1
/apps/app1/
/apps/app1/ui/ @UX_TEAM1
[app2]@TEAM2
/apps/app2/
/apps/app2/ui/ @UX_TEAM2
With Bitbucket: Code Owners for Bitbucket supports project/path specific CODEOWNERS files.
/apps/app1/CODEOWNERS
ui/ @UX_TEAM1
/apps/app2/CODEOWNERS
ui/ @UX_TEAM1
What if too many users get added for each PR?
How can I avoid creating distraction through notifications and unnecessary work (efficiency threshold effect) when my code owners groups are very large?
Solution
Have random assignment of a subset of users. Also helps to reduce potential code owners burnouts.
This has been implemented only by GitHub so far documentation link.
Going further
With Bitbucket: The plugin Code Owners for Bitbucket has a random assignment feature.
CODEOWNERS.toplevel.assignment_routing random 2
What if I need flexible merge checks?
How can I require a minimum number of reviewers instead of all in my merge checks?
Solution
Offer flexible merge checks, requiring only a specific amount of approvals from the code owner groups.
This is possible in GitLab per section - documentation link.
Going further
With Bitbucket: The plugin Code Owners for Bitbucket offers a feature to choose the number of reviews required overall, per group or conditionally.
**/*.java @@Seniors @@Juniors
(Check(@@Seniors >= 1) | Check(@@Juniors >= 2))
How do I get started with Code Owners in an existing code base?
here are a few steps that you could take to introduce Code Owners within your organization.
Step 1: Identify Key Areas
- Repository Audit: Identify key areas, modules, and components.
- Complexity Analysis: Find out where Code Owners are most needed.
Step 2: Define Code Ownership Rules
- Select Owners: Choose teams best suited to own certain code parts. Consider their expertise, workload and interest.
- Documentation: Clearly document the areas of responsibility for each Code Owner group.
Step 3: Training and Transition
- Training Sessions: Do training sessions for the team to understand the new concept.
- Gradual Implementation: Start with a few areas and gradually expand to avoid overwhelming the team.
Step 4: Monitor and Adjust
- Feedback Loop: Regularly collect feedback from the team and adjust the process as needed.
- Review Burden: Monitor if certain Code Owners are getting overloaded and redistribute ownership if necessary.
Takeaways
Here is in a nutshell what you should remember from this article:
- Code Owners is a helpful concept to ensure Pull Requests are actually reviewed by knowledgeable reviewers
- The concept is now widely accepted and implemented by all major code hosting platforms
- For compliance purposes, Code Owners is useful to consistently address the issue of assigning relevant reviewers. However, for a secure code review process, you also need (i) documented and comprehensive review guidelines (eg checklists) and (ii) merge checks to ensure only changes vetted by code owners can be merged
Try Code Owners
You can play around with how Code Owners rules are constructed in our Code Owners Playground.
You can also use the following links to get access to the documentation of Code Owners for: