Bitbucket Pipelines configuration reference

Overview

The bitbucket-pipelines.yml file configures automated builds, tests, and deployments. Configuration options organize into these top-level sections:

options: Global pipeline settings
clone: Git repository behavior
definitions: Cache and service containers
image: Docker image configuration
pipelines: Pipeline execution flow
parallel: Concurrent step execution
stage: Logical groupings of steps
step: Individual pipeline tasks

Global Options (`options`)

Contains settings applying to all pipelines in a repository.

Docker

Enable Docker command execution across all steps:

options:
  docker: true
pipelines:
  default:
    - step:
        script:
          - docker version
          - docker run hello-world

Property: docker Data type: Boolean Default: false

Max Time

Set maximum step runtime (in minutes):

options:
  max-time: 30
pipelines:
  default:
    - step:
        name: Sleeping step
        script:
          - sleep 120m # Timeout after 30 minutes

Property: max-time Data type: Integer Allowed values: 1–720 Default: 120 minutes

Size

Allocate additional resources to steps or pipelines on Bitbucket Cloud or Linux Docker self-hosted runners:

Size	CPU	Memory	Volume
1x	2	4GB	64GB
2x	4	8GB	64GB
4x	8	16GB	256GB
8x	16	32GB	256GB
16x	32	64GB	256GB
24x	48	96GB	256GB
32x	64	128GB	256GB

options:
  size: 2x
pipelines:
  default:
    - step:
        script:
          - echo "Double memory allocated"

Property: size Default: 1x Note: Larger sizes consume proportionally more build minutes and require Standard/Premium plans.

Runtime

Configure runtime behavior (architecture, IP ranges):

options:
  runtime:
    cloud:
      atlassian-ip-ranges: true
      arch: arm

Property: runtime Required child: cloud

Clone Configuration

Controls how the Git repository is cloned at the start of each step.

Clone Depth

Set a shallow clone depth to speed up cloning. The default depth is 50.

clone:
  depth: 2

Set to full for a complete history (useful for version calculations or changelogs):

clone:
  depth: full

Git LFS

Enable or disable Git Large File Storage support:

clone:
  lfs: true

Skip Cloning

Disable cloning entirely when the step does not need the repository source (for example, a pure deployment step):

clone:
  enabled: false

Clone Properties

Property	Description	Default
`depth`	Shallow clone depth. Use an integer or `full`	`50`
`lfs`	Enable Git LFS	`false`
`enabled`	Whether to clone at all	`true`

Pipeline Structure

Basic Pipeline

image: node:18
pipelines:
  default:
    - step:
        name: Build and Test
        script:
          - npm install
          - npm test

Branch-Specific Pipelines

pipelines:
  branches:
    main:
      - step:
          name: Deploy to Production
          deployment: production
          script:
            - ./deploy.sh
    develop:
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - ./deploy.sh staging

Pull Request Pipelines

pipelines:
  pull-requests:
    '**':
      - step:
          name: Test PR
          script:
            - npm test

Tag Pipelines

pipelines:
  tags:
    'v*':
      - step:
          name: Release
          script:
            - ./release.sh

Custom Pipelines

pipelines:
  custom:
    deploy-to-staging:
      - step:
          name: Manual Deploy
          deployment: staging
          script:
            - ./deploy.sh

Parallel Execution

Run multiple steps simultaneously:

pipelines:
  default:
    - parallel:
        - step:
            name: Unit Tests
            script:
              - npm run test:unit
        - step:
            name: Integration Tests
            script:
              - npm run test:integration
        - step:
            name: Lint
            script:
              - npm run lint

Stages

Group steps for organized execution:

pipelines:
  default:
    - stage:
        name: Build
        steps:
          - step:
              name: Compile
              script:
                - npm run build
    - stage:
        name: Test
        steps:
          - step:
              name: Run Tests
              script:
                - npm test
    - stage:
        name: Deploy
        deployment: production
        steps:
          - step:
              name: Deploy
              script:
                - ./deploy.sh

Step Options

Common Step Properties

- step:
    name: Build Application
    image: node:18
    caches:
      - node
    services:
      - redis
    artifacts:
      - dist/**
    script:
      - npm install
      - npm run build

Conditional Execution

- step:
    name: Deploy
    condition:
      changesets:
        includePaths:
          - "src/**"
    script:
      - ./deploy.sh

Definitions

Define reusable resources:

definitions:
  caches:
    npm: ~/.npm
    cypress: ~/.cache/Cypress
  services:
    redis:
      image: redis:7
    postgres:
      image: postgres:15
      variables:
        POSTGRES_DB: testdb
        POSTGRES_USER: testuser
        POSTGRES_PASSWORD: $DB_PASSWORD

Complete Example

image: node:18
definitions:
  caches:
    npm: ~/.npm
  services:
    postgres:
      image: postgres:15
      variables:
        POSTGRES_DB: myapp
        POSTGRES_PASSWORD: $DB_PASSWORD
options:
  max-time: 60
  size: 2x
pipelines:
  default:
    - step:
        name: Build and Test
        caches:
          - node
          - npm
        services:
          - postgres
        script:
          - npm install
          - npm run build
          - npm test
        artifacts:
          - dist/**
  branches:
    main:
      - step:
          name: Build
          caches:
            - node
          script:
            - npm install
            - npm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy to Production
          deployment: production
          script:
            - ./deploy.sh production
  pull-requests:
    '**':
      - step:
          name: PR Tests
          caches:
            - node
          script:
            - npm install
            - npm test
            - npm run lint

Key Structural Elements

Pipeline: Top-level trigger definitions (default, branches, tags)
Step: Individual executable tasks with scripts and configuration
Parallel: Execute multiple steps simultaneously
Stage: Group steps for organized execution flow
Definitions: Reusable service and cache configurations

Next Steps

Configure Docker Images for your build environment
Set up Variables and Secrets
Add Caching to improve performance
Use Service Containers for testing