rollback(id: string, options?: RequestScope): Promise<RolledBackVersionResource>Restores an environment to a snapshot in one transaction, behind the same per environment advisory lock that envless.variables.apply takes. The environment is derived from the version, which is why there is no project or environment argument here.
It rewrites the live environment, it does not create a new version. Variables in the snapshot but missing live are re-created, variables in both are overwritten whenever value, type, visibility, required or defaultValue differs, and live variables absent from the snapshot are soft-deleted. Ids are not preserved, so a re-created variable comes back with a new id and any cache of variable ids has to be rebuilt afterwards.
Rollback does not snapshot the current state first, so call envless.versions.create before it if you might want to come back. The restored ciphertext is copied verbatim too: if the workspace passphrase was rotated without re-encrypting version entries, this call succeeds and writes values that no longer decrypt, with no warning.
Example
const backup = await envless.versions.create('api', 'production', { note: 'pre rollback' })
const result = await envless.versions.rollback('0191f0c4-6d2a-7c31-9a4b-8f2e1d5c7a90')
console.log(backup.label, result.versionLabel, result.added, result.updated, result.removed)Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Version uniqueId to restore, which must belong to the workspace behind the key. |
options.signal | AbortSignal | No | Cancels the request. |
Returns
RolledBackVersionResource with the restored versionLabel plus added, updated and removed counts.
Worth knowing
- Requires both
versions:writeandvariables:write. - Rollback needs Dev or above. On the Free plan, which keeps only the latest published version, every call fails with status 402 and code
plan.upgrade_required(error.resourceversion). Nothing is deleted on a downgrade, so the same id restores once the plan is back. - The three counts describe what changed live, not the size of the snapshot. All zero means the environment already matched the version.
- The restored variables are new rows, so re-read the environment before trusting any variable id you held before the call.
Required scopes
versions:write and variables:write
Underlying endpoint
POST /versions/{id}/rollback
Request and response schema, every error code, and a live playground.
In Python
envless.versions.rollback()
The same method in envless-sdk, the Python SDK, with the same request, retries and errors.
In Ruby
Envless.versions.rollback
The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.
In PHP
$envless->versions->rollback()
The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.