Variables API

Preview the .env.example keys of a repository before creating its service

Like the service scan, for a repository that has no service yet: nothing is created or stored. The suggestions can reference the databases of the environment. Give a git connection and repository, or a repository URL (with gitToken for a private one); serverId is the server a read that needs an agent (Bitbucket, other hosts, a pasted token) runs on. The pasted token is used for this read only and never stored. A repository that cannot be read answers status: unavailable with the reason.

Which variables reference a variable

Read a git service's .env.example files again

Reads .env.example, .env.sample, .env.template and .env.dist (never .env or .env.local) from the repository root and the build context at the tracked branch: through the git provider's API when the service is linked to a connection or the repository is public on github.com or gitlab.com, otherwise by a scan-only command on the service's server. The files become the suggestion source of GET /services/{serviceId}/suggested-variables. Returns the keys not set yet with smart defaults; a repository that cannot be read answers status: unavailable with the reason, and nothing changes. Reading re-runs on every push to the tracked branch.

Suggested variables

References to databases of the environment that nothing references yet, and the keys of the repository's .env.example-style files that are not set yet (read before the first deploy, see POST /services/{serviceId}/env-template-scan, and again after every push to the tracked branch and at every build). Accepting a suggestion is a normal staged write; send source: "suggested" for an .env.example key so a value left empty is reported by the deploy plan.

List a service's variables

Secret values are never returned: they appear as {key, isSecret:true, set:true}. computedSecret is also true for a variable that embeds a secret through a reference. platform lists the reserved variables NebulaCtrl provides; exports the virtual variables other services can reference.

Upsert variables (staged until deployed)

Bulk upsert; variables not listed are untouched. Omitting a value keeps the stored one. Values may reference other services (${{service-slug.KEY}}), the same service (${{KEY}}) and shared variables (${{shared.KEY}}), and may contain generators (${{secret(32)}}, ${{randomInt(1,6)}}, ${{uuid()}}, ${{randomBytes(32,hex)}}) that run once: writing the same text again keeps the generated value. $${{ writes a literal ${{. Variables whose resolved value changes in other services are restaged (restaged). Platform variable names (PORT, NEBULA_*) are rejected with reserved_variable.

Delete a variable (staged until deployed)

Version history of a variable

Newest first. Non-secret versions include their value; secrets carry only a fingerprint (equal fingerprints mean equal values).

Restore an old non-secret version as a new version

Secrets cannot be restored (restore_unsupported); use a release rollback or re-enter the value.

Rotate a generated variable (plan or stage)

Re-runs the generators of a generated variable. dryRun:true returns the plan (affected services, deploy order, warnings, blockers) and changes nothing; dryRun:false stages the new value and restages the services that consume it. Nothing is deployed. Database credentials and volume-backed passwords are blocked with rotation_unsupported once deployed.

Validate a draft value

Parses the draft, checks generator arguments and dry-run resolves its references in the service's environment. Nothing is written and no generated value is returned.