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 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 Server 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 Server 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.