Code Owners for Bitbucket Cloud

Get started

For the installation check the corresponding section.

Define a CODEOWNERS file in the root of your repository with code owners rules
Create a pull request (with CODEOWNERS file in destination branch)
Benefit from auto-assigned reviewers
Add merge checks to enforce code owner reviews

Discover more features in our Code Owners documentation.

Owner rules

The syntax for owner rules is simple

<filepattern> <members>

<members> can consist of one or more user/group identifiers

@<username>for single users
@@<groupname> for groups. Can be either:
- Bitbucket Cloud groups
  - ensure that the groups have at least read permissions on the repository
- Custom Groups -> see below
names with spaces need to be in double quotes @"<user with spaces>"

<filepattern> follows the same convention as the .gitignore file. For example, this is the behaviour for the following patterns:

* everything in the repository
**/*.java all java files
ci/* all files in directory ci without subdirectories
frontend/ all files in directory frontend with subdirectories
{option1,option2,optionX} provides list of options which can be matched. e.g. main.{java,js,ts} matches main.java, main.js or main.ts. docs/{public/*,api/*} matches files under the docs/public/* and docs/api/* directories.
!ci/playgrounds.yml exclude code owners for selected files
files starting with # or ! can still be used by escaping them \!file.txt

Ordering is important! The last matching file pattern has the highest precedence. Generic rules should be put first, followed by more specific rules.

Protect CODEOWNERS file itself!

Ensure to have a Code Owners rule covering the CODEOWNERS file itself, for example: CODEOWNERS @CTO

Custom Groups

The syntax to create custom groups is

@@@<newgroupname> <members>

The group can be used in owner rules in group syntax @@<newgroupname> (only two @symbols)

Identifiers

As identifiers in CODEOWNERS file are supported in Bitbucket Cloud:

Display Name
Nickname (Public name) of Bitbucket Cloud users

To get the Display Name or Nickname of a user, mention a user in the pull request (e.g. description or comments). In the auto-complete list, you will see the Display Name on top and below the Nickname.

NOT supported:

e-mail addresses or user slugs

Merge checks

The syntax for merge checks is

Check(@@<group_identifier> >= <quota>)

<group_identifier> name of defined group in the CODEOWNER file.
<filepattern> positive integer or * for all group members

Rules:

Only groups can be used in merge checks, no individual users
Combine merge checks on a single line with | (OR) and & (AND)
Checks on different lines, all must be fulfilled (AND)
Checks with inactive groups are removed from the evaluation
Pull request author does not count towards check quota except if the PR author is the only active code owner.

Special Checks:

Minimum number of approvals needed from all matching code owners.

OverallCheck(n)

Minimum number of approvals needed from each matching code owners group.

AllGroupsCheck(n)

Checks in Bitbucket Cloud Code Owners merge check will show as an in-progress build on the pull request:

Merge Check

Use the Bitbucket branch restrictions to enforce Code Owners approvals:

Navigate to the repository’s administration section → Branch restrictions → Merge settings (tab). (https://bitbucket.org/YOURWORKSPACE/YOURREPO/admin/branch-restrictions)
Enable the appropriate number of required successful builds. The Code Owners merge check counts as one build. Example: use 2 to require at least one successful build run and a successful Code Owners merge check.
If you are using Bitbucket Premium, you can optionally enforce the merge checks with "Merging with unresolved merge checks is not allowed".

Examples

**/*.java     @"James Gosling"
**/*.scala    @"Martin Odersky"
jvm/**/*.java @"Brian Goetz"

@@@FrontendTeam @"Brendan Eich" @"Tim Berners-Lee"

web/*        @@FrontendTeam @CTO

@@@Backend @"Grace Hopper" @"James Gosling" @"Martin Odersky"
**/main/*.java @@Backend

@@@BackendTests @@Backend
**/test/*.java @@BackendTests

# At least two approvals for changes in Java main code.
Check(@@Backend >= 2)
# Only one team member must approve, if pull request changes only Java tests.
Check(@@BackendTests >= 1)

@@@Seniors @"Grace Hopper" @"James Gosling"
@@@Juniors @"Martin Odersky" @"Jordan Zee" @"Travis Iralu"

**/*.java @@Seniors @@Juniors

# At least a senior OR two juniors must approve, before pull request with changes in Java files can be merged.
(Check(@@Seniors >= 1) | Check(@@Juniors >= 2))

@@@Seniors @"Grace Hopper" @"James Gosling"

**/*.java @@Seniors @"Martin Odersky" @"Jordan Zee" @"Travis Iralu"

# At least a senior and two code owners in total must approve.
OverallCheck(2)
Check(@@Seniors >= 1)

@@@Backend @"Grace Hopper" @"James Gosling"
@@@Frontend @"Martin Odersky" @"Jordan Zee" @"Travis Iralu"
@@@UX @"Lee Skouras" @"John Yoo"

**/*.java @@Backend
**/*.{js,ts,css} @@Frontend @@UX

# For every active group at least somebody must approve, and Frontend group requires two approvals, if something changed on *.js files.
AllGroupsCheck(1)
Check(@@Frontend >= 2)

Installation -- Bitbucket Cloud

This add-on must be installed through the Atlassian Universal Plugin Manager (UPM):

Choose the Bitbucket workspace that you would like to install the app to
Once in the chosen workspace, click on Settings
Click on Marketplace under Apps and Features
Click on All categories drop down and choose Code review
Code Owners for Bitbucket will show up as an option
Click Add and grant access to the app
The app should now be listed under Installed Apps
You're done!

Upgrading

Happens automatically, except if manual approval is required.

To upgrade app manually to the latest version:

Go to your Workspace settings under Settings -> Installed apps:
- https://bitbucket.org/YOUR_WORKSPACE_NAME/workspace/settings/addon-management
Select the app you want to update.
Press the Update button.

Data security and privacy - Code Owners for Bitbucket Cloud

Please find the general privacy policy here: Privacy Policy (Cloud apps)

App specific data storage

At Mibex Software, we try to only store the bare minimum of data to accomplish our task (installation registration data only) and store everything encrypted at rest.

Add-on Scopes

account: Ability to see all the user's account information. Note that this does not include any ability to mutate user data. Necessary to resolve PR reviewers configured in CODEOWNERS.
repository: Gives the app read access to all the repositories the authorizing user has access. Necessary to read the CODEOWNERS file from your repository.
pullrequest: Gives the app read access to pull requests and collaborate on them. This scope implies repository, giving read access to the pull request's destination repository. Necessary to get the changed files of a PR, to configure the merge check, and to show the Code Owners webcard.
pullrequest:write: Implies pullrequest but adds the ability to create, update, merge, and decline pull requests. This scope implies repository:write, giving write access to the pull request's destination repository. Necessary to add reviewers to a pull request.

Backup

Although the data center location of our Heroku application is Europe (i.e., amazon-web-services::eu-west-1), Heroku backups of our Postgres database are stored in the U.S.