Setting Environment Variables Per Environment

Orbit lets you decide exactly which builds see which environment variables, so production credentials never end up in a publicly reachable branch preview. This guide covers how scope and precedence work, how to add a production-only variable, how staging inheritance behaves, and how to verify what a build actually received.

Why This Matters

A branch preview gets a public URL. Anyone with the link can load it. If a variable is scoped to every environment, it is injected into that preview's build, and whatever the preview does with it, it does with your production credentials.

That is the whole reason this page exists. Everything below is in service of one rule: production secrets belong in production scope, and nowhere else.

How Scoping Works

Every variable has a scope that decides when it is injected at build time.

Scope	Injected into
All environments (project-wide)	Every build of this project, unless you restrict it
A specific environment override	Builds of that one environment only

When the same key exists at both levels, the more specific one wins. An environment-level override beats a project-wide variable with the same key. The Env vars page states this in the subtitle of the All environments section: project-wide variables are available in every build, and environment-level overrides take precedence.

Project-wide variables can also be narrowed without becoming an override. The Available in control offers three environment types (production, staging, preview) and you can deselect any of them.

Adding a Variable With a Scope

Open your project in Orbit and click the Env vars tab.
Scroll to the Add variable form at the bottom.
Fill in the KEY and the value.
Use the Scope dropdown:
- All environments (project-wide) injects it into every build.
- [Environment name] only ([type] override) scopes it to that one environment.
If you chose project-wide, use the Available in buttons to deselect environment types this variable should not reach.
Tick Mark as secret for anything sensitive.
Click Add.

Before you commit, the form tells you what it is about to do. An override shows a notice saying it will apply only to that environment's builds and that project-wide variables still apply elsewhere. A restricted project-wide variable shows exactly which environment types it will be injected into.

Adding a Production-Only Variable

Two equivalent routes:

In the Scope dropdown, choose your production environment (it carries a green production badge), or
Keep the scope as All environments and deselect staging and preview under Available in.

Either way, the variable is absent when a preview or a staging build runs.

"Absent" means absent, not empty. Code that reads process.env.STRIPE_SECRET_KEY in a preview build gets undefined, and depending on how it is written that may throw at build time or, worse, silently take a wrong branch. Give previews a test-mode value rather than no value at all.

The Safe Pattern

The pattern that solves this cleanly for most projects:

Add the production credential scoped to the production environment only.
Add a variable with the same key, holding a test or sandbox value, at project-wide scope.

Production builds get the production-scoped value because the more specific scope wins. Previews and staging get the test value. Nothing is undefined anywhere, and no production credential ever reaches a preview.

Apply it to:

Production database URLs
Payment provider secret keys, using the provider's test keys for previews
Email sending keys, so a preview cannot mail real customers
Admin tokens and signing secrets
Anything with a per-call cost

Inheriting Production Variables In Staging

If your staging environment is close to production and you only want to override a few values, you do not have to duplicate everything.

In Settings, find Staging: environment variables and turn on Inherit production env vars. Production variables are then merged into staging builds at lower priority than staging-specific overrides, so anything you set explicitly on staging still wins.

Inheritance copies production values into staging builds, including production credentials. Only turn it on if your staging environment is protected. Staging supports both a password and an IP allowlist, in the Staging: access protection and Staging: IP allowlist sections of Settings. Turning on inheritance for an unprotected staging environment recreates exactly the exposure this page is about.

Viewing and Editing Existing Variables

The Env vars tab groups variables into:

All environments at the top, holding project-wide variables
A collapsible section per environment, holding that environment's overrides, with a count of how many

Above them there is a search box and a Secrets only filter.

The badges beside each variable name show which environment types it reaches. A variable showing production and preview but not staging will be missing from staging builds, and that badge row is the fastest way to audit a long list.

Click the edit icon to change a value. A secret variable's current value cannot be revealed, only replaced.

Copying and Comparing Between Environments

Copy variables between environments copies a whole set from one scope to another. Pick a From and a To, optionally tick Overwrite variables that already exist in the target, and click Preview to see how many will be added, updated and skipped before you commit.

The Env sync check page compares production and staging key by key and reports what exists only in one, what has different values, and what matches. It is the right first stop for "staging works and production does not", or the reverse.

Values differing between production and staging is normal and expected for most secrets. The sync page says so. What you are looking for is a key present in one environment and missing from the other.

Sharing Variables Across Projects

If several projects need the same credential, use an env group rather than pasting it into each project. Go to Orbit, then Env groups, create a group, add the variables, and link the projects that need them.

Group variables are injected at build time and sit at the bottom of the precedence order: project-level and environment-level variables both take precedence over group variables. You can have up to 20 groups on an account.

Deleting a group removes those variables from future builds of every linked project. Already-completed builds are unaffected.

Importing In Bulk

The Import .env button opens a paste box. Paste a .env file, choose a scope, and Orbit reports how many variables it found and how many it will mark as secret. Keys containing SECRET, TOKEN, KEY, PASSWORD and similar terms are flagged automatically. There is an Overwrite existing variables with the same key option, off by default.

Download .env produces a template of variable names only, with no values, for sharing with a teammate who will supply their own.

Choose the scope in the import dialogue before you click Import, not after. Importing a whole production .env at project-wide scope pushes every production credential into your preview builds in one action, and the fix is to delete and re-add them, not to change a setting.

Verifying What a Build Actually Received

Every deployment's detail page lists the environment variable keys injected at build time and diffs them against your current configuration: added, changed, removed, unchanged. Teal keys came from an environment-specific override, grey ones from project level.

Values are never stored or shown. Hovering a key gives a SHA-256 fingerprint, which is enough to confirm two environments hold the same value without revealing it.

If the configuration changed after that deployment was built, the page says so with an Environment variables updated since this deployment notice and reminds you that the change will not take effect until you redeploy.

Variable changes never apply to the deployment that is already live. They are injected when a build runs. After changing anything your app depends on, redeploy.