Environment variables
This page covers build-time environment variables: adding them, when they apply, and — most importantly — why you must not put secrets in them.
Prerequisite: a project.
Not for secrets
Environment variables are baked into your build and may appear in your published site. Anyone who views your site's source can potentially read them. Don't put API keys, tokens, or anything sensitive here. Stasho has no secret store yet — if your build genuinely needs a secret, keep it in your repo's GitHub Actions secrets and reference it from the workflow file yourself.
What they're for
Build-time configuration that your framework reads during build — public API endpoints, feature flags, analytics IDs, NEXT_PUBLIC_* / VITE_* style values. Exactly the class of variable that ends up in your shipped JavaScript anyway.
Add, edit, remove
Open your project's Environment tab (/projects/<id>/environment):
- Click Add variable
- Fill in Name and Value — names are validated as you type
- Remove a row with the trash icon
- Click Save
Changes apply on the next deploy — push a commit or hit Redeploy to pick them up. Saving here never touches your repo (no PR, unlike build settings).
How they reach your build
Your deploy workflow has a Fetch build env step (included automatically — you don't add it). At build time it fetches your variables from the backend over the same authenticated channel the deploy itself uses, and exposes them to the build step as ordinary process.env.* values.
If that fetch fails, the deploy fails loudly rather than building with missing configuration — a half-configured build never ships silently.
Like your build config, the values are stored encrypted on Aleph (see Your data on Aleph); "not secret" refers to where they end up — your published build — not how they're stored.
Rules and limits
| Rule | Value |
|---|---|
| Name format | Letter or _ first, then letters, digits, _ |
| Reserved names | BACKEND_URL, AUDIENCE, TOKEN, anything starting with GITHUB_ or ACTIONS_ |
| Duplicates | Not allowed |
| Count | Max 50 per project |
| Value size | Max 4 KB each, 16 KB total |
The panel shows an inline error under any row that breaks a rule. Rows left completely blank are dropped on save.
Verification
After saving and redeploying:
- The new deployment's build sees your variables (e.g. a
NEXT_PUBLIC_*value renders in the page) - The Fetch build env step in the GitHub Actions run log shows a successful fetch
What can go wrong
| Symptom | Cause | Fix |
|---|---|---|
| Variable doesn't show up in the site | The deploy that's live predates your save | Redeploy; check you're looking at the new build, not a cached or pre-FINALIZING domain |
| Save rejected with a name error | Reserved or malformed name | Rename it — see the rules table |
| Deploy fails at the Fetch build env step | Backend was unreachable at build time | Redeploy; if it persists, report it |