Set environment variables

Give an app plain variables and secrets by reference, and roll the change out with or without a redeploy.

Last updated 18 November 2026View as Markdown

A variable is either a plain value or a reference to a secret from Secrets. A secret's value is decrypted at deployment and handed to the machine, never stored on the app. An app holds up to 1000 variables, each value at most 8192 characters. Replace app-id with the app's id and secret-id with a secret's id.

Prerequisites

  • Permission for deploy:ManageEnv on the app. To bind a secret, secrets:GetSecretValue on it; binding grants it to the deploy consumer. To redeploy in the same step, deploy:DeployApp.
  • In the console, also deploy:DescribeApp to open the app's page (without it the page is not found).

Set the variables

  1. Open the app's Environment tab.
  2. Choose Add variable.
  3. In the new row, enter the variable name.
  4. Choose Value and enter the value, or choose Secret and, under Choose a secret…, choose the secret.
  5. Choose Save environment, or Save & redeploy (shown only with deploy:DeployApp) to roll the change out at once.

Saving does not restart the app

The running container keeps the environment it started with. Save & redeploy, or "redeploy": true on any environment write, rolls the change out; without it, the panel shows Saved, not running. and what changed until someone redeploys. Choose Redeploy now on that banner, or:

dcloud deploy redeploy apply app-id --reason "New LOG_LEVEL"

The banner, and status in GET /deploy/api/apps/app-id/env, report the app as behind when the environment was saved after the live deployment started, or a bound secret (a database binding's included) changed since, including one synced from 1Password. An app with no live deployment is never reported as behind.

A redeploy (from an environment change, an import, a database binding, a credential rotation or Redeploy now) creates a deployment that runs exactly what the live deployment runs: the same image, or the same pinned compose file. Nothing is rebuilt: an app built from a repository reuses the live image by its digest, and is rebuilt from the same commit only when that image is no longer in its registry repository (the deployment's activity says which). A configuration change is never also a code change. An app with no live deployment yet has nothing to reuse: its redeploy builds or pulls the current source. A redeploy needs deploy:DeployApp as well as the write itself.

What the containers receive

The machine hands the variables to the container in a file, so a long list costs nothing at start. A plain value cannot contain a line break: it is refused with 400 "A value cannot contain a line break, so bind a secret for multi-line material". A secret's value with line breaks (a PEM key, a service-account JSON) reaches the container intact as an ordinary environment variable, so bring such a value in as a secret (op://…, or a secret created in Secrets). For a compose app, which services receive which variables is in Compose files.

Scheduled jobs get the environment as of the live deployment: a variable saved without redeploying reaches jobs when it reaches the app.

Result

After the redeploy, the app's containers start with the new environment. The Environment tab also lists Secrets this app uses: where each value comes from, and the version the app last read.

Did this page help you?