Environment variables and secrets

The examples use the web Application in the production Environment of storefront, its database pg-main, and a Redis URL kept once for the whole Project.

What you can do

• Keep variables on a Project, an Environment and each Service.
• Share one value across Services by referencing it by name.
• Link another Service’s Output, such as a database’s url, as a wired variable.
• Hide values whose names look secret, and reveal them when you need to.
• Set build arguments and build secrets for the build only.
• Set a Service’s variables from the CLI with cloudgate vars set.

Where variables live

Level	Where in the console	Who sees it
Project	Project > Settings > Project variables	Any Service in any of its Environments, by reference
Environment	Environment > Variables	Any Service in that Environment, by reference
Service	Service > Variables	That Service’s containers

Variables are not inherited. A Service is deployed with its own keys only. The Service’s Variables tab lists what is Available from the Environment and Available from the Project, “by reference, not by inheritance”.

Set a Service’s variables

1. Open the Variables tab

   Open the Service, such as web, and its Variables tab.

   cloudgate.octabyte.app/applications/…/variables

   

2. Edit the block

   Press Edit, or Add variables when there are none. Write one KEY=value per line. Lines starting with # are comments and are kept.

3. Save and deploy

   Press Save variables, then deploy the Service. A change here needs a Deployment to take effect.

Share a value across Services

Put the value once on the Project or the Environment, then name it in each Service that needs it:

CACHE_URL=${{project.REDIS_URL}}
API_BASE=${{environment.API_BASE}}

The reference is resolved at each deploy. A key on the Project or Environment that no Service names reaches no container.

Link a database or bucket with a wired variable

A wired variable is filled in from another Service’s Output at each deploy. Nothing stores it or shows it, so a password rotated at the source reaches the next deploy without anyone copying it.

1. Link a variable

   On the Service’s Variables tab, find Wired variables and press Link a variable.

2. Pick the Output

   Enter the variable name, such as DATABASE_URL, choose the Service pg-main and the Output url, and press Save link. If the variable already had a typed value, the button reads Replace typed value with link.

3. Deploy

   Deploy the Service. When an Output changes later, the console says “A wired variable has a new value.” Deploy again to hand it over.

In the Project config the same link is written under the Service:

services:
  web:
    kind: web
    env:
      - DATABASE_URL: pg-main.url
      - S3_BUCKET: uploads.name

Linked Service	Outputs
PostgreSQL, MySQL	url, host, port, user, password, database, ca
Redis	url, host, port, password, ca
Bucket	name, region, endpoint, access_key_id, secret_access_key, path_style

Every Output is a secret. A Server hands out no ca. Remove a link with Unlink.

How secrets are kept

• Encrypted at rest. Every variable value is stored encrypted.
• Masked in the console. Values whose names look secret (containing PASS, SECRET, TOKEN, KEY, AUTH, _URL and similar) are hidden until you press Show values. The match is on the name.
• Never returned. Stored secrets such as a database password or a registry token come back from the API only as “set” or “not set”.
• Masked for Agents. Every tool result an Agent gets, logs included, replaces stored secrets with ••••••.
• Never in the config. The Project config lists variable names only, never values.

Build arguments and build secrets

An Application’s Variables tab also has Build arguments (passed as --build-arg) and Build secrets, which are mounted during the build only and end up in no image layer. Use build secrets for a private package registry token.

Who can change variables

Variables	Who
A Service’s	Members granted the Service (the member role holds service: update)
An Environment’s	Members granted the Environment
A Project’s	Owner, admin, or a custom role with project: update

A Project write reaches every Environment under it, which is why the member role does not have it.

What you cannot do

• Make a Service inherit variables: it must name them.
• Change a running container’s variables without a Deployment.
• Read a wired variable’s value in the console: it exists only in the container.
• Add a new variable name in the console when the Project config is kept in a repository. Values stay editable; the name is the file’s to add.
• Set Project or Environment variables, build arguments or build secrets from the CLI: only a Service’s own.

Related pages

• Databases and buckets hand out the Outputs you link.
• Projects and Environments.
• Deployments: a variable change needs one.
• CLI commands for cloudgate vars.
• How Cloudgate protects secrets on the security page.

Questions

Do Services inherit Project or Environment variables?

No. A Service gets only its own keys. It reaches a Project or Environment value by naming it, such as ${{project.REDIS_URL}}. A key nobody names reaches no container.

Does saving a variable restart my Service?

No. Saving changes nothing that runs. Deploy the Service for the container to get the new value.

What happens if a referenced variable is removed?

The next Deployment of every Service that names it fails, instead of running with an empty value.

Are my variables encrypted?

Yes. Values are encrypted at rest, and the Project config holds only variable names, never values.