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.
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.