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. These can be enabled (or disabled) at the project level for all repositories in a project, or for individual repositories.
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 'needs work' status - blocks the merge if any reviewers have marked the pull request as 'needs work'.
- 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.
- Click the toggle by the merge check to enable (or disable) it.
Merge checks for repositories set to Inherited in the project will now reflect this new configuration. Merge checks explicitly configured at the repository level will not be affected.
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. Configuring merge checks at the repository level will override any checks configured at the project level. If you have not configured merge checks for an individual repository it will inherit merge checks configured at the project level.
To enable (or disable) merge checks for a single repository (requires repository admin permissions):
- Go to Repository settings > Merge checks.
- Use the drop menu to the right of the merge check to set it.
- Inherited - uses the configuration set at the project level.
- Enabled - enforces the conditions of the merge check.
- Disabled - ignores the conditions of the merge check.
Once set, any changes made to a merge check configuration at the project level will be ignored for this repository because it was changed independent of the project configuration.
Inherited merge check configurations
By default, Bitbucket comes with merge checks disabled at the project and repository level. Unless merge checks were configured at the repository level, enabling or disabling merge checks at the project level inherits the configuration at the repository level.
For example, if you enabled the No incomplete tasks merge check for a project, and a repository merge check configuration was unchanged, each repository would have the No incomplete tasks merge check enabled.
Merge check disabled, project level
| Merge check disabled, repository level
|
Merge check enabled, project level
| Merge check enabled, repository level
|
Now suppose you decide that the No incomplete tasks merge check isn't appropriate for one specific repository. You can change that individual repository's merge checks independent of how it's configured at the project level. Any changes made to merge check configuration at the project level for the No incomplete tasks will be ignored for this repository, because it was changed independent of the project configuration.
Merge check enabled, project level
| Merge check disabled, repository level
|
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:
|