Set up and use custom merge checks

Bitbucket Cloud offers built-in branch restrictions that allow your project and repository teams to set up prerequisites that must be met before merge commands are allowed for pull requests.

If you find that the branch restrictions we offer out of the box don’t suit your organisation’s unique workflows, Bitbucket Cloud also supports custom merge checks.

The benefit of using app-based custom merge checks is that you are in complete control of the these checks, allowing you to create consistent, safe, and quality focussed workflows regardless of your requirements.

On premium plans, you can also set and enforce these checks at workspace, project, or repository levels, allowing your organisation to enforce quality standards as broadly or specifically as needed.

Before you begin

Use our developer tutorial to learn how to create a custom merge check app.

Alternatively, if you’d like to install an app created by a third party vendor, keep reading to learn how to install a ready-made app.

Install and enable custom merge checks

You must be a Workspace admin to configure and set up custom merge checks.

To configure custom merge checks:

1. Install a custom merge check app in your workspace via one of the following two options:

   1. Install an app you or your team has created via the Forge CLI forge install command if you have the app source code. Refer to the our developer documentation for more details on creating custom merge check apps. If you are looking for specific details about the Install command, refer to Install command.

   2. Install an app that someone else has created via a direct distribution link given to you by the app developer. Refer to the Distribute your apps developer doc for more details.

2. Select Settings in the upper-right corner of the top navigation bar and select Workspace settings.

3. Select Custom merge checks under Workflow on the left navigation bar.

4. Select Enable to enable the custom merge check feature for your workspace.

5. Once enabled, all custom merge checks available from the installed forge apps will be displayed in Custom merge checks page under Workflow in workspace, project and repository settings pages.

Set up custom merge checks at the repository level

Checks enabled at the repository level will run against all pull requests contained within the repository, provided the pull request target branch matches a configured checks enabled branch.

To administer custom merge checks associated with the repository:

1. Select Repository settings in the left sidebar of the repository.

2. Select Custom merge checks under Workflow on the left sidebar.

3. If you do not see a table, it means you do not have any Forge Apps installed which provide Custom Merge Checks. You will have to install an app into your workspace prior.

4. Click the Add check button on a Forge app shown in the table.

5. Select the name of the app's merge check you’d like to enable.

6. Select the target branch you’d like the custom check to be run against.

7. Click Save which will cause that check to come into effect for all pull requests.

Set up custom merge checks at the project level

Checks enabled at the project level will run against all pull requests contained within all repositories contained within the project. Provided the pull request targets a branch which corresponds to the enabled custom checks.

To administer custom merge checks associated with the project:

1. Select Project settings in the left sidebar of the project.

2. Select Custom merge checks under Workflow on the left sidebar.

3. If you do not see a table, it means you do not have any Forge Apps installed which provide Custom Merge Checks. You will have to install an app into your workspace prior.

4. Click the Add check button on a Forge app shown in the table.

5. Select the name of the app's merge check you’d like to enable.

6. Select the target branch you’d like the custom check to be run against.

7. Select whether or not the check is required

8. Click Save which will cause that check to come into effect for all pull requests.

Set up custom merge checks at the workspace level

Checks enabled at the workspace level will run against all pull requests contained within all repositories contained within all projects contained within the workspace. Provided the pull request targets a branch which corresponds to the enabled custom checks.

To administer custom merge checks associated with the project:

1. Select Project settings in the left sidebar of the project.

2. Select Custom merge checks under Workflow on the left sidebar.

3. If you do not see a table, it means you do not have any Forge Apps installed which provide Custom Merge Checks. You will have to install an app into your workspace prior.

4. Click the Add check button on a Forge app shown in the table.

5. Select the name of the app's merge check you’d like to enable.

6. Select the target branch you’d like the custom check to be run against.

7. Select whether or not the check is required

8. Click Save which will cause that check to come into effect for all pull requests.

Using custom merge checks

Once you’ve installed a custom merge check app and enabled the feature at the workspace level, you can set up custom merge checks at each level of the Bitbucket resource hierarchy: workspace, project, and repository.

This allows organisations (workspace level) to mandate a set of checks that must run across the entire workspace, and gives teams (projects) the ability to also mandate checks running within that project, and finally individual repositories may also set checks.

These checks are inherited. That is a check that is required at the workspace level can not be disabled at a lower level (project or repository).

The checks are also complementary. The same check can be (not that we advise it) at multiple levels, each producing an independent result in the pull request.

That enables a workspace to set a check as not required and a contained project (or repository) could enable the same check targeted against the same branch as required.

As an example, in the repository below:

Any pull request targeting the repository’s configured main branch will run the following merge checks.

• Required number of builds passed

• All tasks resolved (Inherited from the repository's project)

• Minimum approvals (Inherited from the repository's workspace)

And will require a passing result for both the inherited checks (as they’ve been configured as required).

Custom merge checks run in the context of a pull request. Once you’ve enabled a merge check, you will see results for the enabled check results in the Pull Request page.

Any PR created from this point in time will automatically queue and execute any custom checks configured against the target branch.

Any check which is configured to be not required will be executed, but will not prevent a merge.

Types of custom merge checks

A custom check can be pre-merge, on-merge, or both. The type of the check depends on what trigger it is subscribing to in its Forge app manifest. The merge check type is displayed in the add/edit modal in the Custom merge checks setting table.

Pre-merge

Pre-merge checks are triggered as different events occur on an open PR prior to it being merged. For example, when code has been pushed to the source branch of the pull request (on-code-pushed) or when an approval is changed (on-reviewer-status-changed). Any custom merge check which is pre-merge must produce a successful result (if required) prior to a merge action being invoked.

On-merge

On-merge checks are integrated into the merge process itself, and are only triggered after the Merge button (or api) has been hit. Failed on-merge checks which are set as required will result in a pull request merge failure.