Stop Merging Red Builds: Bitbucket's Required Status Checks in Practice

What the feature actually does

Required status checks are a branch‑level merge gate. When you open a pull request targeting a protected branch (usually main or master), Bitbucket looks at the build statuses posted against the pull request’s source commit. If any status you’ve marked as required is missing, pending, or failed, the merge button stays disabled. Once all required checks report success, the merge button becomes available.

Configuring it

You need repository admin permissions to change these settings. In Bitbucket Cloud:

1. Open the repository and go to Repository settings.
2. Under Workflow, open Branch permissions.
3. Add or edit a permission for your target branch pattern, e.g. main.
4. Enable the merge check requiring a minimum number of successful builds, or select specific builds that must pass.

Two decisions matter here. First, how many successful builds to require versus which specific builds. Requiring “at least 1 successful build” is a blunt instrument — any green check satisfies it, including an irrelevant one. Naming specific checks (for example, your test and lint pipeline steps) is stricter and usually what you want on the default branch.

Second, whether to combine this with other merge checks like minimum approvals. Required status checks answer “is the code green?” — they say nothing about “did a human review it?” Most teams want both.

A worked example with Pipelines

In Bitbucket Cloud, the most common pairing is with Bitbucket Pipelines. A minimal bitbucket-pipelines.yml that produces two distinct checkable results:

pipelines:
  pull-requests:
    '**':
      - step:
          name: lint
          script:
            - npm ci
            - npm run lint
      - step:
          name: test
          script:
            - npm ci
            - npm test

Each step posts a build status back to the pull request. If you’ve configured the branch permission to require these builds to succeed, a PR where npm test fails will show a disabled merge button with an explanation of which check is failing. Fix the code, push, the pipeline reruns, the status flips to green, and merging unblocks — no admin intervention needed.

If you use an external CI system (Jenkins, GitHub Actions, a self‑hosted runner), the same gate works as long as that system posts commit build statuses to Bitbucket’s API. The check doesn’t care where the status comes from; it cares that a status with the expected name reports success.

Where this bites people

The feature is reliable, but two failure modes are common enough to plan for.

Renamed or restructured pipelines. If your branch permission expects a check called build-and-test and someone renames the pipeline step to ci, every pull request suddenly shows a missing required check and merging freezes. The fix is trivial — update the branch permission — but the confusion costs an afternoon if nobody connects the dots. Treat pipeline step names as part of your merge contract.

Slow pipelines become a merge queue. If your full test suite takes 40 minutes, every PR now waits 40 minutes minimum, and any push to the source branch restarts the clock. The gate is doing its job, but developer cycle time suffers. The usual answer is a tiered pipeline: fast checks (lint, unit tests) required for merge, slow checks (integration, end‑to‑end) run post‑merge or on a schedule. Requiring everything on every PR is how teams end up disabling the gate entirely.

One more limitation worth knowing: the check validates the state of the source commit, not the hypothetical merge result. Two PRs that each pass independently can still conflict semantically when both merge. If that risk matters to you, look into requiring branches to be up to date before merging, which forces a re‑run against the latest target.

Verify it before you trust it

Don’t assume the gate works because the settings page looks right. Prove it:

1. Create a throwaway branch, introduce a deliberate test failure, and open a pull request against your protected branch.
2. Confirm the merge button is disabled and the UI names the failing check.
3. Push a fix, wait for the pipeline, and confirm the button enables once the status turns green.
4. Also test the missing‑check case: open a PR from a branch where the pipeline didn’t run at all. It should be blocked too.

Five minutes of deliberate failure testing beats discovering a configuration gap after a broken deploy.

The takeaway

Required status checks convert “please don’t merge red builds” from a social norm into an enforced rule. Start with your default branch, require your fast and meaningful checks by name, pair it with an approval requirement, and verify the gate with a deliberately failing PR. Then revisit quarterly — pipelines evolve, and a merge gate pointing at a check that no longer exists is worse than no gate at all.