Secrets and environment variables

How configuration reaches your code

Every service reads its settings from environment variables at start time. The platform builds that list from three places, in order: shared groups, values set on the service, and values linked from other resources such as databases. A later value replaces an earlier one with the same key, so a service can override a group without changing it for everyone.

Variables and secrets

Both are stored the same way, encrypted at rest, and injected into the service the same way. The difference is who can read them back.

Plain variables

Use plain variables for settings that are safe to show to anyone on the team: log levels, feature flags, public URLs. Their values appear in the dashboard and in the CLI output.

Secrets

Use secrets for anything that grants access: API tokens, signing keys, passwords. Once saved, a secret value is never shown again. You can replace it or delete it, and every change is written to the audit log.

Shared groups

A group is a named set of variables that several services use. Change a value in the group and every linked service picks it up on its next deploy.

• One group per concern, such as shared-config or payments
• Groups can be limited to some environments
• A service can link several groups

Environments and previews

Each environment has its own values. Production, staging, and preview environments never share secrets unless you link the same group to them. Preview environments copy the staging values by default, so a pull request never sees production credentials.

Rotating a secret

Rotation is a two-step change so nothing breaks in between:

1. Add the new value under a second key and deploy the code that reads it.
2. Remove the old key once nothing uses it.

envVars:
  - key: API_TOKEN_NEXT
    sync: false

Limits

A service can hold up to 500 variables, and a single value can be up to 32 KB. For larger files, such as certificates, store them as secret files and read them from disk.