Merge Checks

Owned by Markus Sutter
Last updated: Sept 02, 2024 by Michael Rüegg
3 min read

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:

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

Check(@@JavaDevs >= 2)

3. Enabling Merge Checks

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

  1. Enable the merge check: Code Owners minimum approvals:

  2. Optionally, you allow repository admins to skip the merge checks:

  3. Leave the legacy settings empty.

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

((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:

How to require approvals by Code Owners independent of groups?

Use the overall check type like:

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:

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

Syntax

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:

Min. # of approvals for each group

Replace this setting:

With this check, using the number or * wildcard: