How to put checks before merging a PR in BitBucket

Merge checks enable you to set recommended or mandatory conditions for merging changes into specific branches or branch patterns. They work alongside branch permissions, providing your team with greater flexibility and control over the development workflow.

Purpose of Merge Checks

Dependent Merges

• Ensure only changes with passing builds are merged.

• Specify the required number of successful builds before merging.

• Integrate with Bitbucket Pipelines, our App Marketplace build tools, or the commit status REST API.

Code Review Completion

• Link merges with the code review process.

• Encourage collaborative workflows using pull requests.

• Maintain consistency, ensuring developers know what’s required before merging.

Task Completion

• Add tasks to pull requests to address necessary changes.

• Monitor pull requests as they progress toward approval.

• Require all tasks to be resolved before merging.

Bitbucket Premium: Advanced Merge Checks

Bitbucket provides recommended merge checks for all users, helping ensure that pull requests meet your team’s standards. With Bitbucket Premium, you unlock additional merge checks to enhance your code review process:

Enforce Merge Checks: All conditions must be met before a pull request can be merged, ensuring thorough review and code quality.

Additional Reviewer Approvals: If the source branch is modified after initial reviews, new approvals are automatically requested.

Preserve Approvals for Unchanged Diffs: When the diff does not change, previous approvals are retained, saving time and effort during reviews. These features help maintain a streamlined, consistent workflow while ensuring every merge meets your team’s requirements.

Configuring and Setting Up Custom Merge Checks

Only Workspace Admins can configure and manage custom merge checks. For detailed instructions, refer to the guide on Setting Up and Using Custom Merge Checks.

Using Merge Checks

Merge checks let you recommend or require specific conditions to be met before merging. They work alongside branch permissions, providing flexibility and control over your development workflow.

Key Features of Merge Checks

• Free Plan: You can select merge check options to alert users about unresolved conditions. However, they can still merge despite the warnings.

• Premium Plan: Prevent users from merging with unresolved merge checks by enabling the "Prevent a merge with unresolved merge checks" option.

Merge Check Options

Condition	What It Does
Minimum number of approvals	Notifies users if a pull request doesn't have the required number of approvals. Note: Self-approvals don’t count.
Minimum approvals from default reviewers	Alerts users when the required number of default reviewers haven't approved the pull request.
No changes are requested	Warns users if any reviewer has marked 'Changes requested.'
No unresolved pull request tasks	Flags open tasks within the pull request that need to be completed.
Minimum successful builds for last commit	Ensures the last commit has the specified number of successful builds, with no failed or in-progress builds.
Maximum commits behind destination branch	Alerts users if the branch is behind the destination branch by the specified number of commits.
Reset changes requested on source branch modification	Automatically clears 'Changes requested' statuses when the source branch is modified.
Allow automatic merge when builds pass	Enables merging while builds are running. The merge is completed only if the builds succeed.

Premium-Only Features

Setting	What It Does
Reset approvals on source branch modification	Removes approvals if the source branch is modified, requiring reviewers to reapprove the pull request.
Keep approvals with no diff changes	Retains approvals if no changes are made to the diff (e.g., empty commits or rebasing without code changes).
Prevent merging with unresolved checks	Blocks merging until all merge checks are resolved, with a checklist showing pending requirements.

These settings provide granular control to ensure only vetted and high-quality code makes it to your branches.

Adding Branch Permissions and Merge Checks

Configure Permissions and Checks for the main Branch

1. Navigate to the repository settings and click Add a branch restriction.

2. Fill in the following fields:

   • Branch or pattern: main

3. Under the Branch permissions tab:

   • Write access: Select Only specific people or groups that have write access and assign access to Alana. (Note: Alana automatically gets merged via pull request permissions.)

   • Merge access via pull requests: Assign access to Harvey.

4. Expand Add merge checks:

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

   • From the dropdown, choose 2.

5. Click Save.

This configuration ensures that only production-ready code is merged into the main branch, requiring at least two successful builds before merging.

Configure Permissions and Checks for the develop Branch

1. Navigate to the repository settings and click Add a branch restriction.

2. Fill in the following fields:

   • Branch or pattern: develop

3. Under the Branch permissions tab:

   • Write access: Assign to Alana and Harvey Persona. (Note: Alana and Harvey automatically get merged via pull request permissions.)

   • Merge access via pull requests: Assign to teamsinspace:developers.

4. Go to the Merge settings tab and configure the following:

   • Minimum number of approvals: Set to 2.

   • Minimum approvals from default reviewers: Set to the desired number of default reviewers for the pull request.

   • No unresolved pull request tasks: Enable this option to ensure tasks are completed before merging.

   • Minimum number of successful builds for the last commit: Set to 3.

5. Click Save.

This setup provides structured control over the develop branch, requiring multiple approvals, successful builds, and task completion for consistent code quality.