Docker image options
Bitbucket Pipelines runs most builds in Docker containers (excluding builds on theLinux shell, macOS, and Windows runners). Theimage 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, seeUse 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 forservice 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 ‘Recommended’ default image 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.
Theimage option can be used to specify public images or private images. For publicly-accessible Docker images, you can useimage as a single-line option such as:
image: atlassian/default-image:IMAGE_TAG_HEREFor private images, use the block version of theimage option, such as:
image: name: us-east1-docker.pkg.dev/my-project/my-repo/test-image:latest username: $DOCKER_REGISTRY_USERNAME password: $DOCKER_REGISTRY_PASSWORDFor information about using and creating images, see Use Docker images as build environments.
Property —image
Required — No
Data type — Either:
string
block of new-line separated key-value pairs (YAML spec - Block Mapping)
Default value —atlassian/default-image:latest (For details, seeUse Docker images as build environments — Default build environment)
Allowed parent properties —services,step, or the YAML root (image can be a top-level property)
Allowed child properties —name,username,password,aws, andrun-as-user
Example — using the image option to set the image for the whole pipeline
image: bash:latest # https://hub.docker.com/_/bashpipelines: default: - step: name: Hello world example script: - echo "Hello, World!"Example — using the image option to use a different image on a pipeline step
image: bash:latest # https://hub.docker.com/_/bashpipelines: 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
image: public.ecr.aws/docker/library/python:slim # https://gallery.ecr.aws/docker/library/pythonpipelines: 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).
image: name: my-docker-hub-account/my-docker-image:latest username: $DOCKER_HUB_USERNAME password: $DOCKER_HUB_PASSWORD run-as-user: 1001pipelines: 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).
image: name: us-east1-docker.pkg.dev/my-project/my-repo/test-image:latest username: $DOCKER_REGISTRY_USERNAME password: $DOCKER_REGISTRY_PASSWORDpipelines: default: - step: name: Hello world example script: - echo "Hello, World!"Name
The imagename 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, seeUse Docker images as build environments — Using private build images.
Property —name
Required — No
Data type — String
Allowed parent properties —image
Example — using name to pull a public DockerHub image
image: name: my-account/bash:latestpipelines: default: - step: script: - echo "Hello, World!"Example — using name to override the image used for a step
image: my/bash:ltspipelines: default: - step: image: name: my/bash:latest script: - echo "Hello, World!"Example — using name to set the image used for a service container
definitions: services: my-service: image: name: my/bash:latestpipelines: default: - step: services: - my-service script: - echo "Hello, World!"Username
The imageusername property, when used with thepasswordproperty, provides Bitbucket Pipelines with access to private Docker images. For details on configuring access to private Docker images, seeUse 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, seeVariables and secrets — User-defined variables.
Property —username
Required — No
Data type — String
Allowed parent properties —image
Example — using username and password to pull a private Docker image
image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORDpipelines: default: - step: script: - echo "Hello, World!"Example — using username and password to override the build image used for a step with a private image
image: my/bash:ltspipelines: 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
definitions: services: my-service: image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORDpipelines: default: - step: services: - my-service script: - echo "Hello, World!"Password
The imagepassword property, when used with theusernameproperty, provides Bitbucket Pipelines with access to private Docker images. For details on configuring access to private Docker images, seeUse 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, seeVariables and secrets — User-defined variables.
Property —password
Required — No
Data type — String
Allowed parent properties —image
Example — using password and username to pull a private Docker image
image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORDpipelines: default: - step: script: - echo "Hello, World!"Example — using password and username to override the build image used for a step with a private image
image: my/bash:ltspipelines: 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
definitions: services: my-service: image: name: my/bash:latest username: $CONTAINER_REGISTRY_USERNAME password: $CONTAINER_REGISTRY_PASSWORDpipelines: 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 therun-as-user property. The specified user UID needs to be a user already defined in the image and should have a valid home directory.
Property —run-as-user
Required — No
Data type — Integer
Allowed values — UID of any user on the image
Default value —0 (root user)
Allowed parent properties —image
Example — using run-as-user to run pipeline steps as a specific user (UID = 1000)
image: name: my/bash:latest run-as-user: 1000pipelines: default: - step: script: - echo "Hello, World!"Example — using run-as-user to run a pipeline step as a specific user (UID = 1000)
image: my/bash:ltspipelines: 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)
definitions: services: my-service: image: name: my/bash:latest run-as-user: 1000pipelines: default: - step: services: - my-service script: - echo "Hello, World!"AWS
The imageaws properties allow pipelines to use private images hosted in anAmazon Elastic Container Registry (AWS ECR). Theaws property supports two authentication methods:
using an access key and a secret key (
access-keyandsecret-key)using an OpenID Connect (OIDC) role (
oidc-role).
For details, seePrivate 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, seeVariables and secrets — User-defined variables.
Property —aws
Required — No
Data type — Block of new-line separated key-value pairs (YAML spec - Block Mapping)
Allowed parent properties —image
Allowed child properties — Requires either:
Example — using aws, access-key, and secret-key to pull a private image from AWS ECR
image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEYpipelines: default: - step: oidc: true script: - echo "Hello, World!"Example — using aws and oidc-role to pull a private image from AWS ECR
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: oidc: true 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 theaccess-key andsecret-key options.
Access-key
Theawsaccess-key property, when used with thesecret-key property, provides Bitbucket Pipelines with access to private Docker images hosted in anAmazon Elastic Container Registry (AWS ECR). For details, seePrivate 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, seeVariables and secrets — User-defined variables.
Property —access-key
Required — No
Data type — String
Allowed parent properties —aws
Example — using aws, access-key, and secret-key to pull a private image from AWS ECR
image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEYpipelines: 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
image: my/bash:ltspipelines: 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
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_KEYpipelines: default: - step: services: - my-service script: - echo "Hello, World!"Secret-key
Theawssecret-key property, when used with theaccess-key property, provides Bitbucket Pipelines with access to private Docker images hosted in anAmazon Elastic Container Registry (AWS ECR). For details, seePrivate 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, seeVariables and secrets — User-defined variables.
Property —secret-key
Required — No
Data type — String
Allowed parent properties —aws
Example — using aws, secret-key, and access-key to pull a private image from AWS ECR
image: name: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/bash:latest aws: access-key: $AWS_ACCESS_KEY secret-key: $AWS_SECRET_KEYpipelines: 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
image: my/bash:ltspipelines: 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
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_KEYpipelines: default: - step: services: - my-service script: - echo "Hello, World!"OIDC-roles
Theawsoidc-role property provides Bitbucket Pipelines with access to private Docker images hosted in anAmazon Elastic Container Registry (AWS ECR). For details, seeUse AWS ECR images in Pipelines with OpenID Connect.
Property —oidc-role
Required — No
Data type — String
Allowed parent properties —aws
Example — using aws and oidc-role to pull a private image from AWS ECR
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: oidc: true script: - echo "Hello, World!"Example — using aws and oidc-role to pull a private image from AWS ECR for a single step
image: my/bash:ltspipelines: default: - step: oidc: true 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
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: oidc: true services: - my-service script: - echo "Hello, World!"Was this helpful?
- Bitbucket Pipelines configuration reference
- Git clone behavior
- Cache, service container, and export pipelines definitions
Docker image options
- Pipeline start conditions
- Parallel step options