Checks for merging pull requests
Pull requests provide a way to do peer code reviews and merges as part of a branch-based development workflow. As your team grows, you may need to set restrictions about when pull requests can be merged to protect your production code and keep code quality high. Merge checks can help you do this.
On this page:
Merge checks
Merge checks stop pull requests from being merged until they meet requirements that you’ve set. Your requirements can be based a range of things, including the number of reviewers who have approved the pull request, or the result of a Code Insights report. This ensures that pull requests are fully vetted before they’re merged. It also helps to avoid the problem of code review blockages and the need to completely lock down a repository.
Default merge checks
Bitbucket Data Center and Server comes with some default merge checks.
By default, merge check settings from the project level are inherited by the repositories. Repository admins can either set a merge check to inherit the project-level setting or override it (by enabling or disabling the merge check at the repository-level).
Later when you modify a project-level merge check (enable or disable it), only merge checks in repositories that are set to inherit the project-level setting change to match the project-level merge check. Merge checks that've been set to override project-level settings will not change.
Starting from Bitbucket 8.10, project admins can also restrict repository-level customization of a merge check. Note that when you restrict changes, any custom settings saved at the repository-level for that merge check are deleted and the merge check inherits project settings.
The default merge checks that come with Bitbucket are:
- All reviewers approve - requires all reviewers to approve a pull request before merging.
- Minimum approvals - requires at least the specified number of approvals before merging.
- Minimum successful builds - requires at least the specified number of successful builds before merging.
- No 'changes requested' status - blocks the merge if any reviewers have marked the pull request as 'changes requested'.
- No incomplete tasks - requires all tasks to be complete before merging.
In addition to minimum approvals for a pull request, you can also set default reviewers. If both of these checks have been configured, they both need to be met in order to merge. In other words, meeting the minimum number of approvals won't be enough to merge if the default reviewers have not approved the pull request.
Configure merge checks for all repositories in a project
Enabling (or disabling) merge checks at the project level changes merge checks for repositories set to inherit project settings. If you previously changed merge checks for an individual repository, that repository's configuration will not change when configuring merge checks at the project level.
To enable (or disable) merge checks for repositories in a project (requires project admin permissions):
- Go to Project settings > Merge checks.
- Select More actions ... > Enable or Disable.
- Optional: To disable repository-level customization, select More actions ... > Don't allow.
Configure merge checks for an individual repository
Enabling (or disabling) merge checks at the repository level enables a merge check for all pull requests created in that repository.
If your project admin hasn't restricted repository-level customization for a merge check, you can configure it to override the project-level setting (enabled or disabled) or set it to inherit the project-level setting.
To enable (or disable) merge checks for a single repository (requires repository admin permissions):
- Go to Repository settings > Merge checks.
- Select More actions ... >
- Inherit from project, to use the project-level setting
- Enable or Disable to override the project-level setting
Add a new merge check
Additional merge checks can be installed by system administrators and can also be enabled for all repositories in a project, or for individual repositories.
To add merge checks from the Atlassian Marketplace (requires system admin permission):
- Go to Project settings > Merge checks.
- Click Add merge check.
- Search for a merge check to add, and click Install.
Once you add a new merge check, you can enable (or disable) it in the same way as the default merge checks.
Create a merge check
You can also write your own merge request check plugin.
Code Insights merge checks
You can block pull requests from being merged until their Code Insights reports meet your requirements. You can set these merge checks for all the repositories in a project, or a single repository, and your requirements can be based on whether:
- a specific report is present
- the report passes or fails
- the report adds annotations of a certain severity to the diff
Annotations only block merging if they are on the diff. If they’re somewhere else on a changed file, or on a file that hasn’t changed they won’t block the merge.
To add a Code Insights merge check for all the repositories in a project (requires project admin permissions):
- Go to Project settings > Code Insights.
- Enter the report key of your required report. You can find this on the report in the bottom right.
- Enter its required status and its annotation requirements.
- Click add.
To add a Code Insights merge check for a repository (requires repository admin permissions):
- Go to Repository settings > Code Insights.
- Enter the report key of your required report. You can find this on the report in the bottom right.
- Enter its required status and its annotation requirements.
- Click add.
Required builds merge check
This feature is available with a Bitbucket Data Center license.
While the minimum successful builds merge check lets you require at least the specified number of successful builds, you can use the required builds merge check for requiring specific builds to successfully pass before a pull request can be merged into specified target branches.
Using required builds provides a simple but powerful interface to ensure code quality by protecting critical branches in your repository.
To use required builds, you must have Bamboo 7.1+ or the Bitbucket Server Integration Plugin version 2.0.0+. See Link your CI server for more details on integration guides.
To add a required build merge check for pull requests in a repository (requires repository admin permissions):
Go to Repository settings > Required builds.
Select Add required builds.
From the Add required builds page, input the details as described in the table below.
- Select Save.
| Field | Description |
|---|---|
| Add builds | Add any build keys here that will need to successfully pass before merging a pull request. The build key will depend on the CI tool used to generate the build. For example;
|
| Select protected target branches | Choose from a list of branches. Any pull request with a target branch that matches this setting will need to have successful builds on the latest commit before it can be merged. You can set this merge check to apply to Any branch in the repository, or you can be more specific by choosing:
|
| Select exempt source branches | In some cases, you may want to add specific source branches that won’t need to pass in the selected required build(s). For example; you could allow urgent fixes to skip build checks by adding the Branch pattern Leave this option set to None if you don’t want to add an exemption, otherwise choose from the following:
|