Skip to main content
Your build can read every environment variable of the you’re deploying, and none of them end up in the image. Automatic builds need no setup. Dockerfile builds need one extra line in each RUN step that uses them. This is safer than Docker’s ARG and ENV, which are saved in the image history where anyone with the image can read them.

​
Automatic builds

When the environment builds without a Dockerfile, every variable is set as an environment variable of the same name for your install and build commands, the way it would be in CI. Change a value and the next deployment rebuilds the steps that use it.

​
Dockerfile builds

In a Dockerfile build, your variables arrive as a .env file. Mount it in each RUN step that needs it:
Dockerfile
  • Declare ARG UNKEY_SECRETS_ID in every stage that mounts the file. Docker doesn’t carry ARG values across FROM lines.
  • set -a && . /run/secrets/.env && set +a loads the variables for that one RUN step only. The file isn’t saved in the layer.
  • Changing a variable reruns that step and every step after it in the stage. Steps before it stay cached.
The file uses standard .env syntax, one KEY=value per line. Values with spaces, quotes, $, or newlines are single-quoted, so PEM keys and JSON come through unchanged. If your framework reads .env files itself, point it at /run/secrets/.env and make sure its parser handles quoted multi-line values.

​
Troubleshooting

​
A build step keeps using an old value

Older Dockerfiles mount the secret with the fixed id env. That still builds, but changing a variable doesn’t rerun the step, so the old value can stay cached. Change the mount to id=${UNKEY_SECRETS_ID}.

​
Cloning a private repository or installing a private package fails

We fetch only the repository being built, with read-only access. A RUN git clone of another private repository, a private submodule, or a private package registry isn’t authenticated. Add the token it needs as an environment variable and use it in the step that needs it.

​
Next steps

Environment variables

Kinds, limits, import, and how values reach running instances.

Dockerfile builds

Build context, the runtime contract, and explained errors.
Last modified on September 29, 2026