From 94624206b6fdce50dcc74247d6a31ddd2901cf2a Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 5 Sep 2024 11:47:30 +0200
Subject: [PATCH] build: run mount secrets as env

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/manuals/build/building/secrets.md     | 43 +++++++++++++------
 content/manuals/build/cache/invalidation.md   |  6 +--
 .../build/ci/github-actions/secrets.md        |  3 +-
 3 files changed, 34 insertions(+), 18 deletions(-)

diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md
index 4e24146e084..76fab257078 100644
--- a/content/manuals/build/building/secrets.md
+++ b/content/manuals/build/building/secrets.md
@@ -16,16 +16,14 @@ 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](/reference/dockerfile.md#run---mounttypesecret) that
+Secret mounts expose secrets to the build containers, as files or environment
+variables. You can use secret mounts to pass sensitive information to your
+builds, such as API tokens, passwords, or SSH keys. You [mount the secrets to
+the `RUN` instructions](/reference/dockerfile.md#run---mounttypesecret) that
 need to access them, similar to how you would define a bind mount or cache
 mount.
 
-```dockerfile
-RUN --mount=type=secret,id=mytoken \
-    TOKEN=$(cat /run/secrets/mytoken) ...
-```
+### Passing secrets
 
 To pass a secret to a build, use the [`docker build --secret`
 flag](/reference/cli/docker/buildx/build.md#secret), or the
@@ -82,21 +80,40 @@ $ docker build --secret id=API_TOKEN .
 
 ### 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.
+By default, secrets are mounted as files located at `/run/secrets/<id>`. You
+can customize how the secrets get mounted in the build container using the
+`target` and `env` options for the `RUN --mount` flag in the Dockerfile.
 
-The following example mounts the secret to a `/root/.aws/credentials` file in
-the build container.
+The following example takes secret id `aws` and mounts it to `/run/secrets/aws`
+in the build container.
 
-```console
-$ docker build --secret id=aws,src=/root/.aws/credentials .
+```dockerfile
+RUN --mount=type=secret,id=aws \
+    AWS_SHARED_CREDENTIALS_FILE=/run/secrets/aws \
+    aws s3 cp ...
 ```
 
+To mount a secret as a file with a different name, use the `target` option in
+the `--mount` flag.
+
 ```dockerfile
 RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
     aws s3 cp ...
 ```
 
+To mount a secret as an environment variable instead of a file, use the
+`env` option in the `--mount` flag.
+
+```dockerfile
+RUN --mount=type=secret,id=aws-key-id,env=AWS_ACCESS_KEY_ID \
+    --mount=type=secret,id=aws-secret-key,env=AWS_SECRET_ACCESS_KEY \
+    --mount=type=secret,id=aws-session-token,env=AWS_SESSION_TOKEN \
+    aws s3 cp ...
+```
+
+It's possible to use the `target` and `env` options together to mount a secret
+as both a file and an environment variable.
+
 ## SSH mounts
 
 If the credential you want to use in your build is an SSH agent socket or key,
diff --git a/content/manuals/build/cache/invalidation.md b/content/manuals/build/cache/invalidation.md
index a81222a3de7..5274b4876ab 100644
--- a/content/manuals/build/cache/invalidation.md
+++ b/content/manuals/build/cache/invalidation.md
@@ -82,12 +82,12 @@ Build arguments do result in cache invalidation.
 ```dockerfile
 FROM alpine
 ARG CACHEBUST
-RUN --mount=type=secret,id=foo \
-    TOKEN=$(cat /run/secrets/foo) ...
+RUN --mount=type=secret,id=TOKEN,env=TOKEN \
+    some-command ...
 ```
 
 ```console
-$ TOKEN=verysecret docker build --secret id=foo,env=TOKEN --build-arg CACHEBUST=1 .
+$ TOKEN="tkn_pat123456" docker build --secret id=TOKEN --build-arg CACHEBUST=1 .
 ```
 
 Properties of secrets such as IDs and mount paths do participate in the cache
diff --git a/content/manuals/build/ci/github-actions/secrets.md b/content/manuals/build/ci/github-actions/secrets.md
index 4d08136f7a5..4931409414d 100644
--- a/content/manuals/build/ci/github-actions/secrets.md
+++ b/content/manuals/build/ci/github-actions/secrets.md
@@ -26,8 +26,7 @@ First, create a `Dockerfile` that uses the secret:
 ```dockerfile
 # syntax=docker/dockerfile:1
 FROM alpine
-RUN --mount=type=secret,id=github_token \
-  cat /run/secrets/github_token
+RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN ...
 ```
 
 In this example, the secret name is `github_token`. The following workflow