Published in


Atlassian BitBucket announces support for Docker BuildKit

Atlassian BitBucket has announced the support for Docker BuildKit in Bitbucket Pipelines. This was one of the top-voted features for Bitbucket Pipelines. One can now build Docker images with the BuildKit utility.

With BuildKit one can take advantage of the various features it provides like:

  • Performance: BuildKit uses parallelism and caching internally to build images faster
  • Secrets: Mount secrets and build images safely
  • Cache: Mount caches to save re-downloading all external dependencies every time
  • SSH: Mount SSH Keys to build images

Configuring your bitbucket-pipelines.yaml

BuildKit is now available with the Docker Daemon service. It is not enabled by default and can be enabled by setting the environment variable DOCKER_BUILDKIT=1 in the pipelines configuration.


  • Use multi-stage builds to utilise parallelism.
  • Caching is not shared across different builds and it’s limited to the build running on the same docker node where the build runs.
  • With BuildKit, secrets can be mounted securely as shown above.
  • For restrictions and limitations please refer to the restrictions section of our support documentation.

Enable Docker BuildKit

To use Docker BuildKit in a Bitbucket Pipeline, set the DOCKER_BUILDKIT=1 environment variable in the pipeline configuration (bitbucket-pipelines.yml).


Docker BuildKit restrictions

To protect the security of our users, the following Docker BuildKit features have been disabled in addition to the features listed in Running Docker commands:

  • multi-architecture builds
  • the — platform option (such as docker run — platform linux/arm/v7)

The following Dockerfile RUN directive options, also known as Dockerfile frontend syntaxes, have been disabled:

  • RUN — mount=type=ssh — To access your Bitbucket Pipelines SSH keys, use the — ssh option, such as: — ssh default=/opt/atlassian/pipelines/agent/ssh/id_rsa
  • RUN — network=host
  • RUN — security=insecure

Docker BuildKit caching limitations

The predefined docker cache used for caching the layers produced during Docker Build operations does not cache layers produced when using BuildKit.

The RUN — mount=type=cache Docker frontend syntax will only retain the cache until the pipeline step is complete; it will not be available for other steps in the pipeline or new pipeline runs.

If Docker BuildKit is enabled and the build layers need to be cached, we recommend using the Docker Build — cache-from option. This allows one or more tagged images stored in an external image registry to be used as a cache source. This methods also avoids the 1GB size limit of the predefined docker cache.


Where — cache-from $IMAGE:latest points to the previous successful deployment stored on an external registry, such as Docker Hub. For information about using the Docker build — cache-from option, visit: Docker docs — Specifying external cache sources.

Using secrets and secure variables with Docker BuildKit

Do not pass secrets or secure variables (such as passwords and API keys) to BuildKit using the docker build — build-arg option. This will cause the secret to be included in the resulting Docker image and the Pipeline logs.

Docker BuildKit includes secret handling; helping to keep your passwords, API keys, and other sensitive information out of the Docker images you generate. To use BuildKit secrets, use the — secret Docker Build option, and the — mount=type=secret BuildKit frontend syntax.

The following examples show how to use BuildKit secrets with:

Troubleshooting Docker BuildKit

If you are experiencing issues Docker build issues due to Docker BuildKit, you can disable BuildKit by setting DOCKER_BUILDKIT=0 before the docker command.

Such as:


  1. Enabling Docker BuildKit in BitBucket
  2. Build images with BuildKit

We are here to make the community stronger by sharing our knowledge. Follow us to stay updated on the latest and greatest in the web & mobile tech world.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store