FAQ

• Data Center / Server 🗄

• Cloud ☁️

For Auto-Merge related questions, please check our separate DevSensei Auto-Merge FAQ section.

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 :

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:

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 :

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:

CODEOWNERS.toplevel.subdirectory_overrides  enable

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

project-a/CODEOWNERS:

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

project-b/CODEOWNERS:

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

project-b/user-dos/CODEOWNERS:

# 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.

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:

1. Go to Repository settings

2. 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:

*.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) 🗄

1. Define for each rule a separate Code Owners group:

   CODE

   @@@rule_x @@Team

2. Use group in corresponding owner rule:

   CODE

   *.x @@rule_x

3. 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:

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:

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:

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:

1. Go to Repository settings

2. 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.

3. 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):

1. Go to Project settings

2. 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.

"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: \

\#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 DevSensei auto-merge feature).
Check lines 5 to 12 before you run it.

#!/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
# DevSensei 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:

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:

1. 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)

2. 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.