Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
Suggest or require checks before a merge
Bitbucket Premium
Providing your users with recommended checks to consider before merging is available to everyone. However, we also offer a few Premium merge checks:
Enforce merge checks to ensure every pull request is fully vetted before it gets merged.
Require another approval from reviewers, if the source branch of a pull request is modified.
Keep approvals if there is no change to the diff in the pull request.
Merge checks allow you to recommend or require specific conditions on merges for individual branches or branch patterns. Merge checks work in tandem with branch permissions to give the members of your workspace flexibility and control over your development workflow.
Purpose of merge checks
Dependent merges
Ensure users are only merging changes with passing builds.
Select a specific number of successful builds before a merge.
Use with Bitbucket Pipelines, a build tool integration from our App Marketplace, or our commit status REST API.
Code review completion
Tie merges to code review.
Get your colleagues working collaboratively with pull requests.
Keep your workflow consistent so developers know what they have to do to merge.
Task completion
Create tasks on pull requests to mark changes that need to be made.
Manage a pull request as it progresses to approval.
Ensure all tasks in a pull request are complete before a merge.
Merge checks
To configure and set up custom merge checks
You must be a Workspace admin to configure and set up custom merge checks. For details, see Set up and use custom merge checks.
You can use merge checks to recommend or require the following conditions before a merge.
When you select any of these options (and don't have the Premium plan), we'll warn users when they have unresolved merge checks, but they'll still be able to merge. To prevent users from merging, upgrade to Premium and select Prevent a merge with unresolved merge checks. Learn more about Premium
Setting - Check for the following conditions to be true | Result |
|---|---|
Minimum number of approvals | Users get notified when pull requests don't have that number of approvals. Note: The author of the pull request (PR) can approve their own PR, but that approval does not count towards the number of approvals needed for the merge check to pass. |
Minimum number of approvals from default reviewers | Users get notified when pull requests don't have that number of approvals from default reviewers. |
No changes are requested | Users get notified if pull requests have ‘Changes requested’ associated with any of the reviewers. |
No unresolved pull request tasks | Users get notified when they have open pull request tasks. |
Minimum number of successful builds for the last commit with no failed builds and no in progress builds | Users get notified when they don't have that number of successful builds for the most recent commit. |
Maximum number of commits behind destination branch | Users get notified when a branch is behind the maximum number of commits compared to the destination branch. |
Reset requested changes when the source branch is modified | Automatically resets any ‘Changes requested’ statuses when the source branch is modified. |
Allow automatic merge when builds pass | When all required merge checks except successful builds are completed, you will be able select Merge while the build is running instead of waiting for the build to be complete. The merge will then happen as soon as the build is successful but will be blocked if the build fails. |
If you're on our Premium plan, you also have access to the following settings.
Setting | Result |
|---|---|
Reset approvals when the source branch is modified | If there are any changes to the source branch of the pull request, the pull request updates with no approvals, and the reviewers have to review and approve the pull request again. |
Keep approvals if there is no change to the diff in the pull request | Ensures that any approvals that were made are kept intact if there are no changes to the existing diff in the pull request. For example, when an empty commit is added to the branch or no new changes are introduced when rebasing the source branch. |
Prevent a merge with unresolved merge checks | Users won't be able to merge if their pull request has unresolved merge checks. They'll see a checklist of what they need to resolve before the merge can be executed. |
Example setup
Merge checks apply to individual branches or branch patterns along with branch permissions. The rest of this section expands the example we used to describe branch permissions and includes merge checks.
Let's say Alana (Principal Engineer), Harvey (QA lead), and another 5 engineers are working on a Teams in Space project. Everyone has write access to the repository, but you want to restrict access to the default and develop branches. From the branch permission dialog, you might want to assign permissions like this:
Branch | Branch permissions | Merge checks |
|---|---|---|
Default | Write access: Alana Merge via pull request: Alana, Harvey |
|
Develop | Write access: Alana, Harvey Merge via pull request: Alana, Harvey, |
|
Start by navigating to the repository where you want to add a branch restrictions, then go to Repository settings > Branch restrictions.
Add branch permissions and merge checks to the main branch
Click Add a branch restriction.
Enter the following into each field:
Branch or pattern: main
On the Branch permissions tab under Write access, select Only specific people or groups have write access: Alana (Alana automatically gets merge via pull request permissions)
On the Branch permissions tab under Merge access via pull requests, select Only specific people or groups have merge access: Harvey
Expand Add merge checks:
Select Minimum number of successful builds for the last commit with no failed builds.
Select 2 from the dropdown.
Click Save.
This setup helps the members of a workspace control access to the main branch. Because they only merges production ready code to main, they only want a merge check for successful builds.
Add branch permissions and merge checks to the develop branch
Click Add a branch restriction.
Enter the following into each field:
Branch or pattern: develop
On the Branch permissions tab under Write access, select Only specific people or groups have write access: Alana and Harvey Persona (Alana and Harvey automatically get merge via pull request permissions)
On the Branch permissions tab under Merge access via pull requests, select Only specific people or groups have merge access: teamsinspace:developers
Select the Merge settings tab, and select the following:
Select Minimum number of approvals and select 2 from the dropdown.
Select Minimum number of approvals from default reviewers and select the number of default reviewers, if you have set any for this pull request, you want to approve the pull request.
Select No unresolved pull request tasks.
Select Minimum number of successful builds for the last commit with no failed builds and select 3 from the dropdown.
Click Save.
Was this helpful?
Still need help?
The Atlassian Community is here for you.