Environment variable governance

One shared definition, many consumers, and a reviewed path for changing it.

By the OneEnv team · Last updated 2026-10-15

What it is

An Env Master is a workspace-level variable definition: a key, a description, a secret flag and one value. Services inherit it. Changing the value of a master that others inherit is a governed edit; creating a master, renaming it, or setting its first value is immediate.

Why it matters

Shared variables are copied between repositories and drift apart. With inheritance, the list of consumers is data: you can see which services use DATABASE_HOST before you change it, and each of them decides whether to accept the new value.

When to use it

For values used by two or more services. Keep values that only one service needs inside that service.

Prerequisites

A workspace and at least one service.
To inherit a value into a service you need edit permission on that service (Owner and Admin always do).
To change an existing value you need an active branch.

Step by step

Open Env Master and choose New Env Master (Key, Description, secret checkbox).
Or bring many at once with the .env or CSV import. Importing a key that already exists stages a branch change rather than overwriting it.
Or create from a Template. Templates are reusable field sets (for example a Postgres host, port, database name); importing one makes a Template Instance with one master per field.
In a service, open Variables and use Inherit Env Master or Inherit Template Instance.
To change a shared value: select or create a branch, edit the value in Env Master, and save. The edit is staged on the branch.
To opt one service out of the shared value, set an override on that service and publish it. The override always wins for that service and does not use a branch.

Illustrative example

Services billing, orders and reports all inherit DATABASE_HOST. You stage a new host on a branch called move-db-host. Nothing changes until the branch is merged; then each of the three services gets its own decision to approve or reject.

What you should see

Each service lists inherited variables with a status (in sync, or pending while a decision is open).
Secret values are masked on every screen except the export itself.
A rejected change leaves that service on its last approved value; its export does not move.

Common errors

DUPLICATE_KEY (409): the key already exists in the workspace, including archived keys.
Re-submitting a masked secret (the starred display value) is rejected, so a mask can never overwrite the real secret.
Edit controls are disabled with a hint when no branch is selected.

Branching · Propagation · Export · Workflow: update a shared variable

← Previous

Invite team members

Branching and staged changes