Can Bitbucket block a merge when the Pipelines build fails?

Yes, but with a condition. Bitbucket merge checks can require a minimum number of successful builds on the last commit, with no failed or running builds. Preventing a merge while checks are unresolved is listed as a Premium feature. On other plans, users are warned but can still merge.

The checks available

Bitbucket's merge check page lists these for a branch or branch pattern, working alongside branch permissions:

Other options include a maximum number of commits behind the destination branch and automatic merge when builds pass. The build check works with Bitbucket Pipelines, a marketplace build tool or the commit status API. If only the build check is unresolved, a user can merge while the build runs, and the merge goes through if the build passes and is blocked if it fails.

Pull request pipelines in Pipelines

A pipeline defined under pull-requests runs when a pull request is created or updated. Bitbucket says it merges the destination branch into your working branch before it runs, and if that merge fails, the pipeline stops. Pull request pipelines run in addition to branch and default pipelines, so two may start. The page also states that pull requests from a forked repository do not trigger the pipeline, which means a fork's change may reach review without your scan having run.

pipelines:
  pull-requests:
    '**':
      - step:
          name: Scan and test
          script:
            - ./run-checks.sh

Steps to set up a gate

1. Add a pull-requests pipeline that includes your security scan and tests.
2. In repository settings, add merge checks for main and release branches.
3. Require at least one successful build and at least one approval.
4. On Premium, turn on preventing merges with unresolved checks. Without it, treat the check as advice.
5. Set branch permissions so only a small group can merge, and consider who can write directly.
6. For fork contributions, have a maintainer pull the branch into the repository and run the checks before merging.

Custom merge checks need the Workspace admin role. The page does not describe a separate bypass role, so confirm in your own settings who can override.

Try it yourself

Click through it at your own pace, or open it full screen. Look at the state where the gate says no, and what the developer sees.

For how to decide what blocks, see which pipeline findings should block, warn or log. Safeguard policies and gates can enforce findings checks on connected repositories, and a free scan is at https://gold.safeguard.sh/scan.

Quick check

Sources

• Atlassian: Suggest or require checks before a merge, fetched 19 October 2026.
• Atlassian: Pipeline start conditions, fetched 19 October 2026.

Last reviewed: 19 October 2026.