How to use merge checks to enforce your master branch

Your master branch represents the code that you will ship to your customers, and should be protected at all costs. No one intends to ship a bug to a customer on purpose, so having a mechanism in place to catch these subtle bugs is essential to a development team. Code review has been around in some form since the dawn of version control to help keep a close eye on the master branch and ensure code quality is high.

Pull requests in particular provide a way to do peer code reviews and merges as part of a branch-based development workflow. As teams grow sometimes you need to take pull requests a step further to really make sure code is ready to be merged into the family jewel: the master branch.

What are merge checks and why are they important

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 your team flexibility and control over the deployment workflow. They help ensure:

  • Dependent merges:
  • Code review completion:
    • Tie merges to code review.
    • Get your team 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 in Bitbucket Cloud

In Bitbucket Cloud, merge checks is available on Free or Standard plans.

With merge checks, you can recommend users to have the following conditions met before merging*:

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.

Merge checks apply to individual branches or branch patterns along with branch permissions. Learn more about how to set up merge checks in Bitbucket and how to use them with branch permissions here.

*Recommended merge checks means that we'll warn users when they have unresolved merge checks, but they'll still be able to merge. If you're interested in requiring users to perform checks before merging, you'll need to upgrade to Premium and select "Prevent a merge with unresolved merge checks".

Enforced merge checks in Bitbucket Cloud

Enforced merge checks, a feature of Bitbucket Cloud Premium, make it easy to ensure that every pull request is fully vetted before it gets merged. This gives admins the ability to require users to perform checks before merging. Admins can require all of the checks available on Free and Standard, and more:

Setting Result
Require a certain number of approvers Get at least 1 additional set of eyes on any change before it is merged. (On the Bitbucket Cloud team, we require 2 approvals for every Pull Request.)
Require a certain number of successful builds Peer reviews are great but take that extra step and make sure the builds are passing pre-merge. Everyone says don't break the build, but do you mean it?
Require all tasks to be completed Those tasks are there for a reason. Make sure all the feedback reviewers leave gets addressed, instead of promises to fix it later.
Reset approvals when the source branch of a pull request is modified Along with required approvers, this guarantees that no change goes unreviewed. This can be overkill for some branches, where reviewers can approve a PR while trusting the author to make some small tweaks, but it's great for making sure nothing slips into a critical branch (typos in the release branch, anyone?).

Atlassian is a public company, so the Bitbucket team uses these checks as part of our compliance controls to prevent unauthorized changes to our code, and we know many teams have similar requirements. We also know that having an entire repository locked down can be frustrating, which is why we made merge checks totally configurable at the branch level. Production code can be protected and thoroughly reviewed but until it's ready, you can still iterate quickly on features in dev and staging, all in the same repository.

Try Enforced Merge Checks

Enforced Merge Checks is a feature in Bitbucket Cloud's Premium plan which has features for teams that require granular admin controls, security and auditing. Bitbucket Cloud Premium is available at $6/user/month.

If you’re ready to get started, sign up for a free Bitbucket Cloud account or upgrade to Premium.

If you’re already a Bitbucket Cloud Premium user, you can add merge checks from your repository settings menu, under the branch permissions section.

Happy coding!


Interested in upgrading to Standard or Premium for more advanced admin settings, security permissions, and greater flexibility?

Upgrade now