Versions

envless.versions.create()

Publish a snapshot of the environment

ts
create(project: string, environment: string, body?: VersionCreate, options?: ProductScope): Promise<VersionResource>

Snapshots every live variable in the environment as it stands right now into a new immutable version, and emails the active members of the workspace apart from the publisher. This is the programmatic equivalent of publishing a version in the dashboard.

The ciphertext is copied verbatim. The server cannot decrypt or re-encrypt it, so the workspace key in force at this moment is the key needed to read the snapshot back later. That is exactly why rotating a passphrase has to rewrite version entries as well as live variables.

Take a version before any risky bulk change, and take one before a rollback, because envless.versions.rollback does not snapshot the current state for you. The body is optional and a missing or unparseable body is read as no note rather than an error.

Example

ts
const version = await envless.versions.create('api', 'production', { note: 'before billing migration' })

console.log(version.id, version.label, version.variableCount)

Parameters

ParameterTypeRequiredDescription
projectstringYesProject slug or project uniqueId.
environmentstringYesEnvironment slug to snapshot.
body.notestringNoFree text label for why the snapshot was taken, up to 200 characters.
options.productstringNoProduct slug used to disambiguate a project slug shared across products.
options.signalAbortSignalNoCancels the request.

Returns

VersionResource for the new snapshot, carrying the server assigned label and the variableCount captured.

Worth knowing

  • label is assigned server side. Passing one has no effect.
  • A note over 200 characters and an environment already holding 1000 versions both fail with status 400 and the generic request.invalid code, so read message to tell them apart.
  • Publishing is on every plan, Free included. What Free lacks is the history: only the latest version can be read back or restored there, so a snapshot taken as a safety net before a bulk change is only usable as one from Dev upward.
  • A version is immutable and the SDK exposes no update or delete for one. The only way forward is another snapshot.

Required scopes

versions:write

Underlying endpoint

POST /projects/{slug}/environments/{environmentSlug}/versions

Request and response schema, every error code, and a live playground.

In Python

envless.versions.create()

The same method in envless-sdk, the Python SDK, with the same request, retries and errors.

In Ruby

Envless.versions.create

The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.

In PHP

$envless->versions->create()

The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.