Build secrets

A build secret is any piece of sensitive information, such as a password or API token, consumed as part of your application's build process.

Build arguments and environment variables are inappropriate for passing secrets to your build, because they persist in the final image. Instead, should use secret mounts or SSH mounts, which expose secrets to your builds securely.

Secret mounts

Secret mounts expose secrets to the build containers as files. You mount the secrets to the RUN instructions that need to access them, similar to how you would define a bind mount or cache mount.

RUN --mount=type=secret,id=mytoken \
    TOKEN=$(cat /run/secrets/mytoken) ...

To pass a secret to a build, use the docker build --secret flag, or the equivalent options for Bake.

$ docker build --secret id=mytoken,src=$HOME/.aws/credentials .

variable "HOME" {
  default = null
}

target "default" {
  secret = [
    "id=mytoken,src=${HOME}/.aws/credentials"
  ]
}

Sources

The source of a secret can be either a file or an environment variable. When you use the CLI or Bake, the type can be detected automatically. You can also specify it explicitly with type=file or type=env.

The following example mounts the environment variable KUBECONFIG to secret ID kube.

$ docker build --secret id=kube,env=KUBECONFIG .

The following example maps an environment variable directly to a secret ID.

$ docker build --secret env=KUBECONFIG .

Target

By default, secrets are mounted to /run/secrets/<id>. You can customize the mount point in the build container using the target option in the Dockerfile.

The following example mounts the secret to a /root/.aws/credentials file in the build container.

$ docker build --secret id=aws,src=/root/.aws/credentials .

RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws s3 cp ...

SSH mounts

If the credential you want to use in your build is an SSH agent socket or key, you can use the SSH mount instead of a secret mount. Cloning private Git repositories is a common use case for SSH mounts.

The following example clones a private GitHub repository using a Dockerfile SSH mount.

# syntax=docker/dockerfile:1
FROM alpine
ADD git@github.com:me/myprivaterepo.git /src/

To pass an SSH socket the build, you use the docker build --ssh flag, or equivalent options for Bake.

$ docker buildx build --ssh default .