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.

Learn more about Bitbucket Premium.

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

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.

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

  • Check for 2 passed builds on the last commit

Develop

Write access: Alana, Harvey

Merge via pull request: Alana, Harvey,
teamsinspace:developers (group)

  • Check for 3 passed builds on the last commit

  • Check for at least 2 approvals

  • Check for unresolved pull request tasks

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

  1. Click Add a branch restriction.

  2. Enter the following into each field:

    1. Branch or pattern: main

    2. 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)

    3. On the Branch permissions tab under Merge access via pull requests, select Only specific people or groups have merge access: Harvey

  3. Expand Add merge checks:

    1. Select Minimum number of successful builds for the last commit with no failed builds.

    2. Select 2 from the dropdown.

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

  1. Click Add a branch restriction.

  2. Enter the following into each field:

    1. Branch or pattern: develop

    2. 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)

    3. On the Branch permissions tab under Merge access via pull requests, select Only specific people or groups have merge access: teamsinspace:developers

  3. Select the Merge settings tab, and select the following:

    1. Select Minimum number of approvals and select 2 from the dropdown.

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

    3. Select No unresolved pull request tasks.

    4. Select Minimum number of successful builds for the last commit with no failed builds and select 3 from the dropdown.

  4. Click Save.

Additional Help