# 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](manage-environments.md).

## 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](promote-a-secret.md).

## 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](quotas.md).

## Related

- [Manage environments](manage-environments.md)
- [Promote a secret](promote-a-secret.md)
- [Compare environments](compare-environments.md)
