Merge checks

Merge checks are a Premium feature for Bitbucket Cloud, but you can try them free for a limited time!

In the near future you will be able to choose to upgrade to a premium plan and continue to use merge checks. If you choose not to upgrade at that time, we will turn off any merge checks you have configured.

Learn more about Bitbucket Premium.

On this page:

Merge checks allow you to tightly control when merges occur to specific branches or branch patterns. Merge checks work in tandem with branch permissions to give your team flexibility and control over your development workflow with a few critical elements:

Build dependent merges

  • Ensure you're only merging changes with passing builds.
  • Select a specific number of successful build before you can merge.
  • Requires either Bitbucket Pipelines, a build tool integration, or connect using our commit status REST API.

Code review completion

  • Tie merges to code review.
  • Get your team working collaboratively with Bitbucket pull requests.
  • Keep your workflow consistent so developers know what they have to do to merge.

Task completion

  • Bitbucket pull requests include tasks to mark changes which need to be made.
  • Tasks are a great way to manage a pull request as it progresses to approval.
  • Teams can use merge checks with tasks to be sure all tasks in a pull request are complete before you can merge.

What's in a merge check?

You can use merge checks to require the following conditions before a merge:

Setting Result

Require at least {#} approvals

You must have at least that number of pull request approvals in order to merge to the target branch.
Reset approvals when the source branch of a pull request is modified If there are any changes to the source branch of the pull request, the approvals will be reset, and the approvers will have to review and approve the pull request again. in order to merge if you've selected a specific number of approvals.
Require all tasks to be resolved You must resolve all pull request tasks in order to merge.
Require a minimum of {#} successful builds

You must have that number of successful builds in order to merge.

The number of successful build statuses must be posted for the most recent commit.

Example merge check set up

Merge checks are applied to individual branches or branch patterns along with Branch permissions. Let's expand the example we used to describe branch permissions to include merge checks. 

So, 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 master and develop branches. You might want to assign permissions like this: 

Branch Permissions Merge checks

Write: Alana

Merge with pull request: (Alana) Harvey

Require successful builds: 2

Write: Alana, Harvey

Merge with pull request: (Alana, Harvey)
Teams in space:developers 

Require successful builds: 3

Require pull request approvals: 2

Require all tasks complete: Yes

Start by navigating to the repository where you want to add a branch permissions, then go to 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 Persona
    3. Merge via pull request: Harvey Persona.
  3. Expand Add merge checks.
  4. Select Require a minimum of 2 successful builds.
    The result will look something like this:
  5. Click Save.

This set up helps the team control access to the master branch. Since this team 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, then click Save.
    1. Branch or pattern: develop
    2. Write access: Alana Persona and Harvey Persona (Alana and Harvey also get merge via pull request permissions).
    3. Merge via pull request: developers
  3. Expand Add merge checks.
  4. Select and adjust the following fields:
    1. Require at least 2 approvals
    2. Require all tasks to be resolved
    3. Require a minimum of 3 successful builds
      The result will look something like this:

Final result on the branch permission page

Once you set up all the branch permissions and merge checks the landing page will look something like this:

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport