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:
| name | platform | applications available out-of-the-box |
|---|---|---|
atlassian/default-image:1 atlassian/default-image:latest | Ubuntu 14.04 |
|
atlassian/default-image:2 RECOMMENDED | Ubuntu 16.04 |
|
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:
- PHP: https://hub.docker.com/_/php/
- JavaScript: https://hub.docker.com/_/node/
- Java (Maven): https://hub.docker.com/_/maven/
- Python: https://hub.docker.com/_/python/
- Go: https://hub.docker.com/_/golang/
- .NET Core: https://hub.docker.com/r/microsoft/dotnet/
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:
image: docker.someprovider.com/account-name/openjdk:8
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:
image:
name: account-name/openjdk:8
username: $DOCKER_HUB_USERNAME
password: $DOCKER_HUB_PASSWORD
email: $DOCKER_HUB_EMAILPrivate 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:
image:
name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/openjdk:8
aws:
access-key: $AWS_ACCESS_KEY
secret-key: $AWS_SECRET_KEYPrivate 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:
image:
name: <region>.gcr.io/<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:
image:
name: docker.your-company-name.com/account-name/openjdk:8
username: $USERNAME
password: $PASSWORD
email: $EMAILPin 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
image:
name: ubuntu@sha256:a0ee7647e24c8494f1cf6b94f1a3cd127f423268293c25d924fbe18fd82db5a4Find an image digest
> docker inspect --format='{{.RepoDigests}}' ubuntu
[ubuntu@sha256:a0ee7647e24c8494f1cf6b94f1a3cd127f423268293c25d924fbe18fd82db5a4]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.
image:
name: atlassian/default-image:2
run-as-user: 1000Creating 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.
Resources
- Install Docker locally: https://docs.docker.com/engine/installation/
- Build your own Docker image: https://docs.docker.com/engine/userguide/dockerimages/
- Publish your Docker image to Docker Hub: https://docs.docker.com/engine/userguide/dockerimages/#push-an-image-to-docker-hub
- Publish your Docker image to your self-hosted registry: https://docs.docker.com/engine/userguide/containers/dockerimages/#push-an-image-to-docker-hub