Setting environment variables per environment

Orbit lets you control exactly which environment variables are available in each type of build - production, staging, or branch previews. This lets you keep production secrets out of preview deployments and use different API endpoints per environment.

How scoping works

Every variable in Orbit has a scope that determines when it is injected at build time:

• All environments (project-wide) - the variable is available in every build regardless of environment type. This is the default.
• Production only - the variable is only injected when building the production environment.
• Staging only or Preview only - environment-level overrides that only apply to builds of that specific environment.

When the same key exists in multiple places, the most specific wins. An environment-level override takes precedence over a project-wide variable with the same key.

Adding a variable

1. Go to Orbit -> [your project] -> Env vars
2. Scroll to the Add variable section at the bottom
3. Fill in the KEY and value fields
4. Use the Scope dropdown to choose where the variable applies:
   • All environments (project-wide) - injected into every build
   • [Environment name] only ([type] override) - scoped to one specific environment
5. If you choose project-wide, you will also see Available in buttons: production, staging, preview. Deselect any types you want to exclude.
6. Check Mark as secret if this is a credential or token - secret values are masked in the UI
7. Click Add

Adding a production-only variable

To add a variable that only exists in production builds:

1. In the Scope dropdown, select your production environment (shown with a green "production" badge), or
2. Keep the scope as "All environments" but deactivate the staging and preview buttons under Available in

Either approach means the variable will not be present when a preview branch or staging build runs.

Security guidance

Variables scoped to "All environments" are available in branch previews. Branch previews are accessible to anyone with the preview URL. This means:

• Production database credentials, payment keys, and admin secrets must be scoped to production only
• For preview builds, use test-mode or sandbox credentials for third-party services
• Never put STRIPE_SECRET_KEY, DATABASE_URL (production), or similar secrets in the All environments scope unless you intend them to be present in previews

A common safe pattern is to keep your production database URL in a production-only variable, then add a separate DATABASE_URL pointing at a test database with project-wide scope. The production-scoped variable wins at production build time, and previews use the test database URL.

Viewing and editing existing variables

The Env vars tab shows variables grouped into sections:

• All environments - project-wide variables at the top
• Collapsible sections for each environment (for example, "Production" or "Staging") showing environment-specific overrides

Variable values are hidden by default. Click the pencil icon next to any variable to update its value. You cannot view the current value of a secret variable - you can only replace it.

The badge next to each variable name shows whether it is scoped to specific environment types. For example, a variable showing production and preview badges (but not staging) will be excluded from staging builds.

Inheriting production variables in staging

Under Settings -> Staging: environment variables, there is a toggle: Inherit production env vars. When enabled, production-scoped variables are merged into staging builds at lower priority than staging-specific overrides. This is useful if your staging environment is nearly identical to production and you only want to override a handful of values.

Importing variables from a .env file

The Env vars tab has an Import .env button. Paste your .env file contents and choose a scope. Orbit detects the number of variables, marks likely secrets automatically based on the key name (any key containing SECRET, TOKEN, KEY, PASSWORD, and similar terms), then imports them in bulk. You can also use the Download .env button to get a template with just the key names (no values) to share with your team.