Data Center π
Cloud βοΈ
For Auto-Merge related questions, please check our separate DevSensei Auto-Merge FAQ section. |
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 | ||||
---|---|---|---|---|
auto-assignment of reviewers | ||||
|
|
| ||
|
|
| ||
|
| β | ||
|
| β | ||
|
|
| ||
|
| β | ||
|
| β | ||
|
| β | ||
|
| β | ||
Flexible configuration | β | |||
| β | |||
| β | |||
| β | |||
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 | β |
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.
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 |
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.
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. π
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 |
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
Disable: Auto-assignment of Code Owners for current repository.
No reviewers will be assigned to new PRs or updated PRs.
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 |
Define for each rule a separate Code Owners group:
@@@rule_x @@Team |
Use group in corresponding owner rule:
*.x @@rule_x |
Add a group based merge check for each rule:
Check(@@rule_x >= 2) |
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' |
Repository level:
Go to Repository settings
Click on ADD-ONS -> Code Owners
Disable App for repo (since 5.1)
Or if you just want do disable the auto-assignment, use option: Auto-assignment of Code Owners for current repository.
No reviewers will be assigned to new PRs or updated PRs.
Got to Merge Checks hooks of repository
Disable Code Owners min approvals Merge Checks in Merge Checks hooks
All Code Owners Merge Checks are ignored.
Project level (since 5.2):
Go to Project settings
Click on ADD-ONS -> Code Owners
Enabled/disable app for project.
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
Yes, there is a Bitbucket Cloud edition of Code Owners.
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" |
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. |
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. |
To use groups of reviewers in your CODEOWNERS
file, you have three options:
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 |
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:
In the Pull Request UI, click on the ...
icon on the upper right corner > edit
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:
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 |
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
.
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"