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.

Add account-level build arguments

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

Using Secrets as Build Arguments

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:
To this:
RUN --mount=type=secret,id=API_TOKEN API_TOKEN=$(cat /run/secrets/API_TOKEN) \
  • (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 of API_TOKEN from the file location pointed to by API_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.

Add application-level build arguments

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