Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
Set up and use custom merge checks
Custom merge checks are rules and conditions written as Forge apps that workspace administrators can create or implement from existing check apps created by others, like third-party vendors, to help build consistent, safe, and quality-focused workflows. These custom checks can provide customized validations for your pull requests and extra controls to your development workflow. In order to ensure their workflows remain consistent, repository admins can enable custom merge checks to ensure conditions or checks are met before code is merged.
Configure custom merge checks
You must be a Workspace admin to configure and set up custom merge checks.
To set up customer merge checks:
Install the custom merge check app in your workspace via one of the following two options:
Installing 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.
Installing 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.
Select Settings in the upper-right corner of the top navigation bar and select Workspace settings.
Select Custom merge checks under Workflow on the left navigation bar.
Select the Allow custom merge checks for my workspace toggle to enable the custom merge check feature for your workspace.
Once the feature is enabled, all the custom merge checks made available from the installed apps will be displayed on the Custom merge checks page in your Repository settings.
Enable and use custom merge checks
You must be a repository admin to enable, disable, and use customer merge checks.
As a repository admin, you can enable custom merge checks to ensure conditions or checks are met before code is merged. By default, all custom merge checks are disabled or Off.
To view and enable or disable custom merge checks associated with the repository:
Select Repository settings in the left sidebar of the repository.
Select Custom merge checks under Workflow on the left sidebar.
On the custom merge checks page, you can change the view from Main branch to All branches to see the custom merge checks created and assigned to any branches.
If you are a repository admin, you can enable and disable these checks by selecting ‘Off’ or ‘Recommended’ from the dropdown associated with that custom merge check.
Premium-only feature
If you have a Premium plan, you can select Required to enforce custom merge checks.
Note: If you do not have a Premium plan, all your custom checks will be ‘Recommended’ by default when enable.
Custom merge checks that have been enabled will appear in the Details tab on the right sidebar of a pull request, along with any other branch restrictions or merge settings that have been enabled.
Once you have enabled some custom checks in Repository settings, your pull requests will now include those checks that you’ve enabled.
Pre-merge vs on-merge checks
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. These checks will be labeled as ‘pre-merge’.
On-merge checks are integrated into the merge process itself, and only triggered after you’ve selected the Merge button. Failed required on-merge checks will result in a pull request merge failure.
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 definition. The merge check type is displayed in the Type column on the list of custom merge checks (see the above image as an example).
Information on using Forge & creating custom merge checks
Forge resources
Join the Bitbucket Community to keep up with what’s going on with custom checks or to add to the conversation: Forge for Bitbucket Cloud community
Creating custom merge check resources
Was this helpful?