How to Run Conditional Steps by Branch in Bitbucket Pipelines

The branches: block scopes a pipeline to matching branch names, and the condition: key gates a step on changed files.

Under pipelines.branches, key blocks by branch glob (e.g. main, feature/*). Use a step condition: with changesets to skip work when nothing relevant changed.

Branch-specific pipeline and a file condition

main deploys; the deploy step runs only when files under src/ changed.

pipelines:
  branches:
    main:
      - step:
          name: Deploy
          condition:
            changesets:
              includePaths:
                - "src/**"
          script:
            - ./deploy.sh
    'feature/*':
      - step:
          name: Test
          script: [npm ci, npm test]

Gotchas

• Branch keys use glob patterns; quote ones with special characters like feature/*.
• The condition: changesets check skips a step when no matching files changed, useful for monorepos.
• A push with no matching branches: block falls back to the default: pipeline.

Related guides