Why a Bitbucket PR will not merge
A Bitbucket Cloud pull request that will not merge is blocked by one of three things: a merge conflict (the source and destination changed the same lines), an unmet merge check (not enough approvals, an open task, a failing build), or a branch restriction (a branch permission that forbids merging without approvals or passing builds). The critical catch — and the source of most "but the check failed and it merged anyway" confusion — is that on Bitbucket Cloud, unresolved merge checks are only warnings unless you are on Premium and have enabled "Prevent a merge with unresolved merge checks" (Suggest or require checks before a merge). So the first question is not "which check failed" but "is enforcement even turned on."
Diagnose it
Open the PR and read the merge panel top to bottom:
- "Merge" is unavailable and the PR notes conflicts → conflict. Resolve locally (below). Bitbucket Cloud is explicit that "when you have merge conflicts, you can't select the Merge button from the pull request to merge" (Resolve merge conflicts).
- Checks show warnings but Merge is still clickable → merge checks are not enforced (no Premium "prevent merge" setting). The check is advisory.
- Merge is blocked with a message about approvals or builds → a branch restriction is enforcing the requirement, which is the mechanism that actually blocks (Configure branch restrictions).
To see what the repository requires, a workspace admin can read the branch restrictions under repo Settings → Branch restrictions (under Workflow). Merge checks and branch permissions "work in tandem" — the check defines the condition, the restriction enforces it (Configure branch restrictions).
Root causes
Merge conflict. Someone changed the same code in the destination branch since you branched. Bitbucket surfaces this when you attempt to merge: "If anyone else has made changes in the destination to the same code you touched, we'll notify you of conflicts when you attempt to merge" (Resolve merge conflicts).
Unmet merge check. The configurable checks are: minimum number of approvals, minimum approvals from default reviewers, no changes requested, no unresolved PR tasks, and a minimum number of successful builds for the most recent commit (Suggest or require checks before a merge). Only a workspace admin can configure them.
Branch restriction. A branch permission such as a required approval count (require_approvals_to_merge in the API) forbids the merge until satisfied (Configure branch restrictions). Note a project-level restriction may not be overridable at the repo level (Cannot override project-level merge check at repository level).
Wrong merge strategy for the branch. If the branch requires a specific strategy and the dialog default is different, the merge can be refused; the default strategy is set by an admin on the Merge strategies page (Pull request and merge settings).
Resolution options
Resolve a conflict locally. Bitbucket Cloud has no in-UI conflict editor — you resolve on your machine and push. The documented flow pulls the destination into your feature branch (Resolve merge conflicts):
git checkout <feature_branch>
git pull origin <destination_branch> # brings in the conflicting changes
# Git marks the conflicts; edit the files to resolve them, then:
git add <resolved_file>
git commit -m "Merge <destination_branch> and resolve conflicts"
git push origin <feature_branch>
Once the push lands, Bitbucket recomputes mergeability and the Merge button becomes available.
Satisfy a merge check. Get the approvals, resolve the open PR tasks, clear any "changes requested," or get the required build green. For the "minimum successful builds" check, the build status comes from Bitbucket Pipelines, a Marketplace build integration, or the commit-status REST API (Configure branch restrictions) — so a missing build status, not a failed build, can also leave the check unmet.
Turn warnings into a real gate. If the problem is the opposite — people merging past failing checks — a workspace admin must, on Premium, enable "Prevent a merge with unresolved merge checks" (Suggest or require checks before a merge). Without Premium, the check cannot block.
Recommended approach (with tradeoffs)
If merges that bypass failing checks are a real risk for you, the only configuration that enforces anything on Bitbucket Cloud is Premium's "prevent merge" plus a branch restriction — advisory warnings will not stop a determined or distracted merger. The tradeoff is a plan cost and a stricter workflow: enforced checks mean a PR genuinely cannot land until its builds pass and reviews complete, which is the point, but it also means a flaky build or a missing build status blocks shipping until someone intervenes. Weigh that against the cost of an unreviewed or untested change reaching your default branch.
For conflict resolution, resist the urge to "merge the destination in" repeatedly to make the button light up — that produces a tangled history. A clean git pull of the destination, a deliberate resolution, and one merge commit is easier to read later than a chain of conflict-resolution merges.
Validation steps
After resolving, confirm the PR is actually mergeable rather than assuming the button means it:
- The PR page shows no conflict banner and the Merge button is enabled.
- Every configured merge check shows satisfied (not a lingering warning).
- If a branch restriction requires builds, the most recent commit shows a successful build status.
Prevention strategies
- Keep feature branches short-lived so the destination drifts less and conflicts are smaller and rarer.
- Decide enforcement deliberately. If checks must block, budget for Premium and configure the "prevent merge" setting plus a matching branch restriction — otherwise document that checks are advisory so no one assumes a gate that is not there.
- Wire builds to the commit status so the "minimum successful builds" check has a status to read; a check that never receives a build result stays unmet for the wrong reason.
Operational lessons
The Bitbucket-specific trap is the warning-versus-gate distinction. Teams configure merge checks, see them appear on PRs, and assume the branch is protected — until a change merges with a red build and no one understands how. On Cloud, a check is only a gate with Premium enforcement and a branch restriction behind it; everything else is a suggestion. Knowing that up front saves a confused incident review later.
When a PR is blocked, the useful context is rarely just "which check is red" — it is the commit behind it, the build that produced (or failed to produce) the status, and the destination changes that caused the conflict. Correlating the PR state with the build and the triggering commit is what turns "the merge is stuck" into "this commit needs a passing pipeline and a rebase against main."