From efaf0c30f7f14fefd05ed9f75700e6be51067d2f Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Fri, 20 Mar 2026 10:37:12 +0000 Subject: [PATCH 1/3] Fix issue #24434: document secret mount behavior Assisted-By: docker-agent --- .../build/ci/github-actions/secrets.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md index 42f2d83ab69..ec65a9d8ac8 100644 --- a/content/manuals/build/ci/github-actions/secrets.md +++ b/content/manuals/build/ci/github-actions/secrets.md @@ -57,6 +57,46 @@ jobs: "github_token=${{ secrets.GITHUB_TOKEN }}" ``` +### How secrets appear in the build container + +When you use a secret mount, the secret is made available as a file inside the build container. +By default, secrets are mounted to `/run/secrets/`, where `` is the secret identifier +you specify in the `--mount` instruction. + +**File location and permissions:** + +- Default path: `/run/secrets/` (for example, `/run/secrets/github_token`) +- Custom path: Use the `target` option to specify a different location +- File permissions: Secrets are mounted with restricted permissions (typically mode 0400), + readable only by the user running the build step +- Content: The file contains the exact bytes of the secret value, including any newlines + +**Environment variable secrets:** + +When you use the `env` option in your secret mount (like `--mount=type=secret,id=github_token,env=GITHUB_TOKEN`), +the secret file content is automatically loaded into the specified environment variable. +This is useful when tools expect credentials via environment variables rather than files. + +**Example with custom target:** + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine +# Mount secret to a custom location +RUN --mount=type=secret,id=github_token,target=/tmp/token \ + cat /tmp/token +``` + +**Example reading secret file directly:** + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine +# Read from default location +RUN --mount=type=secret,id=github_token \ + cat /run/secrets/github_token +``` + ### Using secret files The `secret-files` input lets you mount existing files as secrets in your build. From cc9469622c487635e51c7c26a7c7f18768d1cf0f Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Fri, 20 Mar 2026 11:15:13 +0000 Subject: [PATCH 2/3] Fix security concern in secret mount examples - Replace insecure 'cat' examples that expose secrets with secure usage - Add cross-reference to main secrets documentation - Add warning about never outputting secret values directly - Fix line length issue (wrap long line) - Show proper examples using secrets with curl Addresses reviewer feedback on PR #24442 Assisted-By: docker-agent --- .../build/ci/github-actions/secrets.md | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md index ec65a9d8ac8..c206c04b1d0 100644 --- a/content/manuals/build/ci/github-actions/secrets.md +++ b/content/manuals/build/ci/github-actions/secrets.md @@ -63,17 +63,18 @@ When you use a secret mount, the secret is made available as a file inside the b By default, secrets are mounted to `/run/secrets/`, where `` is the secret identifier you specify in the `--mount` instruction. -**File location and permissions:** +For more details on secret mounts, file locations, and permissions, +see [Secret mounts](/manuals/build/building/secrets.md#secret-mounts). + +**File location:** - Default path: `/run/secrets/` (for example, `/run/secrets/github_token`) - Custom path: Use the `target` option to specify a different location -- File permissions: Secrets are mounted with restricted permissions (typically mode 0400), - readable only by the user running the build step -- Content: The file contains the exact bytes of the secret value, including any newlines **Environment variable secrets:** -When you use the `env` option in your secret mount (like `--mount=type=secret,id=github_token,env=GITHUB_TOKEN`), +When you use the `env` option in your secret mount +(like `--mount=type=secret,id=github_token,env=GITHUB_TOKEN`), the secret file content is automatically loaded into the specified environment variable. This is useful when tools expect credentials via environment variables rather than files. @@ -82,21 +83,26 @@ This is useful when tools expect credentials via environment variables rather th ```dockerfile # syntax=docker/dockerfile:1 FROM alpine -# Mount secret to a custom location +# Mount secret to a custom location and use it with curl RUN --mount=type=secret,id=github_token,target=/tmp/token \ - cat /tmp/token + curl -H "Authorization: token $(cat /tmp/token)" https://api.github.com/user ``` -**Example reading secret file directly:** +**Example using secret as environment variable:** ```dockerfile # syntax=docker/dockerfile:1 FROM alpine -# Read from default location -RUN --mount=type=secret,id=github_token \ - cat /run/secrets/github_token +# Load secret into environment variable +RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN \ + curl -H "Authorization: token ${GITHUB_TOKEN}" https://api.github.com/user ``` +> [!WARNING] +> Never use commands like `cat`, `echo`, or `printenv` to output secret values directly, +> as this would expose them in build logs and layer history. +> Always consume secrets within commands without displaying their values. + ### Using secret files The `secret-files` input lets you mount existing files as secrets in your build. From 292d43302d1348ffc82392005cda7a4f652d1adb Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Fri, 20 Mar 2026 11:43:37 +0000 Subject: [PATCH 3/3] Simplify secret mount explanation with cross-reference Replace detailed explanation of secret mount behavior with brief callout that cross-references the canonical Build secrets documentation. This avoids duplicating content that's already covered in detail at /manuals/build/building/secrets.md and keeps the GitHub Actions page focused on the GitHub Actions-specific usage patterns. Assisted-By: docker-agent --- .../build/ci/github-actions/secrets.md | 51 +++---------------- 1 file changed, 6 insertions(+), 45 deletions(-) diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md index c206c04b1d0..40c2c0ac330 100644 --- a/content/manuals/build/ci/github-actions/secrets.md +++ b/content/manuals/build/ci/github-actions/secrets.md @@ -57,51 +57,12 @@ jobs: "github_token=${{ secrets.GITHUB_TOKEN }}" ``` -### How secrets appear in the build container - -When you use a secret mount, the secret is made available as a file inside the build container. -By default, secrets are mounted to `/run/secrets/`, where `` is the secret identifier -you specify in the `--mount` instruction. - -For more details on secret mounts, file locations, and permissions, -see [Secret mounts](/manuals/build/building/secrets.md#secret-mounts). - -**File location:** - -- Default path: `/run/secrets/` (for example, `/run/secrets/github_token`) -- Custom path: Use the `target` option to specify a different location - -**Environment variable secrets:** - -When you use the `env` option in your secret mount -(like `--mount=type=secret,id=github_token,env=GITHUB_TOKEN`), -the secret file content is automatically loaded into the specified environment variable. -This is useful when tools expect credentials via environment variables rather than files. - -**Example with custom target:** - -```dockerfile -# syntax=docker/dockerfile:1 -FROM alpine -# Mount secret to a custom location and use it with curl -RUN --mount=type=secret,id=github_token,target=/tmp/token \ - curl -H "Authorization: token $(cat /tmp/token)" https://api.github.com/user -``` - -**Example using secret as environment variable:** - -```dockerfile -# syntax=docker/dockerfile:1 -FROM alpine -# Load secret into environment variable -RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN \ - curl -H "Authorization: token ${GITHUB_TOKEN}" https://api.github.com/user -``` - -> [!WARNING] -> Never use commands like `cat`, `echo`, or `printenv` to output secret values directly, -> as this would expose them in build logs and layer history. -> Always consume secrets within commands without displaying their values. +> [!NOTE] +> Secrets are mounted as files in the build container. +> By default, they're available at `/run/secrets/`. +> 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](/manuals/build/building/secrets.md). ### Using secret files