BB
Bitbucket Pipelines Conventions
Pipeline YAML structure, naming, and step organization
Details
Language / Topic
Bitbucket PipelinesCategory
Style Guide
Rules
balanced
- Structure bitbucket-pipelines.yml with top-level sections in order: image → definitions → pipelines (default, branches, pull-requests, custom, tags)
- Use descriptive step names for every step — names appear in the Bitbucket UI build log and are essential for debugging failures
- Set max-time on steps (default 120 minutes) to prevent runaway builds from consuming build minutes; keep lint/test steps under 10 minutes
- Use YAML anchors (&alias and *alias) with definitions to share common step configurations across branches and avoid YAML duplication
- Define a global image: at the top level; override per-step with image: only when a step requires a different runtime
- File must be named bitbucket-pipelines.yml and placed in the repository root — Bitbucket will not detect it elsewhere
- Top-level ordering: image → options → clone → definitions (caches, services) → pipelines (default, branches, pull-requests, tags, custom)
- Every step must have a descriptive name: field — shown in the Bitbucket UI sidebar and critical for identifying failures in multi-step pipelines
- Set max-time on resource-intensive steps; the global default is 120 minutes, but lint/test should be 10-15, builds 30, deploys 20
- Use options: max-time: at the global level to set a default timeout for all steps; override per-step where needed
- Use YAML anchors for shared step definitions: define &build-test under definitions and reference with *build-test in branch pipelines
- Override anchored steps with <<: *base-step to merge and extend base definitions with branch-specific scripts or after-script blocks
- Define a top-level image: for the most common runtime (e.g., node:20, python:3.12); override per-step only when a step needs a different image
- Use script: arrays with one logical command per line — avoid long chained && commands that obscure which command actually failed
- Add after-script: blocks for cleanup tasks (test reports, coverage uploads) that must run regardless of step success or failure
- Organize branch pipelines by environment: branches: develop for CI, staging for pre-prod validation, main/master for production deploys