Text of docs.docker.com › build › ci › github-actions › secrets as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Using secrets with GitHub Actions | Docker Docs

Skip to content Search or ask Docker Search documentation Ask Docker Start a new chat Answers are generated based on the documentation. On this page: Docker Build A build secret is sensitive information, such as a password or API token, consumed as part of the build process. Docker Build supports two forms of secrets: Secret mounts add secrets as files in the build container (under /run/secrets by default). SSH mounts add SSH agent sockets or keys into the build container.

This page shows how to use secrets with GitHub Actions. For an introduction to secrets in general, see Build secrets . Secret mounts In the following example uses and exposes the GITHUB_TOKEN secret as provided by GitHub in your workflow. First, create a Dockerfile that uses the secret: # syntax=docker/dockerfile:1 FROM alpine RUN --mount = type = secret,id = github_token,env = GITHUB_TOKEN ... Pass secret values with GitHub Builder Pass secret values to Docker GitHub Builder using the build-secrets workflow secret.

Its value is a YAML mapping from secret IDs to values, rather than the action's id=value list: name : ci on : push : jobs : build : uses : docker/github-builder/.github/workflows/build.yml@v1 permissions : contents : read id-token : write with : output : image platforms : linux/amd64,linux/arm64 meta-images : user/app secrets : build-secrets : | github_token: ${{ toJSON(secrets.GITHUB_TOKEN) }} The Dockerfile consumes the github_token secret in the same way with either workflow. toJSON quotes the value for the YAML mapping.

For files, environment variables, or SSH agents prepared by earlier steps, use the individual-action examples below. The reusable build runs in separate jobs and doesn't share the caller's filesystem or SSH agent. Pass secret values with individual actions In this example, the secret name is github_token . The following workflow exposes this secret using the secrets input: name : ci on : push : jobs : docker : runs-on : ubuntu-latest steps : - name : Set up QEMU uses : docker/setup-qemu-action@v4 - name : Set up Docker Buildx uses : docker/setup-buildx-action@v4 - name : Build uses : docker/build-push-action@v7 with : platforms : linux/amd64,linux/arm64 tags : user/app:latest secrets : | "github_token=${{ secrets.GITHUB_TOKEN }}" Note Secrets are mounted as files in the build container.

By default, they're available at /run/secrets/<id> . You can also use the env option to load a secret into an environment variable, or the target option to customize the mount path. For details on secret mounts, see Build secrets . Secret sources The docker/build-push-action inputs for secret mounts define where the secret value comes from. The Dockerfile RUN --mount=type=secret options define how the build step consumes the secret.

Action input Source Equivalent Buildx option secrets: MY_SECRET=value Inline value from the workflow --secret id=MY_SECRET,src=<temp-file> secret-envs: MY_SECRET=MY_ENV_VAR Environment variable on the runner --secret id=MY_SECRET,env=MY_ENV_VAR secret-files: MY_SECRET=./secret.txt File on the runner --secret id=MY_SECRET,src=./secret.txt For example, RUN --mount=type=secret,id=MY_SECRET mounts the secret as a file at /run/secrets/MY_SECRET .

To expose the same secret as an environment variable for a RUN instruction, use the env option in the Dockerfile: RUN --mount=type=secret,id=MY_SECRET,env=MY_SECRET . Using environment variables as secret sources The secret-envs input reads secrets from environment variables on the GitHub Actions runner. Use it when a previous workflow step sets an environment variable, or when you want to map a runner environment variable to a different secret ID for the build. name : ci on : push : jobs : docker : runs-on : ubuntu-latest steps : - name : Checkout uses : actions/checkout@v6 - name : Set up Docker Buildx uses : docker/setup-buildx-action@v4 - name : Build uses : docker/build-push-action@v7 env : SENTRY_AUTH_TOKEN : ${{ secrets.SENTRY_AUTH_TOKEN }} with : context : . secret-envs : | sentry_token=SENTRY_AUTH_TOKEN tags : user/app:latest In your Dockerfile, mount the secret and expose it as an environment variable for the command that needs it: # syntax=docker/dockerfile:1 FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . .

RUN --mount = type = secret,id = sentry_token,env = SENTRY_AUTH_TOKEN \ npm run build Using secret files The secret-files input lets you mount existing files as secrets in your build. This is useful when you need to use credential files that are generated during your workflow, or when you need to mount configuration files like .npmrc or .pypirc that are already in the expected format. The key difference between secrets , secret-envs , and secret-files : secrets : Pass secret values as strings from the workflow. secret-envs : Read secret values from environment variables on the runner. secret-files : Mount existing files from the runner's filesystem.

Example: Using .npmrc for private npm packages If your build needs to install packages from a private npm registry, you can create an .npmrc file and mount it as a secret: name : ci on : push : jobs : docker : runs-on : ubuntu-latest steps : - name : Checkout uses : actions/checkout@v6 - name : Set up Docker Buildx uses : docker/setup-buildx-action@v4 - name : Create .npmrc file run : | echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc - name : Build uses : docker/build-push-action@v7 with : context : . secret-files : | npmrc=./.npmrc tags : user/app:latest In your Dockerfile, mount the secret file to the expected location: # syntax=docker/dockerfile:1 FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN --mount = type = secret,id = npmrc,target = /root/.npmrc \ npm ci COPY . .

RUN npm run build If a RUN instruction uses a non-root user, set uid , gid , or mode on the secret mount so the user can read the mounted file: RUN --mount = type = secret,id = npmrc,target = /home/node/.npmrc,uid = 1000,gid = 1000 \ npm ci Example: Using dynamically generated credentials You can generate credential files from multiple secrets and mount them: name : ci on : push : jobs : docker : runs-on : ubuntu-latest steps : - name : Checkout uses : actions/checkout@v6 - name : Set up Docker Buildx uses : docker/setup-buildx-action@v4 - name : Create credentials file run : | cat <<EOF > aws-credentials [default] aws_access_key_id = ${{ secrets.AWS_ACCESS_KEY_ID }} aws_secret_access_key = ${{ secrets.AWS_SECRET_ACCESS_KEY }} EOF - name : Build uses : docker/build-push-action@v7 with : context : . secret-files : | aws=./aws-credentials tags : user/app:latest In your Dockerfile: # syntax=docker/dockerfile:1 FROM alpine RUN apk add --no-cache aws-cli RUN --mount = type = secret,id = aws,target = /root/.aws/credentials \ aws s3 cp s3://my-private-bucket/data.tar.gz /tmp/ Multi-line secrets If you're using GitHub secrets with individual actions, place multi-line key-value pairs between quotes: secrets : | "MYSECRET=${{ secrets.GPG_KEY }}" GIT_AUTH_TOKEN=abcdefghi,jklmno=0123456789 "MYSECRET=aaaaaaaa bbbbbbb ccccccccc" FOO=bar "EMPTYLINE=aaaa bbbb ccc" "JSON_SECRET={""key1"":""value1"",""key2"":""value2""}" Key Value MYSECRET *********************** GIT_AUTH_TOKEN abcdefghi,jklmno=0123456789 MYSECRET aaaaaaaa\nbbbbbbb\nccccccccc FOO bar EMPTYLINE aaaa\n\nbbbb\nccc JSON_SECRET {"key1":"value1","key2":"value2"} Note Double escapes are needed for quote signs.

SSH mounts SSH mounts let you authenticate with SSH servers. For example to perform a git clone , or to fetch application packages from a private repository. The following Dockerfile example uses an SSH mount to fetch Go modules from a private GitHub repository. # syntax=docker/dockerfile:1 ARG GO_VERSION = "1.26" FROM golang:${GO_VERSION}-alpine AS base ENV CGO_ENABLED = 0 ENV GOPRIVATE = "github.com/foo/*" RUN apk add --no-cache file git rsync openssh-client RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts WORKDIR /src FROM base AS vend

The rest of this page is on the live site.