Stopping the 'Merge and Pray' Cycle with Bitbucket Merge Checks

The Problem: The Accidental Merge

Every engineering team has been there: a developer merges a pull request (PR) because they forgot to check the CI pipeline, or a junior dev merges their own code without a second pair of eyes. When this happens to a production branch, the result is a broken build, a failed deployment, and an immediate scramble to revert changes.

The goal isn't just to ask developers to be careful; it is to make it technically impossible to merge code that hasn't met your quality bar. In Bitbucket, this is achieved by combining Branch Permissions with Merge Checks.

Defining the Guardrails

Merge checks are server-side gates that disable the merge button in the UI and block API calls until specific conditions are met. Unlike a manual checklist, these are enforced by the platform.

Branch Permissions: Who Can Touch the Code?

Before you set merge checks, you must define which branches are protected. Branch permissions allow you to restrict who can push directly to a branch or force-push (which overwrites history). For a production branch, you should typically disable direct pushes entirely, forcing all changes through a pull request.

Merge Checks: What Must Happen First?

Once a branch is protected, merge checks define the "definition of done" for a PR. Common checks include:

• Minimum Approvals: Ensures at least X number of reviewers have signed off.
• Successful Build: Requires the linked CI/CD pipeline to report a 'Successful' status.
• No Unresolved Comments: Prevents merging if a reviewer has left a comment that hasn't been marked as resolved.

Worked Example: Enforcing a Strict Production Gate

Consider a scenario where you want to ensure that no code reaches the main branch without two approvals and a passing test suite. This configuration applies to Bitbucket Cloud and Data Center (though UI labels may vary slightly by version).

Configuration Steps

1. Navigate to Repository Settings: Go to Repository settings > Branch permissions.
2. Add a Permission: Select the main branch. Set "Write access" to a limited group (e.g., Admins) and ensure "Prevent rewriting history" is checked.
3. Configure Merge Checks: Go to Repository settings > Pull request settings.
4. Enable the following toggles:
   • Check Minimum number of approvals and set it to 2.
   • Check Check for unresolved comments.
   • Check Require a successful build (this assumes you have a Bitbucket Pipeline or an external CI tool integrated via API).

Verification Process

To verify this is working, create a feature branch and open a PR to main. Observe the following behaviors:

• Initial State: The merge button should be disabled or show a warning that checks are not met.
• Partial Success: After one approval, the button should remain disabled.
• Full Success: Once the second approval is granted and the pipeline completes successfully, the merge button becomes active.

Trade-offs and Limitations

While merge checks provide safety, they introduce friction. The most significant limitation is the Administrative Override. Users with repository admin permissions can often bypass these checks. While useful for emergency hotfixes, this creates a security gap. To mitigate this, teams should regularly review audit logs to ensure overrides are only used in genuine emergencies.

Additionally, merge checks are reactive. They stop a merge at the end of the process. They do not replace proactive security measures like secret scanning or dependency vulnerability checks, which should happen during the coding phase or as part of the pipeline itself.

Actionable Closing

If your team is still relying on "honor system" reviews, start by protecting your main branch today. Begin with a single required approval and a successful build check. Once the team adapts to the workflow, layer in unresolved comment checks to ensure that feedback is actually addressed rather than ignored.