Environment variables

Environment variables configure your service without code changes. Every value is encrypted at rest and masked in the UI. Admins can reveal values, and every reveal is logged. A variable marked secret can never be revealed again.

Add or edit a variable#

1. 1

   Open the Environment tab

   On the service page, go to the Environment tab.

2. 2

   Enter a key and value

   Type the variable name (uppercased automatically, for example NODE_ENV) and its value, then click "Add". Reusing a key overwrites it.

3. 3

   Redeploy to apply

   Changes take effect on the next deploy. Click "Deploy" when you’re ready.

Connect a database#

Open a database’s Connect tab to reveal a ready-to-paste block of connection variables, for example DATABASE_URL for Postgres and MySQL, MONGODB_URI for MongoDB, or REDIS_URL for Redis. Copy them into your service’s environment.

Limits & rules#

• Keys are uppercased automatically: node_env becomes NODE_ENV.
• Values can be up to 32,768 characters.
• Changes take effect on the next deploy.
• Through the API and CLI, listing variables returns the keys with masked values. An admin can read values with gheima env reveal, which never returns a secret variable.

Env groups (shared config)#

Create a reusable env group under Env groups, add variables (or import a .env file), and attach it to several services. On deploy, the group’s variables are injected into every attached service. A service’s own variables override the group’s. Use a group for config and secrets that several services share.

Build-time variables#

Variables are normally injected when the container starts, so nothing secret ends up inside your image. Some builds need values earlier: a Next.js app that pre-renders pages from its database, or NEXT_PUBLIC_ and VITE_ values inlined into the browser bundle. Mark those keys with the hammer toggle in the Environment tab, or add them under "Build-time variables".

• Only the keys you mark reach the build. Everything else stays runtime-only.
• Values are mounted as build secrets for the step that reads them, never written into an image layer.
• Keys resolve like they do at runtime, so a linked database’s DATABASE_URL works by listing that one key.
• Whatever your build writes out of a value does persist. An inlined NEXT_PUBLIC_ value lives in the bundle because your framework put it there.