Docker image options

Bitbucket Pipelines runs most builds in Docker containers (excluding builds on the Linux shell, macOS, and Windows runners). The image options allow you to use custom Docker images as build environments. Most of these options relate to pulling images from private Docker registries.

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 can't currently access Docker images that can't be accessed through the internet.

For details on using custom Docker images with Bitbucket Pipelines, see Use Docker images as build environments.

Docker Image options

The following options can be used to set the Docker image for pipeline steps globally within a bitbucket-pipelines.yml, for individual steps, or for service containers:

Image

Bitbucket Pipelines uses Docker containers when it runs your builds either:

  • On Bitbucket Cloud’s infrastructure, or

  • On a Linux Docker self-hosted runner.

You can use the default image (atlassian/default-image:latest) provided by Bitbucket or define a custom image. You can specify any public or private Docker image that isn't hosted on a private network. The image used can be set at the global level, and overridden for individual steps.

The image option can be used to specify public images or private images. For publicly-accessible Docker images, you can use image as a single-line option such as:

1 image: atlassian/default-image:latest

For private images, use the block version of the image option, such as:

1 2 3 4 image: name: us-east1-docker.pkg.dev/my-project/my-repo/test-image:latest username: $DOCKER_REGISTRY_USERNAME password: $DOCKER_REGISTRY_PASSWORD

For information about using and creating images, see Use Docker images as build environments.

Propertyimage

Required — No

Data type — Either:

Default valueatlassian/default-image:latest (For details, see Use Docker images as build environments — Default build environment)

Allowed parent propertiesservices, step, or the YAML root (image can be a top-level property)

Allowed child propertiesname, username, password, aws, and run-as-user

Example — using the image option to set the image for the whole pipeline

1 2 3 4 5 6 7 8 image: bash:latest # https://hub.docker.com/_/bash pipelines: default: - step: name: Hello world example script: - echo "Hello, World!"

Example — using the image option to use a different image on a pipeline step

1 2 3 4 5 6 7 8 9 10 11 12 13 image: bash:latest # https://hub.docker.com/_/bash pipelines: default: - step: name: Step using the Bash image script: - bash --version - step: name: Step using the default Bitbucket Pipelines image image: atlassian/default-image:latest # https://hub.docker.com/r/atlassian/default-image/ script: - echo "Hello, World from the default Pipelines image"

Example — using a public image hosted outside Docker Hub

1 2 3 4 5 6 7 8 9 10 11 12 13 image: public.ecr.aws/docker/library/python:slim # https://gallery.ecr.aws/docker/library/python pipelines: default: - step: name: Step using the Python image script: - echo "Python version:" $(python --version) - step: name: Step using the default Bitbucket Pipelines image image: atlassian/default-image:latest # https://hub.docker.com/r/atlassian/default-image/ script: - echo "Node.js version:" $(node -v)

Example — using private images

This example shows how to pull a private image from Docker Hub (actual use may vary depending on your Docker Hub authentication method).

1 2 3 4 5 6 7 8 9 10 11 12 image: name: my-docker-hub-account/my-docker-image:latest username: $DOCKER_HUB_USERNAME password: $DOCKER_HUB_PASSWORD run-as-user: 1001 pipelines: default: - step: name: Hello world example script: - echo "Hello, World!"

This example shows how to pull a private image from a non-Docker Hub image repository (in this case, Google Artifact Registry).

1 2 3 4 5 6 7 8 9 10 11 image: name: us-east1-docker.pkg.dev/my-project/my-repo/test-image:latest username: $DOCKER_REGISTRY_USERNAME password: $DOCKER_REGISTRY_PASSWORD pipelines: default: - step: name: Hello world example script: - echo "Hello, World!"

Name

The image name property is used to specify which Docker image to use when you are using a private image and login credentials are required. For details on configuring access to private Docker images, see Use Docker images as build environments — Using private build images.

Propertyname

Required — No

Data type — String

Allowed parent propertiesimage

Example — using name to pull a public DockerHub image

1 2 3 4 5 6 7 8 image: name: my-account/bash:latest pipelines: default: - step: script: - echo "Hello, World!"

Example — using name to override the image used for a step

1 2 3 4 5 6 7 8 9 image: my/bash:lts pipelines: default: - step: image: name: my/bash:latest script: - echo "Hello, World!"

Example — using name to set the image used for a service container

1 2 3 4 5 6 7 8 9 10 11 12 13 definitions: services: my-service: image: name: my/bash:latest pipelines: default: - step: services: - my-service script: - echo "Hello, World!"

Username

The image username property, when used with the password property, provides Bitbucket Pipelines with access to private Docker images. For details on configuring access to private Docker images, see Use Docker images as build environments — Using private build images.

Secrets and login credentials should be stored as user-defined pipeline variables to avoid being leaked. For details, see Variables and secrets — User-defined variables.

Propertyusername

Required — No

Data type — String

Allowed parent propertiesimage

Example — using username and password to pull a private Docker image

1 2 3 4 5 6 7 8 9 10 image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORD pipelines: default: - step: script: - echo "Hello, World!"

Example — using username and password to override the build image used for a step with a private image

1 2 3 4 5 6 7 8 9 10 11 image: my/bash:lts pipelines: default: - step: image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORD script: - echo "Hello, World!"

Example — using username and password to define a service container using a private image

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 definitions: services: my-service: image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORD pipelines: default: - step: services: - my-service script: - echo "Hello, World!"

Password

The image password property, when used with the username property, provides Bitbucket Pipelines with access to private Docker images. For details on configuring access to private Docker images, see Use Docker images as build environments — Using private build images.

Secrets and login credentials should be stored as user-defined pipeline variables to avoid being leaked. For details, see Variables and secrets — User-defined variables.

Propertypassword

Required — No

Data type — String

Allowed parent propertiesimage

Example — using password and username to pull a private Docker image

1 2 3 4 5 6 7 8 9 10 image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORD pipelines: default: - step: script: - echo "Hello, World!"

Example — using password and username to override the build image used for a step with a private image

1 2 3 4 5 6 7 8 9 10 11 image: my/bash:lts pipelines: default: - step: image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORD script: - echo "Hello, World!"

Example — using password and username to define a service container using a private image

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 definitions: services: my-service: image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORD pipelines: default: - step: services: - my-service script: - echo "Hello, World!"

Run as user

An image's default user can be overridden by specifying a user UID with the run-as-user property. The specified user UID needs to be a user already defined in the image and should have a valid home directory.

Propertyrun-as-user

Required — No

Data type — Integer

Allowed values — UID of any user on the image

Default value0 (root user)

Allowed parent propertiesimage

Example — using run-as-user to run pipeline steps as a specific user (UID = 1000)

1 2 3 4 5 6 7 8 9 image: name: my/bash:latest run-as-user: 1000 pipelines: default: - step: script: - echo "Hello, World!"

Example — using run-as-user to run a pipeline step as a specific user (UID = 1000)

1 2 3 4 5 6 7 8 9 10 image: my/bash:lts pipelines: default: - step: image: name: my/bash:lts run-as-user: 1000 script: - echo "Hello, World!"

Example — using run-as-user to run a service container as a specific user (UID = 1000)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 definitions: services: my-service: image: name: my/bash:latest run-as-user: 1000 pipelines: default: - step: services: - my-service script: - echo "Hello, World!"

AWS

The image aws properties allow pipelines to use private images hosted in an Amazon Elastic Container Registry (AWS ECR). The aws property supports two authentication methods:

  • using an access key and a secret key (access-key and secret-key)

  • using an OpenID Connect (OIDC) role (oidc-role).

For details, see Private images hosted by AWS ECR (EC2 Container Registry).

Secrets and login credentials should be stored as user-defined pipeline variables to avoid being leaked. For details, see Variables and secrets — User-defined variables.

Propertyaws

Required — No

Data type — Block of new-line separated key-value pairs (YAML spec - Block Mapping)

Allowed parent propertiesimage

Allowed child properties — Requires either:

Example — using aws, access-key, and secret-key to pull a private image from AWS ECR

1 2 3 4 5 6 7 8 9 10 11 image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEY pipelines: default: - step: script: - echo "Hello, World!"

Example — using aws and oidc-role to pull a private image from AWS ECR

1 2 3 4 5 6 7 8 9 10 image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: oidc-role: arn:aws:iam::<aws_account_id>:role/<your_role_name> pipelines: default: - step: script: - echo "Hello, World!"

Access-key and Secret-key

When using private images from an Amazon Elastic Container Registry (AWS ECR), you will need to use the access-key and secret-key options.

Access-key

The aws access-key property, when used with the secret-key property, provides Bitbucket Pipelines with access to private Docker images hosted in an Amazon Elastic Container Registry (AWS ECR). For details, see Private images hosted by AWS ECR (EC2 Container Registry).

Secrets and login credentials should be stored as user-defined pipeline variables to avoid being leaked. For details, see Variables and secrets — User-defined variables.

Propertyaccess-key

Required — No

Data type — String

Allowed parent propertiesaws

Example — using aws, access-key, and secret-key to pull a private image from AWS ECR
1 2 3 4 5 6 7 8 9 10 11 image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEY pipelines: default: - step: script: - echo "Hello, World!"
Example — using aws, access-key, and secret-key to pull a private image from AWS ECR for a single step
1 2 3 4 5 6 7 8 9 10 11 12 image: my/bash:lts pipelines: default: - step: image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEY script: - echo "Hello, World!"
Example — using aws, access-key, and secret-key to use a private image from AWS ECR as a service container
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 definitions: services: my-service: image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEY pipelines: default: - step: services: - my-service script: - echo "Hello, World!"
Secret-key

The aws secret-key property, when used with the access-key property, provides Bitbucket Pipelines with access to private Docker images hosted in an Amazon Elastic Container Registry (AWS ECR). For details, see Private images hosted by AWS ECR (EC2 Container Registry).

Secrets and login credentials should be stored as user-defined pipeline variables to avoid being leaked. For details, see Variables and secrets — User-defined variables.

Propertysecret-key

Required — No

Data type — String

Allowed parent propertiesaws

Example — using aws, secret-key, and access-key to pull a private image from AWS ECR
1 2 3 4 5 6 7 8 9 10 11 image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEY pipelines: default: - step: script: - echo "Hello, World!"
Example — using aws, secret-key, and access-key to pull a private image from AWS ECR for a single step
1 2 3 4 5 6 7 8 9 10 11 12 image: my/bash:lts pipelines: default: - step: image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEY script: - echo "Hello, World!"
Example — using aws, secret-key, and access-key to use a private image from AWS ECR as a service container
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 definitions: services: my-service: image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEY pipelines: default: - step: services: - my-service script: - echo "Hello, World!"

OIDC-roles

The aws oidc-role property provides Bitbucket Pipelines with access to private Docker images hosted in an Amazon Elastic Container Registry (AWS ECR). For details, see Use AWS ECR images in Pipelines with OpenID Connect.

Propertyoidc-role

Required — No

Data type — String

Allowed parent propertiesaws

Example — using aws and oidc-role to pull a private image from AWS ECR
1 2 3 4 5 6 7 8 9 10 image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: oidc-role: arn:aws:iam::<aws_account_id>:role/<your_role_name> pipelines: default: - step: script: - echo "Hello, World!"
Example — using aws and oidc-role to pull a private image from AWS ECR for a single step
1 2 3 4 5 6 7 8 9 10 11 image: my/bash:lts pipelines: default: - step: image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: oidc-role: arn:aws:iam::<aws_account_id>:role/<your_role_name> script: - echo "Hello, World!"
Example — using aws and oidc-role to use a private image from AWS ECR as a service container
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 definitions: services: my-service: image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: oidc-role: arn:aws:iam::<aws_account_id>:role/<your_role_name> pipelines: default: - step: services: - my-service script: - echo "Hello, World!"

Still need help?

The Atlassian Community is here for you.