Shared Environment Variable Groups

An environment variable group holds values that several Orbit projects need, such as a shared API key or a database credential, in one place. Link the group to the projects that need it and every one of their builds gets those variables, so rotating a key is one edit rather than six.

Where Env Groups Live

Open Orbit and choose Env groups from the top-level navigation. The page is titled Shared env var groups and describes them as account-level groups shared across multiple Orbit projects.

Groups sit above projects. A project's own variables still live on its Env vars tab: see Environment Variables in Orbit.

When To Use a Group

The test is simple: is the same value pasted into more than one project?

Good candidates:

• A shared analytics or error-tracking key used by every front end.
• A read replica connection string used by several internal tools.
• A third-party API key for a service the whole account talks to.
• A common feature-flag client token.

Poor candidates:

• Anything specific to one project. It belongs on that project.
• Anything that differs between production and preview. Groups are not per environment, so a value that changes by environment belongs on the project's own environment variables.

Creating a Group

1. Click New group.
2. Give it a Group name, up to 64 characters. Name it after what it contains, for example the service the credentials belong to.
3. Add an optional Description.
4. Click Create group.

An account can hold up to 20 groups. When you are at the limit the button shows (limit reached) and creating another is refused.

Adding Variables

Open the group and use the Variables section:

1. Click Add variable.
2. Enter the key and the value.
3. Tick Mark as secret for anything sensitive.
4. Click Save group.

A variable marked as secret is stored encrypted and its value is not returned to the panel afterwards. The list shows the key and a Marked as secret (hidden) indicator instead of the value. Non-secret values remain visible so you can check them at a glance.

To change a secret's value, type the new one and save. To remove a variable, click Remove on its row and save.

Linking Projects

The Linked projects section lists every project in the account. Click a project to link or unlink it; linked projects are highlighted. Save the group to apply.

A group with no linked projects does nothing, and the section says No projects yet until you link one.

Group variables are injected at build time, so linking a project affects its next build, not the deployment currently live. If you need the change now, redeploy: see Deploying Your Project.

Precedence

The rule is stated on the page: group variables are injected at build time, and project-level and environment-level variables take precedence over group variables.

In other words, most specific wins:

1. Environment-level variables, highest priority.
2. Project-level variables.
3. Group variables, lowest.

That ordering is useful rather than merely a technicality. Set the shared default in the group, and override it on the one project that needs something different, without removing that project from the group. See Environment Variables Per Environment for the environment layer.

It also explains the most common confusion with groups: you edit the group, redeploy, and nothing changes, because the project has its own variable with the same key quietly winning. Check the project's own Env vars tab first when a group value seems to be ignored.

Rotating a Shared Credential

This is the workflow groups exist for:

1. Create the new credential at the provider, leaving the old one active.
2. Edit the value in the group and save.
3. Redeploy each linked project, or wait for its next deploy.
4. Confirm each project is working on the new credential.
5. Revoke the old credential at the provider.

Doing step 5 first gives you a window where every linked project is broken at once, which is precisely the risk a shared credential concentrates.

Deleting a Group

Click delete on the group. The confirmation is specific about the consequence: future builds will lose these variables, and already-completed builds are not affected.

Deleting also unlinks every project. That means the running deployments carry on with the values they were built with, and the next build of each linked project comes up without them. If those variables are required, that build will fail or the app will misbehave at runtime.

Before deleting, unlink projects one at a time and redeploy each, so you find out which ones actually depend on the group before all of them lose it.

Practical Advice

Keep groups small and purposeful. One group per external service beats one giant "shared" group, because it lets you link exactly the projects that need each thing.

Name keys the same everywhere. If one project reads SENTRY_DSN and another reads SENTRY_KEY, a shared group cannot help you. Standardise the names first.

Do not put production credentials in a group linked to projects with public previews. Group variables reach every build of a linked project, previews included.

Troubleshooting

A build does not see the variable. Confirm the project is linked and saved, and that the build ran after the link was made. Group variables apply from the next build.

The value is wrong at runtime. A project-level or environment-level variable with the same key is overriding it. Check the project's Env vars tab.

Create group is unavailable. You are at the 20-group limit, or your account role is not owner or admin.

A secret's value shows as blank. That is correct. Secret values are not returned to the panel after saving.

A project broke after a group edit. Roll the value back in the group and redeploy, then work out which project disagreed. Rolling Back a Deployment gets the running site healthy while you do.

Where To Go Next

• Environment Variables in Orbit for project-level variables.
• Environment Variables Per Environment for the override layer.
• Orbit Project Settings for the rest of a project's configuration.