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:

  • Ensure all merge checks are resolved before the pull request can be merged

  • Require another approval from reviewers, if the source branch of a pull request is modified

  • Automatically merge a pull request when all checks pass

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

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

Result

Check for at least {#} approvals

Users get notified when pull requests don't have that number of approvals.

Check for unresolved pull request tasks

Users get notified when they have open pull request tasks.

Check for {#} passed builds on the last commit

Users get notified when they don't have that number of successful builds for the most recent commit.

If you're on our Premium plan, you also have access to the following settings.

Setting

Result

Ensure all merge checks are resolved before the pull request can be merged

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 so that they can complete the merge.

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.

Automatically merge a pull request when all checks pass

The PR author or an admin can enable this feature to queue up a pending merge to be triggered automatically once all the merge checks have passed.

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 permissions, then go to Repository settings > Branch permissions.

Add permissions and merge checks to the master branch

  1. Click Add a branch permission.

  2. Enter the following into each field:

    1. Branch or pattern: master

    2. Write access: Alana (Alana automatically gets merge via pull request permissions)

    3. Merge via pull request: Harvey

  3. Expand Add merge checks:

    1. Select Check for {#} passed builds on the last commit.

    2. Select 2 from the dropdown.

  4. Click Save.

This setup helps the members of a workspace control access to the master branch. Because they only merges production ready code to master, they only want a merge check for successful builds.

Add permissions and merge checks to the develop branch

  1. Click Add a branch permission.

  2. Enter the following into each field:

    1. Branch or pattern: develop

    2. Write access: Alana and Harvey Persona (Alana and Harvey automatically get merge via pull request permissions)

    3. Merge via pull request: teamsinspace:developers

  3. Expand Add merge checks:

    1. Select Check for at least {#} approvals and select 2 from the dropdown.

    2. Select Check for at least {#} approval 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 Check for unresolved pull request tasks.

    4. Select Check for {#} passed builds on the last commit and select 3 from the dropdown.

  4. Click Save.

Last modified on Jan 7, 2021
Cached at 9:26 PM on Jan 20, 2021 |

Additional Help

Ask the Community