Use Docker images as build environments

Bitbucket Pipelines runs your builds in Docker containers. These containers run a Docker image that defines the build environment. You can use the default image provided by Bitbucket or get a custom one.

We support public and private Docker images including those hosted on Docker Hub, AWS, GCP, Azure and self-hosted registries accessible on the internet. (Bitbucket Pipelines cannot currently access Docker images that cannot be accessed via the internet.)

Default build environment

If you don't specify a Docker image to use as your build environment, Bitbucket Pipelines will use a default one that we have built with some common tools.

The default image is atlassian/default-image:latest. You can also specify the version:

nameplatformapplications available out-of-the-box



Ubuntu 14.04
  • wget
  • xvfb
  • curl
  • ssh
  • git: 1.9.1
  • mercurial: 2.8.2
  • java: 1.8u66
  • maven: 3.0.5
  • node: 4.2.1
  • npm: 2.14.7
  • nvm: 0.29.0
  • python: 2.7.6
  • gcc: 4.8.4
  • ant: 1.9.3



Ubuntu 16.04
  • wget
  • xvfb
  • curl
  • ssh
  • git: 2.7.4
  • mercurial: 3.7.3
  • java: Open-JDK 1.8u151
  • maven: 3.3.9
  • node: 8.9.4
  • npm: 5.6.0
  • nvm: 0.33.8
  • python: 2.7.12
  • gcc: 5.4.0
  • ant: 1.9.6

(lightbulb) Best practices tip: after you have Pipelines working, try to find a specific image you can use to not rely on our default image. We don't upgrade it very often, to maximise compatibility for customers who rely on it, and it includes many tools you might not need. This means you'll likely get bug fixes and faster builds from using your own, smaller build image.

Custom build environments

If the default environment does not exactly meet your needs, your first step should be to see if a public available image on Docker Hub will help. Here are some of the official images available on Docker Hub that we recommend and configure in Pipelines during setup:

To use these images or another public image on Docker Hub as your build image, see the guide for Using public build images below.

To use an existing Docker image from your own registry, see the guide for Using private build images below.

To build your own Docker images, see the guide for Creating a custom build environment below.

Using public build images

You can use existing public images hosted on Docker Hub, another registry, or in a self-hosted registry. You can only use images that can be be accessed via the internet. 

In the examples below:

  • The account name is the name of the account that owns the image.
  • The username, password, and email are your personal credentials for the registry.

Public images hosted on Docker Hub

You can find the name of the image by looking at the pull command listed (1) on the relevant dockerhub page:

If you don't specify the tag, Docker uses the latest version tag:

image: openjdk

Here's an example with both image version and account on Docker Hub:

image: account-name/openjdk:8

Public images hosted outside Docker Hub

If the image is not provided by Docker and is hosted in a private registry, the image name should include the URL:


Using private build images

To authenticate with a private Docker registry, including self-hosted registries and private images on Docker Hub, Amazon ECR and Google GCR, you need to provide a username and password as part of the image configuration in your YAML file. You can also optionally include an email address, which may be required by some providers.

Private images hosted by Docker Hub

You can use secure variables to configure username and password variables, then add them to the image YAML configuration as shown below:

  name: account-name/openjdk:8

Private images hosted by AWS ECR (EC2 Container Registry)

If the image is hosted by ECR, you can provide the access key and secret key via secure variables under an additional "aws" section in your YAML image configuration:

  name: <aws_account_id>.dkr.ecr.<region>
    access-key: $AWS_ACCESS_KEY
    secret-key: $AWS_SECRET_KEY

Private images hosted by Google Container Registry (GCR)

To pull an image from GCR, you need to configure a service account for Pipelines with "Viewer" access in your GCP admin console:

Download the generated JSON private key, and copy/paste it into a secure variable in Pipelines. The configured variable can then be used directly in the password field in your YAML image configuration as shown below:

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

Images hosted on other registries

To use another private registry, you must provide the registry URL in the image name, and username/password credentials as shown below:

  username: $USERNAME
  password: $PASSWORD
  email: $EMAIL

Pin images by digest

To ensure that an image cannot be modified, you can refer to an image by its hash or digest value. The digest is a cryptographic hash, that changes whenever the content of an image changes. Pinning the digest of an image is the surest way to guarantee that no changes can be introduced.

Use image digests

  name: ubuntu@sha256:a0ee7647e24c8494f1cf6b94f1a3cd127f423268293c25d924fbe18fd82db5a4

Find an image digest

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


Override the default user

An image's default user can be overridden by specifying a user UID as the run-as-user. The specified user UID must be an existing user in the image with a valid home directory.

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

Creating a custom build environment

You can build your own Docker file and use it as your build environment. This way, you can keep your build environment lightweight by only including the tools that you need in your build. 


Last modified on Apr 15, 2019

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.