How to Run Pull Request Pipelines in Bitbucket Pipelines

By Daniel Zoghalchali·Latchkey

The pull-requests section triggers on PR activity and runs against a temporary merge of source and target, so checks reflect the merged result.

Add a pull-requests: section keyed by source branch glob. Pipelines runs it when a matching PR is created or updated, merging in the destination branch first.

Steps

• Add pull-requests: under pipelines.
• Key it by source branch (use ** for all branches).
• List the checks you want to gate the merge.

bitbucket-pipelines.yml

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

Gotchas

• If a push matches both branches and pull-requests, the pull-request pipeline takes priority while a PR is open.
• The merge check is skipped when the PR has conflicts; Pipelines then builds the source branch as-is.

Verify it actually works

Bitbucket validates bitbucket-pipelines.yml on push, and a schema error disables the pipeline rather than failing a build, which can look like nothing happened at all.

# validate before pushing
curl -X POST -H "Content-Type: application/x-yaml" \
  --data-binary @bitbucket-pipelines.yml \
  https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/pipelines/validate

# confirm which pipeline definition matched
# Pipelines -> the run -> "Configuration" tab

Constraints that catch people out

• Each step runs in a fresh container. Nothing persists between steps unless it is declared as an artifact or a cache.
• The default memory allocation per step is limited, and service containers share that budget, so adding a database service can push a previously passing build into an out-of-memory failure.
• Only branches with a matching branches: definition run; a push to an unmatched branch silently runs nothing.
• Artifacts are passed forward only to later steps in the same pipeline, not between pipelines.

Frequently asked questions

Related guides

References

• GitHub Actions documentation