From 629429af7900a81cd81d9f6b653981022a906ece Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 1 Feb 2024 14:00:18 +0100
Subject: [PATCH] docs: make the warning about build arguments

Make it clearer that people need to stop leaking their credentials by
putting them in build arguments.

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 frontend/dockerfile/docs/reference.md | 29 ++++++++++++++++-----------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/frontend/dockerfile/docs/reference.md b/frontend/dockerfile/docs/reference.md
index f7cb953c8938..5acd5138a79b 100644
--- a/frontend/dockerfile/docs/reference.md
+++ b/frontend/dockerfile/docs/reference.md
@@ -2031,8 +2031,23 @@ ARG <name>[=<default value>]
 
 The `ARG` instruction defines a variable that users can pass at build-time to
 the builder with the `docker build` command using the `--build-arg <varname>=<value>`
-flag. If a user specifies a build argument that was not
-defined in the Dockerfile, the build outputs a warning.
+flag.
+
+> **Warning**
+>
+> It isn't recommended to use build arguments for passing secrets such as
+> user credentials, API tokens, etc. Build arguments are visible in the
+> `docker history` command and in `max` mode provenance attestations,
+> which are attached to the image by default if you use the Buildx GitHub Actions
+> and your GitHub repository is public.
+>
+> Refer to the [`RUN --mount=type=secret`](#run---mounttypesecret) section to
+> learn about secure ways to use secrets when building images.
+{ .warning }
+
+
+If you specify a build argument that wasn't defined in the Dockerfile,
+the build outputs a warning.
 
 ```console
 [Warning] One or more build-args [foo] were not consumed.
@@ -2048,16 +2063,6 @@ ARG buildno
 # ...
 ```
 
-> **Warning**
->
-> It is not recommended to use build-time variables for passing secrets like
-> GitHub keys, user credentials etc. Build-time variable values are visible to
-> any user of the image with the `docker history` command.
->
-> Refer to the [`RUN --mount=type=secret`](#run---mounttypesecret) section to
-> learn about secure ways to use secrets when building images.
-{ .warning }
-
 ### Default values
 
 An `ARG` instruction can optionally include a default value: