Environment variable references

An application’s environment variable normally holds a literal — the value is stored with the app. If the same database URL is used by three apps, you have three copies, and rotating it means editing three places and hoping you found them all.

A reference stores a pointer instead: this variable comes from that key in that secret project. The value is resolved at deploy time. Rotate the secret once and every app that references it picks up the new value on its next deploy.

This is for applications Reoclo deploys. For a pipeline running elsewhere, use reoclo run.

Creating a reference

In your application’s environment variable editor, switch the variable’s source from Literal to Reference, then choose:

• the secret project to read from
• the key within it

Save, and deploy for it to take effect. As with any environment change, editing does not redeploy on its own.

The variable list shows referenced variables as pointers rather than values — there is no copy to reveal, because there is no copy.

The variable name and the key can differ

The environment variable your container sees is named by the variable, not by the secret. The reference only decides where the value comes from.

So one secret can land under different names in different apps:

App	Variable	References
api	DATABASE_URL	payments-production / DATABASE_URL
worker	PG_DSN	payments-production / DATABASE_URL

Both get the same value. Neither stores it. Rotating DATABASE_URL in the project updates both on their next deploy.

Access is handled for you

You do not grant an application access by hand. When a variable references a project, Reoclo reconciles a grant for that application, and removes it when the last reference to that project goes away.

Those grants are visible on the project’s Access tab alongside the ones you added, marked as belonging to an application. Do not delete them by hand — they are derived from the references, and reconciliation will restore or drop them to match.

The effect is that an app’s access is always exactly what its configuration says it needs. There is no drift between “what this app can read” and “what this app actually uses”.

Deploys fail closed

If a reference cannot be resolved at deploy time — the key was deleted, the project was removed, the grant is gone — the deploy fails. It does not start the container with the variable missing or empty.

The error lists every reference that failed, not just the first, so a bad rename shows you the whole set to fix in one pass.

This is deliberate. An app that boots without its database URL is usually worse than an app that does not boot: it fails later, further from the cause, sometimes after taking traffic. A failed deploy leaves the previous version running.

Deleting a secret can break a future deploy, quietly

Nothing stops you deleting a key that an application references. Running containers keep the value they were given at deploy — the breakage surfaces at the next deploy, which may be days later and triggered by someone else. Check a project’s Access tab for application grants before deleting keys from it.

Previews

Preview environments keep their own variable map, so a preview can reference a -staging project while production references -production. The same key name resolves to a different value depending on which map is in play, and preview deploys fail closed the same way.

When to use which

You want	Use
A value only this app uses, and nothing else needs	a literal
A value shared by several apps	a reference
A value your pipeline needs, outside a Reoclo deploy	reoclo run
A value that must be rotatable without touching apps	a reference

Next Steps

• Secrets Manager — projects, versions, and grants
• Injecting secrets into CI — the pipeline equivalent
• reoclo env — an application’s own environment variables
• Deployment Configuration — the wider deploy surface