Agent RulesAgent Rules
BB

Pipes & Reusable Steps

Using and creating Bitbucket Pipes for DRY pipelines

Bitbucket Pipelines
Architecture
pipes
reusable
anchors
caches
services
Use in BuilderAll Bitbucket Pipelines Options

Details

Language / Topic
bitbucket-pipelinesBitbucket Pipelines
Category
Architecture

Rules

balanced
- Use Atlassian-maintained pipes for common tasks: atlassian/aws-s3-deploy, atlassian/slack-notify, atlassian/docker-publish
- Pin pipe versions to specific tags (e.g., atlassian/aws-ecr-push-image:2.3.0) for reproducible builds — never use floating tags
- Use YAML anchors (&anchor and *anchor) with the merge key (<<:) to share step definitions across branches without duplication
- Create custom pipes as Docker images for complex reusable logic shared across multiple repositories in the workspace
- Define caches and services in the definitions: block and reference them by name in steps to keep pipeline YAML DRY
- Pipes are pre-built Docker containers that encapsulate CI/CD tasks: pipe: atlassian/aws-s3-deploy:1.0.2 with variables: block
- Prefer Atlassian-maintained pipes for AWS, Azure, GCP, Docker, Slack, Jira integrations — they are tested, documented, and maintained
- Pin pipe versions to exact tags (2.3.0 not 2); review pipe changelogs before upgrading — pipes can introduce breaking changes
- YAML anchors for step reuse: define &install-and-test under a top-level x-definitions key; reference with *install-and-test in branch pipelines
- Merge key <<: *base-step inherits all properties from the anchor; add or override specific fields like deployment: or script: entries
- Custom pipes: create a Docker image with a pipe.sh entrypoint that reads BITBUCKET_* and pipe-specific environment variables
- Store custom pipe source in a dedicated Bitbucket repository; publish the Docker image to Docker Hub or a private registry
- Version custom pipes semantically: major for breaking changes, minor for features, patch for fixes — consumers pin to specific versions
- definitions: caches: define named caches (node, pip, maven, docker, custom paths); reference in steps with caches: [node]
- definitions: services: define service containers (postgres, redis, elasticsearch) with image and memory allocation; reference with services: [postgres]
- Use parallel: to run independent steps concurrently within a stage — reduces total pipeline time to the duration of the slowest parallel step
- Combine YAML anchors with parallel steps: define common test steps as anchors, run them in parallel across branch pipelines