Merge Checks

Concepts

Code Owners app consists of two parts:

1. Owner Rules: Who is responsible for what part of your code?

Owner Rules assign Code Owners to a particular pull request.

In this example, members of group JavaDevs are responsible for all Java source code:

CODE

**/*.java @@JavaDevs

Owner rules define which groups and users are active code owners in a pull request. These active code owners are added as reviewers to the pull request.

2. Merge Checks: How many of these Code Owners need to approve before a pull request can be merged?

Merge Checks enforce how many of the Code Owners have to approve a pull request before merging.

In this example, changes in Java source code must be reviewed and approved by at least 2 members of the JavaDevs group:

CODE

Check(@@JavaDevs >= 2)

3. Enabling Merge Checks

The Merge Checks are enabled in the repository or project settings.

Enable the merge check: Code Owners minimum approvals:
Optionally, you allow repository admins to skip the merge checks:
Leave the legacy settings empty.
When the merge checks are not full filled, merging will be prevented:

Merge Checks Guide

How to combine multiple Merge checks?

If you add multiple merge checks each on its own line to the CODEOWNERS file, all active Merge checks (aka AND) get checked and must be fulfilled, before a pull request can be merged.

If either one Merge check or another needs to be fulfilled for a pull request to be merged, combine the merge checks on one line with the OR/AND syntax like:

CODE

((Check(@@JavaDevs >= 2) | Check(@@TeamLeads >= 1)) & Check(@@TypeScriptDevs >= 1))

Read this as "two Java devs or one team lead need to approve as well as one TypeScript dev" before a pull request can be merged.

If a group is not active in a pull request, the check for this group will be stripped away from AND/OR checks and the remaining of the check line must still be fulfilled!

How to require all members of a group to approve in a Merge check?

Use * instead of a positive integer in the Merge check:

CODE

Check(@@JavaDevs >= *)

How to require approvals by Code Owners independent of groups?

Use the overall check type like:

CODE

OverallCheck(2)

Use * instead of positive integer to require all Code Owners to approve.

How to require approvals for each active group and all mentioned individually in an Owner rule?

Use the all groups check type like:

CODE

AllGroupsCheck(1)

With this Merge Check, single code owners (e.g @Peter) are always required to approve.

If you need help converting your requirements into Merge Check rules, or if you have an uncovered use case, please let us know.

Examples

@@@Backend @Lisa @Laura
@@@Frontend @Tom @Tim @Travis @Timo

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

# At least one member of the Backend team must approve changes in Java code.
Check(@@Backend >= 1)
# At least 2 approvals required by Frontend team for changes in JavaScript code.
Check(@@Frontend >= 2)

@@@Backend @Lisa @Laura @Louis @Lucas
**/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 @Lisa @Laura
@@@Juniors @Tom @Tim @Travis @Timo

**/*.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 @Lisa @Laura

**/*.java @@Seniors @Tom @Tim @Travis @Timo 

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

@@@Backend @Lisa @Laura
@@@Frontend @Tom @Tim @Travis @Timo
@@@UX @Paul @Pia

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

@@@Backend @Lisa @Laura
@@@Frontend @Tom @Tim @Travis @Timo
@@@FullTeam @@Backend @@Frontend

dirBackend/    @@Backend
dirFrontend/   @@Frontend
dirShared/     @@FullTeam

# *only* active on dirBackend:
Check(@@Backend >= 1)
# *only* active on dirFrontend:
Check(@@Frontend >= 1)
# *only* active  on dirShared:
Check(@@FullTeam >= 1)

Syntax

The syntax for merge checks is

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

<group_identifier> name of Bitbucket reviewer group, Bitbucket user group or custom defined group
<quota> 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
Multiple CODEOWNER files: merge checks are checked for each file independently
Pull request author does not count towards check quota except if the PR author is the only active code owner.
1. To consider Pull request author as approving owner in group merge checks, use the AuthorSelfApproval option: Check(@@<group_identifier> >= <quota>,AuthorSelfApproval)

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)

Fallback to allow other users to approve pull requests in case Code Owners are not available (eg. holidays) :

Define a group with the special name FallbackOwners and add the people which can approve PRs for other Code Owners.
In case a Code Owner is absent and the PR can not be merged because of a missing Code Owner approval, add extra reviewers from the FallbackOwners group to the PR. Any approval of such an extra reviewer counts towards any Code Owners merge check.

Fallback example:

@@@FallbackOwners @paul

@@@Devs @chris @linda
* @@Devs

OverallCheck(1)

So if Chris and Linda are not available to approve, Paul can be added and approve instead and the PR can be merged.

Migrate from old Settings Merge Checks 🗄

In Bitbucket Server/Data Center the merge checks originally where a setting in the repos merge checks. These are still supported, but only active if there is no merge check in the CodeOwner file. We recommend to migrate to the merge checks declared in the Code Owners file.

Min. # of approvals of all code owners

Replace this setting:

With this check, using the number or * wildcard:

CODE

OverallCheck(2)

Min. # of approvals for each group

Replace this setting:

With this check, using the number or * wildcard:

CODE

AllGroupsCheck(1)