Environment variables and secrets

Environment variables

Open the app, then Configuration → Environment Variables.

• Individual lists the settings. Add one with a Key and a Value and choose Add; each row has actions to edit and delete it.
• Bulk Edit takes the settings in .env format, one KEY=value per line; choose Apply Changes.
• Upload .env reads a .env file. It replaces the settings you have.

Choose Save. Every setting becomes an environment variable in the app's container, and saving replaces the app's instances so that they start with the new values.

A key starts with a letter or underscore and contains only letters, digits and underscores. The platform refuses a value over 32 KiB, and settings over 256 KiB together.

A slot has its own settings — see Slot settings.

Caution

Settings are not secret. Everyone with apps/read on the app — the Reader, Apps Reader and Platform Reader roles among them — can read the values of the app's and its slots' settings through the API, and in View changes on the Revisions tab. Keep passwords, keys and connection strings with credentials in a vault and reference them as secrets.

Build variables

Some frameworks — Next.js and Vite among them — read settings when the app is built and put the values into the code they produce. Turn on Build variable for such a setting so that it is also passed to the image build.

• The portal flags a setting whose name starts with VITE_, NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, REACT_APP_, VUE_APP_ or EXPO_PUBLIC_ and is not marked.
• At most 32 settings can be build variables, and each must be one of the app's settings.
• Build variables are written in plain text into the build job, where anyone who can read the resource group's jobs or pods in the cluster sees them, and a framework that reads one puts its value in the code it produces. Never mark a secret; a secret reference cannot be marked.
• Marking or unmarking a setting, or changing the value of a marked one, rebuilds the app.

Build variables do nothing for an app that runs a container image, which is not built.

Secrets

A secret stays in its vault; the app holds a reference to it. Open the app, then Configuration → Secrets, and add a reference to each secret the app needs — the steps are in Secrets in apps and functions.

Important

The app reads its secrets from the file /secrets/env.json, a JSON object that maps each name you gave under Environment Variable Name to the secret's value. Nothing sets them as environment variables: your code has to read the file — see Read the values in your code.

• The file is written when an instance starts, by the app's managed identity. That identity needs the Secrets Reader role on the vault, and for an app you assign it yourself — see Give a workload access. Without it the app's instances do not start.
• The file lives in memory and is read-only; it is never written to disk.
• After a secret's value changes, restart or deploy the app to pick it up, and each of its slots too: a restart covers only the app or the slot it is made on.
• The app's slots get the same secret references as the app, and read the secrets with the app's managed identity. Code on a slot's branch therefore reads the app's secrets — see What a slot shares with the app.

The managed identity's variables

Every app has a managed identity, shown on its Overview. The app's container, and every slot's, gets the variables STACKSHIP_IDENTITY_RESOURCE_UID and STACKSHIP_IDENTITY_TOKEN_ENDPOINT, with which your code can get a token for the identity — see Use a managed identity in code. The identity starts with no access; give it roles as described in Give a managed identity a role.