Use Docker images as build environments

Overview

Bitbucket Pipelines executes builds within Docker containers that utilize images to define the build environment. You can select Bitbucket's default image or provide your own custom image.

The platform supports both public and private Docker images from Docker Hub, AWS, Google Cloud, and self-hosted registries. However, images must be accessible via the internet—internal registries without internet connectivity are not currently supported.

Default build environment

When no image is specified, Bitbucket automatically uses atlassian/default-image:latest. This image comes pre-configured with common development tools.

Available Default Images

Image	OS	Notable Tools
`atlassian/default-image:1`	Ubuntu 14.04	Git 1.9.1, Maven 3.0.5, Node 4.2.1, Python 2.7.6
`atlassian/default-image:2`	Ubuntu 16.04	Git 2.7.4, Maven 3.3.9, Node 8.9.4, Python 2.7.12
`atlassian/default-image:3`	Ubuntu 20.04 LTS	Git 2.25.1, Node 14.17.5, Python 3.8.10
`atlassian/default-image:4`	Ubuntu 22.04 LTS	Git 2.39.1, Node 18.13.0, Python 3.10.6 (self-hosted)
`atlassian/default-image:5`	Ubuntu 24.04 LTS	Git 2.49.0, Node 22.15.0, Python 3.12.3, Docker CLI (cloud-hosted)

After initial setup, try to find a specific image you can use to avoid relying on default images. This enables faster builds and better compatibility.

Using Public Images

Public images from Docker Hub can be referenced directly by name. For example:

image: openjdk

For specific versions or accounts:

image: account-name/openjdk:8

Images outside Docker Hub require the full URL:

image: docker.someprovider.com/account-name/openjdk:8

Common Language Images

Node.js

image: node:18
pipelines:
  default:
    - step:
        script:
          - npm install
          - npm test

Python

image: python:3.11
pipelines:
  default:
    - step:
        script:
          - pip install -r requirements.txt
          - pytest

Java

image: maven:3.9-eclipse-temurin-17
pipelines:
  default:
    - step:
        script:
          - mvn clean install

Go

image: golang:1.21
pipelines:
  default:
    - step:
        script:
          - go build
          - go test ./...

Using Private Images

Docker Hub Private Images

image:
  name: account-name/openjdk:8
  username: $DOCKER_HUB_USERNAME
  password: $DOCKER_HUB_PASSWORD

The email field was previously supported but is now deprecated and no longer required.

AWS ECR Images

Using credentials:

image:
  name: <account-id>.dkr.ecr.<region>.amazonaws.com/openjdk:8
  aws:
    access-key: $AWS_ACCESS_KEY
    secret-key: $AWS_SECRET_KEY

Using OpenID Connect (recommended):

image:
  name: <account-id>.dkr.ecr.<region>.amazonaws.com/openjdk:8
  aws:
    oidc-role: arn:aws:iam::<account-id>:role/<role-name>

Google Container Registry Images

image:
  name: <region>.gcr.io/<project>/image:latest
  username: _json_key
  password: '$GCR_JSON_KEY'

Other Registries

image:
  name: docker.your-company-name.com/account-name/openjdk:8
  username: $USERNAME
  password: $PASSWORD

Pinning Images by Digest

For immutability, reference images by their cryptographic hash:

image:
  name: ubuntu@sha256:a0ee7647e24c8494f1cf6b94f1a3cd127f423268293c25d924fbe18fd82db5a4

To find an image's digest:

docker inspect --format='{{.RepoDigests}}' ubuntu

Per-Step Images

Override the default image for specific steps:

image: node:18
pipelines:
  default:
    - step:
        name: Build with Node
        script:
          - npm install
          - npm run build
    - step:
        name: Deploy with Python
        image: python:3.11
        script:
          - pip install awscli
          - aws s3 sync dist/ s3://my-bucket/

Overriding the Default User

Specify a different user by UID:

image:
  name: atlassian/default-image:3
  run-as-user: 1000

Creating Custom Build Environments

To build your own Docker image for use as a build environment:

Install Docker locally
Create a Dockerfile with your required tools:

FROM node:18
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    awscli
WORKDIR /app

Build the image:

docker build -t mycompany/custom-build-env:1.0 .

Push to a registry:

docker push mycompany/custom-build-env:1.0

Reference it in your pipeline:

image: mycompany/custom-build-env:1.0
pipelines:
  default:
    - step:
        script:
          - npm install
          - python3 build.py

Best Practices

Use specific versions - Pin to exact versions rather than latest for reproducible builds
Keep images small - Smaller images download faster and use less storage
Use official images - When possible, use official images from Docker Hub
Cache image layers - Structure Dockerfiles to maximize layer caching
Security scan images - Regularly update base images to patch vulnerabilities

Next Steps

Learn about Service Containers to run databases
Set up Variables and Secrets for image credentials
Configure Caching to speed up builds

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