In this page

What is a merge check?

In Bitbucket Cloud, merge checks ensure that pull requests meet specific requirements before being merged into the repository. They help guarantee that changes are thoroughly reviewed and meet your standards.

Note: while Bitbucket and GitHub use the term "pull request", other platforms like GitLab refer to them as "merge requests". Despite the different terminology, the concept is the same, though the underlying implementations may differ.

How to use merge checks?

The app provides the custom merge check called "Commit policy satisfied". It ensures that the pull request details (such as title and description), as well as all commits in a pull request, adhere to the rules defined in the commit policy.

Activate the merge check

To activate the merge check in a Bitbucket repository:

  1. Enable the custom merge check in the repository.
  2. Add the commit policy configuration file to the repository.

Once these are completed, the merge check will automatically apply to all pull requests in the repository, including both existing and future ones.

View the merge check

The results of Bitbucket merge checks can be seen directly on the pull request page:

  1. Go to Pull requests (in the repository left-bar).
  2. Click the pull request you are interested in.
  3. See the pull request details in the right-bar.

At the top of the right-bar, you'll find a section listing all the checks that Bitbucket runs on the pull request. It also includes the Commit policy satisfied check:

The result of the last run is indicated by an icon:

  • The Passed status with a green tick means the pull request satisfied all the commit policy conditions.
  • The Did not pass status means the pull request violates one or more conditions in the policy. In this case, if the merge check is configured as required, you won't be able to merge the pull request!

At the bottom of the right-bar, you can find the Commit policy section:

It contains more details about the last run of the merge check:

Fix the merge check

If the merge check found violations or failed to run:

  1. Review the Commit policy section at the bottom of the pull request's right-bar to identify the specific violations or problems.
  2. Make the necessary changes to the pull request's title, description, or commits to comply with the commit policy.
  3. Push the updated code to the source branch of the pull request.
  4. Rerun the merge check.
Run the merge check

Bitbucket automatically runs merge checks in the following events:

If the last run did not pass, you can manually rerun the check by clicking the Rerun button next to the merge check name. Note that running the check again is not possible if the last run passed! (It is a feature design decision by Atlassian.)

💡 If the Rerun button is not available, but you want to rerun the check, you can force it by clicking the Approve button! Don't forget to also click Unapprove to revert the change. This trick is useful in several situations.

Questions?

Ask us any time.