Variables

A variable in Envpilot isn't a row that gets overwritten in place: every change is versioned and every deletion is recoverable for a week. This page covers the lifecycle. Scheduled rotation and expiry reminders live on their own page — Rotation & expiry.

Per-environment key uniqueness#

Before anything else, one rule underlies every write path: the same key may exist on multiple active variables in a project only if their environment sets are disjoint. DATABASE_URL scoped to [development] and DATABASE_URL scoped to [production] are two independent variables; DATABASE_URL scoped to [development, staging] conflicts with one already scoped to [staging] because they overlap on staging. Attempting to create, update, or restore a variable into an overlapping environment fails with an error naming the clashing environment(s).

This keeps every (key, environment) pair resolving to exactly one active variable — which is what makes envpilot pull, extension sync, and the public API deterministic. The check runs on every write path: create, update (when environments change), variable-request approval, and restore from trash.

Version history#

Every value or metadata change to a variable inserts a new row into its version history: who changed it, when, which environments and description applied, and (for updates) an optional reason you can type in — up to 200 characters. The very first version is recorded automatically as "Initial creation."

The history view (opened from a variable's detail panel) lets you filter to updates vs. rollbacks and compare versions side by side. It's driven entirely by these version records, so nothing is inferred after the fact.

Version history is a Pro-tier feature (variable_version_history) — on Free tier the history list is empty.

Rollback#

Rolling back restores a variable to an earlier version's value, description, and environments, and — like every other write — records a new version ("Rolled back to version N") rather than deleting anything, so the history stays a complete, append-only log. Rollback is restricted to organization Admins; Team Leads, Developers, and Members cannot roll back a variable even if they can otherwise edit it.

If the target version's secret value was written before per-change vault objects existed, only its metadata (description, environments) is restored, not the value — the mutation reports whether the value itself was actually restored.

Trash and restore#

Deleting a variable is a soft delete: it's hidden from the active list, every active grant on it is revoked, and any live share links pointing at it are revoked too — a deleted variable can't leave a working external link behind. It then shows up in the project's Trash page for 7 days, alongside any soft-deleted shared accounts, each labeled with how long ago it was deleted and how many days remain.

Restoring re-runs the per-environment uniqueness check described above — if a new variable with the same key and an overlapping environment was created while the old one sat in the trash, the restore is rejected rather than silently creating a conflict. Restoring does not re-grant permissions or shares that were revoked on delete; those have to be re-created explicitly.

Past the 7-day window, a background sweep purges the variable (and its vault object) permanently, and it's no longer restorable. Anyone with delete access to a project can also Empty trash to purge everything early, which destroys the underlying vault values immediately.

Limits#

• Version history is Pro-only (variable_version_history). On Free the history list is empty — changes still apply, they just aren't recorded for comparison.
• Rollback is Admin-only, regardless of tier or of who can edit the variable.
• Trash holds deleted variables for exactly 7 days, then a sweep purges them and the underlying vault object permanently.
• Variables per project: 50 on Free, unlimited on Pro (max_variables_per_project).
• Restores are rejected — never silently merged — when they would break the uniqueness rule.

See also#

• Rotation & expiry — scheduled rotation reminders.
• Roles & permissions — who can restore, rollback, and manage trash.
• Secret sharing links — how shares interact with deletion.
• Shared accounts — the parallel trash/restore behaviour for accounts.