Environments

How one secret name holds a Default value and a value of its own per environment, and which one an app or a workflow gets.

Last updated 18 November 2026View as Markdown

Every secret name can have a Default value, and each environment can override it with a secret of the same name of its own. An organization starts with three environments, created the first time anything lists them: Development (dev), Staging (staging) and Production (prod), in that promotion order. You can add, rename, recolour and delete environments; see Manage environments.

What a lookup gets

Whatever reads a secret by name in an environment gets that environment's own secret, else the Default one. It never gets another environment's secret. With no environment, it gets the Default only.

Reader How its environment is chosen
An app The app's secrets environment, set on the app or with PUT /secrets/api/apps/{appId}/environment. null: Default only. It applies when a variable is bound by name, such as in a .env import.
A workflow job environment: <slug> on the job. Without it, Default only. A slug that names no environment stops the run.

An app's variable holds the secret it was bound to, not the name: changing the app's environment later does not re-point variables bound before. Setting an app's environment needs deploy:UpdateApp on the app. An unknown app or environment is 404.

The promotion order

Each environment has a position (Development 10, Staging 20, Production 30 to start with); a new one goes last unless you give a position. The order decides which environment is "earlier": Environments in the console marks a name that a later environment is missing while an earlier one has it, and offers to promote it. See Promote a secret.

Colours

Each environment shows a coloured dot beside its name: gray, blue, teal, green, amber, red or violet. Left unset (color: null), the colour is read from the slug's words, split at - and _: prod or production is red, staging or stage amber, dev or development blue, anything else gray. So eu-prod is red and product-demo is gray. The API returns both color (as set) and effectiveColor (what is shown).

Limits

  • An environment's slug cannot be changed. A workflow names the environment by it.
  • An environment that still holds secrets or apps cannot be deleted.
  • How many environments an organization may have is a quota; see Quotas.
Did this page help you?