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

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community