Shared variables

What it is

One variable that several apps can use - across one team, or across several. Change it once and every app that uses it gets the new value on its next deploy.

Typical cases: an API key three services all call, an S3 bucket name, a SENTRY_DSN.

How it works

A shared variable has two independent parts, and confusing them is the single most common mistake here.

Availability scopes say who it is offered to. A scope is a suggestion. A variable can carry several:

Scope	Suggested to
Teams	Every app in each team you tick
Projects	Every app inside the chosen projects, or only the environments you narrow it to
Specific apps	Exactly the apps you pick - the one scope that links right away

Two variables may carry the same name, as long as they are offered to different audiences: one DATABASE_URL per project is the point of the model. The same name offered to exactly the same apps, projects and teams is refused, because nothing on the page could tell the two rows apart and one would silently win at deploy time.

The per-app link is what actually injects it. Until an app links the variable, the value reaches nothing, whatever its scopes say.

That is deliberate. A variable that appeared in every app the moment somebody ticked a team would make a shared secret a footgun, and would make "why does this app have that value" unanswerable.

At deploy time a linked shared variable folds above the app's own variable of the same name, and below a preview override.

Two teams or more, and it stops asking

Ticking a second team changes what the variable does. It is then added to every app in every team you ticked, with no link and no opt-in, and it folds at the lowest priority - so an app's own value for the same name still wins.

That is the setting for a corporate proxy or an internal registry mirror, and the wrong one for anything a single team should keep to itself. The review step spells out which of the two you are about to create, and the wording changes as you tick.

You can only tick a team you hold Manage env vars in, across the whole of that team. A team the variable already reaches stays ticked and locked, so a variable shared instance-wide is still editable by an admin who is not a member of every team.

Unticking a team until only one is left turns the automatic add off, and the variable is a suggestion again. A team that is deleted does not: the variable keeps injecting into the teams that are left, which is why removing a colleague's team never silently strips a value from yours.

A variable another team shares with you

It shows in your Shared tab with the owning team's name and no edit buttons: they own the value, you receive it. You can still link it to your own apps. You are told who owns it, not which other teams it also reaches.

On an app's Environment tab a variable that arrives this way is listed read-only, so a value in the container is never a value with no explanation. The one thing you can do to it there is Remove from this app, which takes back your own link.

If the owner later stops sharing it with your team, your apps' links to it go with it. Nothing is left behind to spring back to life if they ever share it again.

Create one

You can start from two places: the Variables page, or the app you want the variable in.

From the Variables page

Open the Shared tab

Open Variables in the sidebar, then the Shared tab, then New shared variable.

Fill the table

Type a name and a value per row. Add another takes as many rows as you like, and pasting a whole .env into a name field explodes it into rows - every one of them becomes its own shared variable.

The Secret switch applies to the whole table. A secret is write-only and immutable, here as anywhere else.

Set availability

Choose at least one availability scope, or pick specific apps. One of the two is required, and the choice applies to every row you typed.

Picking Teams opens the list of teams you may share with, all ticked. Untick to narrow it - one team is the ordinary case.

Review and create

The last step lists what is about to be created and how many apps each scope reaches.

From an app

Open the app's variables

Open the app, then Environment, then Add.

Go to Shared

On the Shared tab, click New shared variable.

Fill it in

Same table. This app is already the destination and cannot be unpicked - the variable is linked to it as soon as it is created. You can still offer it to teams or to projects at the same time.

Creating a shared variable needs the Manage env vars permission held across the whole team, not only on one app. Without it the button is not there.

Use one in an app

Open Environment

Open the app, then Environment.

Link it

Click Add, then the Shared tab: every shared variable offered to this app is listed there. Add the one you want.

Redeploy

Redeploy.

A linked row in an app shows two different removals, and they mean very different things:

Action	Effect
Remove from this app	Unlinks it here. The variable and every other app keep it
Delete for all apps	Deletes the variable for the whole team

On a variable that reaches more than one team there is no link to take back: Remove from this app drops your explicit one, and the variable keeps arriving from the team that shares it, at the lowest priority. The row says so, and stays.

Limits and gotchas

Scope is not injection. Worth repeating: the link is the only mechanism, unless the variable covers more than one team.
The app's own variable loses to a linked shared one of the same name. If an app needs its own value, unlink the shared one rather than fighting it.
A shared variable belongs to the team that created it. Deleting that team deletes the variable, including for any other team it reached - the delete dialog counts them.
Deleting one affects every app that links it, on their next deploy. The dialog says how many.
Secrets follow the same fork rule: a preview of a fork never receives a secret-typed shared value.
A compose app's own file wins. Deplo passes a variable into every service of a compose stack, but a key the compose file sets itself keeps the compose value. Those rows are marked Set in the compose file on the app's Environment tab: change the value there, or remove the key from the compose.
Deleting the last project, environment or app a variable was offered to leaves the variable, not the sharing: the row reads Not shared with anything until you give it a new audience. Its value is untouched and still editable.

If it does not work

The app does not see the value - it is scoped but not linked. Link it on the app's Environment tab.
The value changed and the app still has the old one - it applies on the next deploy. Redeploy.
A different value than expected - the app defines the same name itself, a preview override does, or the app is a compose stack whose file sets that key.