Environment variables and secrets
Workspace env vars, the vault, templates in harthelm.yml and what reaches which stage.
A workspace has two kinds of values for your app: environment variables, which are plain and visible to anyone who
can open the workspace, and secrets in the workspace's vault, which are stored encrypted and never shown again.
harthelm.yml refers to both with templates.
Workspace environment variables
Environment variables on the rail, or hart env, holds name and value pairs:
hart env set NODE_ENV=production LOG_LEVEL=info
hart env list- Every terminal sees them (new terminals at once), the prepare and test stages, and every service after the next Sync.
- Names are letters, digits and
_, not starting with a digit.HART_*is reserved. - Import .env reads a
.envfile into the list; nothing is saved until you click Save.
They are not secret: keep passwords and tokens in the vault.
The vault
Each workspace has a vault for secrets. Values are write-only: you set or generate one, and nobody sees it again.
hart secret generate SESSION_KEY
hart secret keysA service gets a secret only if its env names it:
services:
api:
type: steps
steps: [{run: ./api}]
env:
API_KEY: ${{ secrets.API_KEY }}The Sync review asks for every secret the file references that has no value yet: type one, or let Harthelm generate a random 32-character value. See Secrets.
Templates in harthelm.yml
Templates ${{ … }} are filled in at Sync. They work in env values, a managed service's config and secrets,
and a forward target; anywhere else they are an error.
| Template | Value |
|---|---|
${{ workspace.id }} | the workspace's id |
${{ workspace.devDomain }} | the dev URL's host, <id>-3000.<workspace domain> |
${{ team.id }} | the team's id |
${{ env.K }} | the workspace variable K; an unset one is an error at Sync |
${{ secrets.K }} | the vault value of K |
${{ services.<name>.host }}, .port, .dsn, .secret, .details.<field> | the connection of a managed service of the same file; .secret is its password or key alone and follows a rotation (see Managed services) |
There are no operators or defaults. $${{ writes a literal ${{.
What reaches which stage
| Terminals | prepare, test | Services | |
|---|---|---|---|
| Workspace env vars | yes | yes | yes, after a Sync |
A service's own env | that service | ||
| Secrets | no | only the services whose env names them | |
HART_* variables | yes | yes | yes |
A service's own env wins over a workspace variable of the same name. Every service also gets HART_WORKSPACE_ID,
HART_TEAM_ID, HART_DEV_DOMAIN, HART_SERVICE, HART_REPLICA (the pod's name), HART_STAGE, HART_API and
HART_DATA=/data/app.
Changes need a Sync
A changed env var or secret takes effect at the next Sync. The Run panel says "Environment variables or platform settings changed since the last Sync" until then.