Variables and secrets

Which level should you use?

Project secret: a value shared across environments or services.
Environment variable: a value specific to production, staging or preview.
Add-on binding: a connection value generated by a database or cache.
Service variable: a value specific to that service, with the highest priority.

In a conflict, the order above runs from lowest to highest priority. Key names are visible, but secret values are masked after saving.

Build-time versus runtime

Build-time values are available to the builder while creating an artifact, for example a variable consumed by a frontend bundler. Runtime values are injected only when the process runs and are generally more appropriate for credentials. A variable read at startup requires a deployment or restart after changing it.

Do not expose secrets in Git, Dockerfiles, public build arguments, screenshots or logs. If exposed, rotate the value at its original source, then redeploy the service.

Reference variables

References prevent copied values from drifting and are resolved during deployment:


DATABASE_URL=${{ Postgres.DATABASE_URL }}
APP_KEY=${{ shared.APP_KEY }}
PUBLIC_URL=https://${{ GERDOO_PUBLIC_DOMAIN }}

${{ shared.KEY }} reads from a project secret, ${{ ServiceName.KEY }} from another service, and ${{ KEY }} from the service’s own context. If a reference cannot be resolved, check the service name, environment, key spelling and binding.

Two stores in the CLI

gerdoo service env manages a simple env map. gerdoo service vars manages the typed store with --build-time and --secret options. For new configuration, the typed store is the clearer choice.