FAQ

Code Owners

What differentiates the app from the native Code Owners feature of Bitbucket Data Center?

As of version 8.14, Bitbucket Data Center includes a native Code Owners feature.

The following table aims at providing users with a clear understanding of the feature set available for the native Bitbucket Code Owners feature and our Code Owners app:

Feature	Code Owners for Bitbucket app	Bitbucket native Code Owners feature
auto-assignment of reviewers	✅	✅
file/ folder path patterns	✅ 🔗 CODE `/features/FeatureCode.java @developer`	✅ CODE `/features/FeatureCode.java @developer`
file extension patterns	✅ 🔗 CODE `**.css @developer`	✅ CODE `**.css @developer`
exclusion patterns	✅ 🔗 CODE `frontend/* @frontend-team # no mandatory review for tests !frontend//tests/*`	❌
Match options of patterns	✅ 🔗 CODE `src/{main/,test/} @devs **.{ts,js} @web-devs`	❌
assign user	✅ 🔗 CODE `@developer @"Paul the JSGuru" paul@example.com`	✅ CODE `@developer`
assign user groups	✅ 🔗 CODE `@@developers` Bitbucket groups Bitbucket reviewers groups custom groups defined in `CODEOWNERS` file	❌
assign random subset of reviewers	✅ 🔗 CODE `CODEOWNERS.toplevel.assignment_routing random 2`	❌
custom merge checks	✅ 🔗 CODE `# At least a senior and two code owners in total must approve. OverallCheck(2) Check(@@Seniors >= 1)`	❌
Fallback groups (users who can be added as reviewers and whose approval counts for merge checks in case of code owners absence)	✅ 🔗 ✅ 🔗 CODE `@@@FallbackOwners @paul @monica`	❌
Flexible configuration	✅	❌
Enable/disable per project	✅🔗	❌
Enable/disable per repository	✅ 🔗	❌
mono-repos support (possibility to have different CODEOWNERS files in different folders)	✅ 🔗	❌
auto-merge of PR	✅ 🔗	✅ 🔗
ship/show/ask support	✅ 🔗	❌
support draft PR (no reviewer assignment until PR is ready to review)	✅ 🔗	✅ 🔗
Code Owners Playground for interactive experimentation	✅ 🔗	❌

Want to apply Code Owners just for specific branches?

Destination branches: Inclusion

Per default, a Code Owner file affects pull requests for all destination branch names. You can make a Code Owner file to only apply pull requests with specific destination branches. For that you need to configure the destination_branch_pattern option in your Code Owner file, where you can configure a pattern for matching destination branches in pull requests.

For example, if you want to activate code owners only for pull requests for the destination branch master :

CODE

CODEOWNERS.destination_branch_pattern master

If you also want to have pull requests with release branches covered by Code Owners, also add this next line:

CODE

CODEOWNERS.destination_branch_pattern release/*

Source branches: exclusion (since 5.1)

Per default, a Code Owners file affects pull requests for all source branches. You can make a Code Owner file to be excluded for pull requests with specific source branches.
For that configure the source_branch_exclusion_pattern option in the Code Owners file.

For example, if you want to ignore code owners for pull requests created by a bot, which creates pull requests with source branches named e.g. like renovate/update-X :

CODE

CODEOWNERS.source_branch_exclusion_pattern renovate/*

Used pattern format is similar to the Atlassian branch permission patterns.

Want to have different CODEOWNERS file in subdirectories? (for monorepos)

Per default, only the Code Owners file at the top level of the repository is considered.

However, if your team has different projects in the same repository it can make sense to have a Code Owners file for different subdirectories. For that enable the CODEOWNERS.toplevel.subdirectory_overrides in the top-level Code Owners file. With that, any Code Owners file in a subdirectory determines the rules for that directory and it’s children. It replaces all rules set by the parent directories Code Owners file.

Here is an example:
In the top-level CODEOWNERS file:

CODE

CODEOWNERS.toplevel.subdirectory_overrides  enable

And then you can add Code Owner files for the subdirectories:

project-a/CODEOWNERS:

CODE

# Rules for Project A
* @@ProjectAOwners
src/*.java  @@JavaExperts
src/*.js    @@JavaScriptExperts

project-b/CODEOWNERS:

CODE

# Rules for Project B
* @@ProjectAOwners
src/*.cs  @@CSharpExperts

project-b/user-dos/CODEOWNERS:

CODE

# Rules for Project B's user documentation
* @@DocumentationTeam
*.md  @@DocumentationTeam
/images/* @@Designers

Why does the app not add a Code Owner as reviewer to the updated pull request?

Is the Code Owners app active in Repo settings?
The Code Owners app will check on rescope events from source branch of PR, if new Code Owners need to be added to the PR reviewer list and will do so.
- But there is one exception since version 3 of the app:
  - If previously the new Code Owners got manually removed as reviewers from this PR, then you will need to add them manually as reviewers, in case a merge check requires their approval or if they should just review the PR.
    Note: If on PR creation some reviewers are assigned, but not all matching Code Owners are part of it, then the missing Code Owners are also treated as "manually removed". And if all reviewers are removed on PR creation, all Code Owners are re-add, because the app can not distinguish this case from a PR created via REST endpoint due to technical reasons.

What triggers the app to update the code owners of a pull request?

Changes on source branch 🗄 & ☁️
~~Changes on destination branch (not always visible in pull request activities)~~ (only before version 3.1)
(starting with version 4.1) manually trigger Code Owners in pull request menu. 🗄

How to Remove Extra Code Owners Comment on Pull Request ?

By default, Code Owners adds a comment with the code owners and reason for their inclusion. Like any comment, this sends out a notification.

If you do not need this comment and want fewer notifications you can disable it by adding following line in the Code Owners file. It must be in the top-level Code Owner file.

CODE

CODEOWNERS.toplevel.create_pull_request_comment disable

How to disable auto-assignment of Code Owners?

If you want to disable the auto-assignment for all pull requests in a repository:

Go to Repository settings
Click on ADD-ONS -> Code Owners
1. Disable: Auto-assignment of Code Owners for current repository.
  1. No reviewers will be assigned to new PRs or updated PRs.

How to require approval by Merge check for groups, but not for single users?

Create a merge check for that specific group or groups. It will not affect extra single users added to a code owner rule:

CODE

*.java  @@JavaDevs @SingleUser
Check(@@JavaDevs >= 2) # Will require merge checks from JavaDevs, but not from the @SingleUser

Need different Merge checks for different owner rules? (since 4.0)

Define for each rule a separate Code Owners group:
CODE
```
@@@rule_x @@Team
```
Use group in corresponding owner rule:
CODE
```
*.x @@rule_x
```
Add a group based merge check for each rule:
CODE
```
Check(@@rule_x >= 2)
```

Is there an REST API for changing the Merge Checks settings?

Code Owners does not have a long-term stable REST API to enable/disable the merge checks. It uses the Bitbucket settings API for its merge check settings. You can call that API to configure the merge checks.
The endpoint for the settings are:

project-level: $YOUR_BITBUCKET_SERVER/rest/api/latest/projects/$PROJECT/settings/hooks/ch.mibex.bitbucket.codeowners%3Acodeowners-merge-check/enabled
repo-level: $YOUR_BITBUCKET_SERVER/rest/api/latest/projects/$PROJECT/repos/$REPO/settings/hooks/ch.mibex.bitbucket.codeowners%3Acodeowners-merge-check/enabled

To enable and change the Merge Check setting, use the project or repo-level endpoint and send a PUT request with the settings:

CODE

curl --request PUT $YOUR_BITBUCKET_SERVER/rest/api/latest/projects/$PROJECT/repos/$REPO/settings/hooks/ch.mibex.bitbucket.codeowners%3Acodeowners-merge-check/enabled \
--user '$ADMIN_USER:$PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"approvals":"2","approvalsPerGroup":"", "disableMinApprovalsForRepoAdmin":""}'

An empty string is used for the default value.

To disable the Merge Checks settings, use a DELETE request:

CODE

curl --request DELETE $YOUR_BITBUCKET_SERVER/rest/api/latest/projects/$PROJECT/repos/$REPO/settings/hooks/ch.mibex.bitbucket.codeowners%3Acodeowners-merge-check/enabled \
--user '$ADMIN_USER:$PASSWORD'

To reset a repo-level setting back to inherited, use this delete request:

CODE

curl --request DELETE $YOUR_BITBUCKET_SERVER/rest/api/latest/projects/$PROJECT/repos/$REPO/settings/hooks/ch.mibex.bitbucket.codeowners%3Acodeowners-merge-check \
--user '$ADMIN_USER:$PASSWORD'

Want to disable Code Owners app for a specific repository or fork? (since 4.0)

Repository level:

Go to Repository settings
Click on ADD-ONS -> Code Owners
1. Disable App for repo (since 5.1)
2. Or if you just want do disable the auto-assignment, use option: Auto-assignment of Code Owners for current repository.
  1. No reviewers will be assigned to new PRs or updated PRs.
Got to Merge Checks hooks of repository
1. Disable Code Owners min approvals Merge Checks in Merge Checks hooks
  1. All Code Owners Merge Checks are ignored.

Project level (since 5.2):

Go to Project settings
Click on ADD-ONS -> Code Owners
1. Enabled/disable app for project.

Why does the app add Code Owners to pull request for "unchanged" files/already merged files? (Bitbucket 6 only)

Bitbucket 6 uses a 3-way diff in the pull request view, which hides some changes of the commits, if the same changes are already in the destination branch.
If you use the Compare diff view to watch the diff for the source and destination branch, you will see that the files actually got changed in the source branch. The same effect can be observed when you view the diff in PR for the individual commits.
Bitbucket 7 uses the 2-way diff also in the pull request view, like in the Compare diff view.
And Code Owners also uses this 2-way diff to calculate the Code Owners.

Background:
Release notes 6.10: Section: 2-way diff for pull requests
Release notes 7.0: Section: A modified behavior for diffs

Is there Code Owners app for Bitbucket Cloud?

Yes, there is a Bitbucket Cloud edition of Code Owners.

How does escaping for Code Owners app work?

To use spaces in user, group names and glob expressions, put them in double quotes.

CODE

"test/file name with spaces.txt" @"Paul Winter" @@"Java Developers"

If your glob expression starts with a #, you need to escape # with a back slash: \

CODE

\#filewithFancyPrefix.txt @"Paul Winter"

Can I disable Code Owners globally?

When you install Code Owners for the first time, it will be enabled by default. Any projects/repositories can thus use Code Owners right away. If you prefer to gradually adopt Code Owners within your organization, you can decide to disable Code Owners by default instead and let individual projects and/or repositories enable it when they are ready to use Code Owners.

If you want to disable Code Owners by default, you need to navigate to the Code Owners administration configuration (located at <your instance>/plugins/servlet/codeowners/admin) and toggle the switch in front of the "Code Owners app" to OFF.

Note that enabled Code Owners merge checks will still apply even if you disable Code Owners.

When you disable Code Owners, it will not be disabled on Projects or repositories that already explicitly enables. See this entry to disable them in that case.

How can I disable the Code Owners app on all existing projects?

The Code Owners app has an API to enable or disable the application for a given project.

The following scripts will go through all existing project, and disable the Code Owners app for each of them (including the Apps' auto-merge feature).
Check lines 5 to 12 before you run it.

BASH

#!/usr/bin/env bash
# Disable Code Owners app for all Bitbucket DC projects, so that you can opt-in one-by-one.
set -e

# Requires curl and https://stedolan.github.io/jq/

# Admin user with Project admin permission
ADMIN_USER=
# Access token for above user with Project admin permission, see https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html
ADMIN_ACCESS_TOKEN=
# Your bitbucket domain, e.g https://git.company.com
BITBUCKET_URL=

HTTP_AUTH="curl --user $ADMIN_USER:$ADMIN_ACCESS_TOKEN"

$HTTP_AUTH $BITBUCKET_URL/rest/api/latest/projects\?limit=1 | jq --raw-output '.values[] | .key' > projects.txt

# Code Owners
cat projects.txt | while read -r line ; do $HTTP_AUTH -X PUT $BITBUCKET_URL/rest/codeowners/1.0/projects/$line/settings/app-active/disabled ; done
# Auto-merge
cat projects.txt | while read -r line ; do echo 'false' | $HTTP_AUTH -X PUT $BITBUCKET_URL/rest/codeowners/1.0/app-settings/projects/$line/settings/enable-devsensei ; done


echo "Go to $BITBUCKET_URL/projects and then to corresponding `Project settings -> Code Owners` to enable Code Owners app again in your some of the projects."

This script only disables the app for existing projects. Newly created projects will need to be manually disabled via the settings.

How to share groups of Code Owner across repositories?

To use groups of reviewers in your CODEOWNERS file, you have three options:

Bitbucket reviewer groups
Bitbucket user groups
Custom Groups defined in CODEOWNERS

We recommend the usage of Bitbucket reviewer and user groups instead of defining custom groups when they change often, because
they require less effort to update.

Reviewer groups can be configured on both the Bitbucket repository and project-level. If you have new team members or others that leave,
you can just change that in one place in the Bitbucket UI, instead of updating all group definitions in all affected CODEOWNERS files.

Example of referencing a Bitbucket reviewer group in CODEOWNERS:

CODE

src/main/java/**   @@NameOfReviewerGroup

How to update the list of reviewers when a Pull Request is changed?

In the event where the list of reviewers assigned to a Pull Request are not relevant anymore, you can follow these steps to let Code Owners assign up-to-date reviewers:

manually remove the current reviewers:
1. In the Pull Request UI, click on the ... icon on the upper right corner > edit
2. remove the reviewers present in the reviewers section (you can hold the backspace key in the input box to delete all reviewers)
trigger the auto assignment of reviewers by Code Owners:
1. In the Pull Request UI, click on the ... icon on the upper right corner > Code Owners: Trigger assignment

This will add reviewers based on the current state of the Pull Request and the rules defined in your CODEOWNERS file.

The action Code Owners: Trigger assignment only adds reviewers not already present based on the rules defined. Reviewers still present when the action is triggered will remain.
This can be useful if you want to keep certain manually-added reviewers when triggering the action.

Disabling Telemetry

The app sends anonymous data about usage and performance to Mibex. ou can opt out of sending telemetry statistics by setting the Bitbucket property plugin.ch.mibex.bitbucket.codeowners.telemetry to false.

Undo Code Owners assignment

There is no native undo feature for the Code Owners assignment in the app, e.g. when the wrong destination branch was chosen.

But there is a trick for fast removing reviewers of a PR in the PR edit dialog:

Click on three dots(further actions) in PR view
Click on Edit in opened menu
Click behind last reviewer in Edit dialog, so that cursor is there.
Press Delete until reviewers list is empty
Press Save
Trigger Code Owners in PR context menu "Code Owners: Trigger assignment"

Auto-Merge

What differentiates the app’s Auto-Merge from the native Auto-Merge feature of Bitbucket Data Center?

As of version 8.15, Bitbucket Data Center includes a native Pull Request Auto-merge feature.

The following table aims at providing users with a clear understanding of the feature set available for the native Bitbucket Code Owners feature and our Code Owners app:

Feature	Auto-Merge in Code Owners app	Bitbucket native Auto-Merge feature
Author can decide during PR creation if should be Auto-Merged	✅	❌ Only possible once the pull request is created
Ship/Show/Ask Support	✅ 🔗	❌
Auto-Merge supports Code Owners	✅ 🔗 Only Auto-Merge when Code Owners approve
Auto-Merge Cancellation	✅	✅
Auto-Merge Policy visible in PR lists	✅ You can see in the PR title the type of the Auto-merge: `[AUTO]`, `[SHIP]`, `[SHOW]`, `[ASK]`	❌
Available in older Bitbucket versions	✅ >= Bitbucket 7.6	❌ >= Bitbucket 8.15

What if I want to use the traditional manual merge for my pull request?

You can select “Manual merge” and requiring “No” approva. This will act as if Auto-Merge does not exist for your pull request.

Will Auto-Merge delete the source branch upon merging?

Bitbucket 7.15 introduced the “Branch deletion on merge” setting, available in Workflow > Branches on your project or repository. Auto-Merge will respect this setting when merging a pull request. This means that Auto-Merge will follow the behavior specified in that setting when merging a pull request.

If the version of your Bitbucket instance is 7.14 or lower, then Auto-Merge will delete the source branch on merge.

How do Auto-Merge and Code Owners interact?

For the most part, Auto-Merge and Code Owners are two independent features next to each other. However, Auto-MErge will skip Code Owners merge checks in the event of a [Ship] or [Show] pull request.

In particular:

a [Show] pull request doesn’t require any approvals to be merged. Moreover, if Code Owners requires approvals for that same pull request, they will be skipped. Therefore the pull request will be automatically merged even if Code Owners merge checks are not fulfilled.
a [Show>=2] pull request will require two approvals, regardless of who they are coming from. If for its part, the merge checks on your repository are configured to require 3 approvals, then in total only 3 approvals will be necessary. Code Owners merge checks will be skipped.
The same applies for [Ask>=2], but they the key difference is that the Ask pull request will not skip Code Owners merge checks. The other difference is that it will not auto-merge.
a [Ship] pull request will skip assignment of Code Owners. This is inline with the philosophy of Ship/Show/Ask: Ship pull request are meant for tiny and trivial changes to your repository. Such changes will be more effective if you don’t bother other team members to carry them through.

I accidentally created a pull request in the wrong category, can I do something about it?

Auto-Merge uses the title of a pull request to determine its category. For example a [Show>=2] pull request will have its title start with [SHOW>=2]. If you modify the title of the pull request after it has been created, it will also change its category for Auto-Merge.

When does Auto-Merge check if a pull request must be auto-merged?

Auto-Merge will check that a pull request can be auto-merged every time an impactful change happens to the pull request. For example, a new task completed, a new approval, a finished build or a change in the title. However, it will never do so less than 20 seconds after the creation of the pull request, leaving you a time window to change the pull request title (or delete the pull request) if you accidentally used the wrong one (see “I accidentally create a pull request in the wrong category, can I do something about it?”).

Is there a way to make some kind of “work in progress” pull request?

Perhaps you want to use auto-merging pull requests, but your pull request is not actually ready and you don’t want it to be auto-merged right away. If that is the case, you have two options:

after creating the pull request, create an open task to prevent the merge (note that if that is the only merge check on your repository, you only have 20 seconds to do so – see “When does Auto-Merge check if a pull request must be auto-merged?”)
you can create the pull request selecting “Manual merge”, and change the title so that it starts with [SHOW>=n] (with n replaced with the desired number) or with [SHOW] when it is not longer work in progress.

I want to use Ship/Show/Ask but I don’t want Ship or Show to skip Code Owners?

This is something that is currently not supported. If you would be interested in such a feature, we will be happy to hear from you!

Why is my pull request not auto-merged?

Common cases where a pull request would not be merged automatically by Auto-Merge:

The pull request author misses permission to merge to destination repository.
Auto-merge feature is disabled in destination repository of pull request.
Last build of pull request is still in progress or has failed.
Someone selected “needs work” for their review status
Pull request title is not prefixed with [AUTO] - or [SHIP] / [SHOW] if Ship/Show/Ask feature enabled.
Before version 6.7.0:
If a merge check does requests to a 3rd party system (like Jira), then the Auto-Merge Bitbucket service user might not have permissions to do it, causing the auto-merge to fail. This is a known situation when using the merge check “Require that a pull request is associated with a valid Jira issue” from ScriptRunner for Bitbucket. We are working on a way to configure a separate Bitbucket user for auto-merging, please vote on CODEOWNERS-56.
- Since version 6.7.0, the pull request author is used to the perform the merge.