Document build secrets passed via environment variables

[basicdays]

One thing that I found that works for passing secrets into builds was by using environment variables instead of files. This is a lot easier for me to use, as this will allow me to define an environment variable value on a CI step instead of having to write things out to file first.

However I cannot find any documentation that this is a supported feature. The only things I can find show that defining a build secret also defines a source file. Is this actually a supported feature, or was this an accidental bug? If it is a supported feature, I would think this should be documented somewhere at least. The best candidate I can think of would be the buildx build page perhaps.

Here's a contrived example of how I'm using it:

FROM debian:bullseye-slim

RUN --mount=type=secret,id=SECRET_TOKEN \
	set -eu; \
	export SECRET_TOKEN="$(cat /run/secrets/SECRET_TOKEN)"; \
	echo ${SECRET_TOKEN:-"SECRET MISSING"};

SECRET_TOKEN=token docker buildx build \
	-t secret-image \
	--secret=id=SECRET_TOKEN \
	--progress plain \
	--no-cache \
	.

Output:

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile:
#1 transferring dockerfile: 220B done
#1 DONE 0.0s

#2 [internal] load .dockerignore
#2 transferring context: 2B done
#2 DONE 0.0s

#3 [internal] load metadata for docker.io/library/debian:bullseye-slim
#3 ...

#4 [auth] library/debian:pull token for registry-1.docker.io
#4 DONE 0.0s

#3 [internal] load metadata for docker.io/library/debian:bullseye-slim
#3 DONE 0.7s

#5 [1/2] FROM docker.io/library/debian:bullseye-slim@sha256:b0d53c872fd640c2af2608ba1e693cfc7dedea30abcd8f584b23d583ec6dadc7
#5 CACHED

#6 [2/2] RUN --mount=type=secret,id=SECRET_TOKEN        set -eu;        export SECRET_TOKEN="$(cat /run/secrets/SECRET_TOKEN)";         echo ${SECRET_TOKEN:-"SECRET MISSING"};
#6 0.239 token
#6 DONE 0.3s

#7 exporting to image
#7 exporting layers 0.0s done
#7 writing image sha256:ec36931c13d2e074576fd3ed8160072c2d6d7bdfd605fa85f0ada5cc11247bba 0.0s done
#7 naming to docker.io/library/secret-image done
#7 DONE 0.0s