Getting Started
The following video provides a quick overview on how to get started with Code Owners. You will find below on this page all the detailed instructions.
Want to try it out first? Access the interactive playground where you can check your Code Owner rules.
Configuration
Add configuration file
The first step is to create a file called CODEOWNERS
at the root of your repository.
Here is an example for the file including some configuration:
# Put this in a file called CODEOWNERS in the root directory
# of your repository.
# Every rule line is a file pattern that is followed by one or more Code Owners.
# Scala code is owned by Martin Odersky
**/*.scala @martin_odersky
# Define group
@@@Java_Experts @james_gosling @brian_goetz
# Java files are owned by group members of Java_Experts
**/*.java @@Java_Experts
# You can also use Bitbucket groups which
# start with '@@' compared to single users.
# This will add all members of the Bitbucket group JS_Experts.
*.js @@JS_Experts
# You can also specify code owners by email address if you prefer:
docs/* docs@example.com
# Ordering is important! The last matching file pattern has the highest precedence.
# So if only files in the jvm sub-directories are in the pull request, Bill Joy
# will be the code owner.
jvm/**/*.java @bill_joy
For more details about how owner rules work, see Owner rules
To configure behavior settings of Code Owners, see CODEOWNERS settings
Alternative file location: .bitbucket/CODEOWNERS
is deprecated.
Add merge checks
You can enforce approvals by a minimum number of reviewers assigned by Code Owners before merging.
To do so, just enable Code Owners minimum approvals as shown below:
Recommendations to prevent unwanted changes regarding approvals:
Ensure to have a Code Owners rule covering the CODEOWNERS file itself, for example:
CODEOWNERS @CTO
Protect branches for which you want enforced approvals with Branch permissions to prevent changes without a pull request for example.
Repository administrators can overrule the enforcement, by disabling the merge checks for repository administrators (e.g. helpful during unplanned absences).
Create Pull Requests
Create Pull Requests with automatically assigned reviewers
When you create a Pull Request, reviewers will automatically be assigned based on the content of theCODEOWNERS
file present in the destination branch.
If you have enabled the Code Owners minimum approvals merge check, the pull request cannot be merged until the required code owners have approved the pull request:
When a Pull Request is updated, additional reviewers may be assigned if needed depending on the updated content.
Auto merge (NEW)
As from version Code Owners 6.0 of Code Owners, you can configure certain Pull Requests to be automatically merged once merge checks are satisfied.
This feature has been inspired by the Ship/Show/Ask branching strategy to optimize the review time of Pull Requests depending on their characteristics. See About Ship/Show/Ask PR workflow for more detail.
When installing Code Owners 6.0 or higher, DevSensei Auto-Merge will be enabled by default.
It allows you to select, when creating a Pull Request, one of the following options:
Auto-merge: the pull request will be merged as soon as all merge checks are fulfilled (merge checks include requiring review approvals, successful pipeline run…)
Auto-merge with minimum reviewers: the pull request will be merged as soon as:
all merge checks are fulfilled (except minimum number of reviewers from Code Owners as this feature overrules this check)
a defined minimum number of reviewers has reviewed it
You can learn more about this auto merge feature by reading the DevSensei Auto Merge documentation.