Build arguments
Docker build arguments & static service environment variables
Build arguments are key:value pairs that will be used to initialize a build with either
docker-compose
or static service environment variables. A static service is any service that doesn't require a container. Visit our guide to static service deployment for more details.Build arguments can be global and used for all your applications, or specific to a single application.
Global build arguments can be kept in your Account Settings under the Builds tab. Secret environment variables that are only relevant to a single application can be added to App Settings in the "Advanced Settings" section so that they aren't exposed to other containers.
Navigate to Account Settings screen by clicking the sliders icon in the upper right. Select the Builds tab.

Build Arguments Setting
An example use-case for global build arguments is an API key for a static build.

Build Arguments Example
You can read about how secrets are referenced from SSM or Secrets Manager in the following link Referencing Cloud Secrets
Environment Variables and environment-specific variables are not accessible in the Docker Build step, so you need to use Build Arguments as this guide explains.
Regular build arguments in Docker using the
ARG=SOMEVAL
format are stored in the docker image and can be retrieved if someone has access to your image or repository. For private images, this may be not be a problem, except for cases where you store private keys or sensitive information that should not be exposed, even internally. Therefore, to access secrets in Docker builds safely, we recommend using the Docker secrets; but this will require a change to your Dockerfile to access the secret.- Enter your secret directly as a string (we store all values encrypted in the database for you), or preferably create or use an existing secret in one of the supported secrets managers. Secrets stored in the secrets managers cannot be retrieved from the UI, which adds a better layer of security over your secrets.
- Click the padlock icon to convert the secret or secret reference to a Docker secret (this will mount the value at a file location you can specify later).
- The Docker secret will be available with the same ID as the key you specified, and will be mounted under
/var/secrets/ID
in the file system. For example, in your Dockerfile change your build argument access code from something like this:
ARG API_TOKEN
RUN API_TOKEN=$API_TOKEN start_server.sh
To this:
RUN --mount=type=secret,id=API_TOKEN API_TOKEN=$(cat /run/secrets/API_TOKEN) \
start_server.sh
- (Optional) In some cases, the build arguments can be automatically read as an environment variable by some startup scripts by using the
_FILE
convention. In this case, the startup script will know to access the value ofAPI_TOKEN
from the file location pointed to byAPI_TOKEN_FILE
as shown in this documentation example from Docker. This only applies to certain conventions, so please check if this applies to your scenario.
Navigate to App Settings. Select Advanced Settings. Toggle open the "App-Level Build Args" section. The application specific build arguments will override the account-wide build argument settings.

Navigating to App-Level Build Args under Application Advanced Settings
Last modified 1mo ago