Code owners
As your team and products grow, expertise in areas of your code base can be fragmented between different members of the team. This can make finding the right people to notify or request reviews on changes difficult. Now, you can add code owners to your repository as a way for developers to maintain ownership over different areas of the code base. Code owners will be automatically added to pull requests in the areas of the code base they own.
When creating a new pull request, Bitbucket will automatically check if a CODEOWNERS file exists in the repository. Bitbucket checks for this file in the .bitbucket folder. If the file is found, every rule in that file is compared to the diff of your pull request. For each matching rule, the users associated with it are automatically added as suggested reviewers.
On this page:
As code owners is a branch-based config, you can have different code owners on different branches. Bitbucket will always use the CODEOWNERS file on the target branch of your pull request.
The CODEOWNERS file
Create the CODEOWNERS file under the .bitbucket folder, on your branch of choice. Compose the file using the following rules:
Every code owner rule should be declared on a separate line.
A code owner rule is composed of branch patterns referring to a path in the repository followed by any number of users.
Users are specified either by email or usernames prepended with the @ character.
Users must have the repository read permission in the target repository. Invalid identifiers or users without permission won’t be added.
Comments can be declared on a line starting with the # character.
- The CODEOWNERS files are read from the bottom to the top. So, the last rule in the file has the highest precedence.
Here’s an example of the CODEOWNERS file:
# Comments in a CODEOWNERS file are prepended with the '#' character.
# Empty lines are also ignored.
# One code owners rule is used for each changed file in a pull request.
# Rules at the bottom take precedence over rules at the top, so this rule will
# only be applied if no other rules match a given change in the pull request.
# The following rule matches all changes in the repository, so unless a rule
# lower in the file matches, globalowner will always be suggested as a code
# owner.
** globalowner@example.com
# Email addresses and Bitbucket usernames can both be used when specifying code owners:
/features/FeatureCode.java @developer-1 developer-2@example.com
# Branch patterns can match specific paths in your repository, or file types, or both.
# The following pattern will match all CSS files in the repository:
**.css @developer-1
# The following pattern will match every file in the app/frontend directory and all
# subdirectories:
app/frontend/ @developer-2
# The following pattern will match every CSS file in the app/frontend directory and all
# subdirectories:
app/frontend/**.css @developer-3
# A rule with a path and no owners is still matched and can be used to prevent code owners
# from being added for a given file. In the following pattern, changes made in the docs
# directory will include content-designer as a code owner.
# If those changes are in images, no reviewer is added.
docs/** @content-designer
docs/images/**Limits
The maximum size of the CODEOWNERS file is 500 KB. If the size is larger than this, the file won’t be read. You can increase or decrease the maximum file size by changing code.owners.maximum.filesize in shared/bitbucket.properties.
No more than 100 reviewers will ever be added automatically to a pull request regardless of how many rules match. This restriction prevents hundreds of reviewers from being added to large pull requests. You can increase or decrease the reviewer limit by changing code.owners.maximum.users in shared/bitbucket.properties.
Code owners quick add for pull request review
If code owners are set for the destination branch of your draft or regular pull request, they’ll be automatically added to it as reviewers. If you want feedback only from some of the added code owners, keep them and remove the others from the Reviewers field.
If you remove at least one code owner, the Code owners quick add button will appear under the field, showing you how many reviewers you can still add from this group.
Add reviewer groups as code owners
Starting from Bitbucket 9.0, you can set reviewer groups as code owners along with individual reviewers. By configuring the CODEOWNERS file, you can specify whether everyone from a group will be added as a reviewer to a pull request, or a particular number of users from this group.
Adding reviewer groups as code owners will save time in searching for the right reviewers, increase the quality of code review, and improve the integrity of the team’s input.
Selection strategies
Depending on how you write a rule for a reviewer group in your CODEOWNERS file, Bitbucket will use additional logic to select individual owners from that group of users. When your rule doesn’t set any explicit strategy, all users of the group will be added as code owners.
The available strategies allow you to add code owners from:
all users of the reviewer group
a particular number of randomly selected users of the reviewer group
one randomly selected user of the reviewer group
both particular and randomly selected users of the reviewer group.
By default, a reviewer group can contain up to 100 users. You can change the default number of users in a reviewer group and the maximum number of code owners through the bitbucket.properties file.
Check the following examples to learn how to set the rules for reviewer groups in the CODEOWNERS file.
Spaces in users' or reviewer groups' names need to be escaped by a double slash \\.
# Example 1: Add all users of the content-designers group as code owners
# for the files in the docs directory:
docs/** @reviewer-group/content-designers
# Example 2: Add three randomly selected users as code owners:
docs/** @reviewer-group/content-designers:random(3)
# random accepts numbers from 1 to 100. If the number of the reviewer group
# members in the rule is bigger than the actual number of members in this group,
# all members will be set as code owners.
# Example 3: Add one randomly selected user as a code owner:
docs/** @reviewer-group/content-designers:random
# Example 4: Add a particular user as a code owner along with a few other
# randomly selected users:
docs/** @John\\ Doe @reviewer-group/content-designers:random(2)
# Example 5: Add one randomly selected user from the reviewer group "Content
Designers" as a code owner
docs/** @reviewer-group/Content\\ Designers:randomWhat if two reviewer groups that you add as code owners have the same user?
Depending on which rules you’re setting for two reviewer groups with the same user, this user can be either randomly selected or always added as a code owner along with all the other members.
What if several rules are configured for one reviewer group in the CODEOWNERS file?
The application of rules depends on their order in the CODEOWNERS file. Because the rules are processed from the bottom to the top of the file, the lower rule will have more precedence. Check the following example:
docs/backend/** @reviewer-group/content-designers:random(5)
docs/frontend/** @reviewer-group/content-designers:random(3)
# The first three random reviewers will be selected from the content-designers group
# if the docs-frontend files were modified.
# Then, five random reviewers will be selected from the content-designers group
if the docs-backend files were modified.
# If the same user is selected twice, they'll be set as a code owner only once.What if a project and repository contain a reviewer group with the same name?
Bitbucket always starts checking for reviewer groups from the repository level. That’s why even when both a project and repository contain a reviewer group with the same name and this group is set in a rule in the CODEOWNERS file, Bitbucket will use the group from the repository.