Releases, promotion and rollback

Operations#

Which capability you need#

Promotion and rollback are the two operations whose capability depends on the environment:

A developer can therefore bind testing and cannot bind production. The contract records the rule as x-beyond-capability-by on both operations: for promotion the environment is read from the request body, for rollback from the path.

The release#

A release is an immutable snapshot. Promotion and rollback rebind it; nothing re-resolves or rebuilds it.

Environments#

An application has exactly two environments, production and testing. Each is a binding:

Promote#

Promotion binds an environment to a ready release with an atomic compare-and-set on the binding's version:

{ "environment": "production", "expected_version": 7 }

If expected_version is not current, nothing changes and the answer is 409 CONFLICT_VERSION with details.current. Read the environment again and decide again; do not retry blindly with the new number.

// Bind the production environment to a ready release. The binding changes only
// if nobody else changed it since you read it.
const api = process.env.CDN_API_ORIGIN;
const token = process.env.CDN_TOKEN;
const application = process.env.CDN_APPLICATION;
const release = process.env.CDN_RELEASE;

const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };

const binding = await (await fetch(new URL(`/v1/applications/${application}/environments/production`, api), { headers })).json();
console.log(`production binds ${binding.release ?? 'nothing'} at version ${binding.version}`);

const response = await fetch(new URL(`/v1/applications/${application}/releases/${release}/promote`, api), {
	method: 'POST',
	headers,
	body: JSON.stringify({ environment: 'production', expected_version: binding.version })
});
const document = await response.json();

if (response.status === 409 && document.error.code === 'CONFLICT_VERSION') {
	// Somebody rebound the environment first. Nothing changed: read it again and decide again.
	console.log(`not promoted: the binding is now at version ${document.error.details.current}`);
	process.exitCode = 1;
} else if (!response.ok) {
	console.log(`${response.status} ${document.error.code} — ${document.error.message}`);
	process.exitCode = 1;
} else {
	console.log(`production now binds ${document.release} at version ${document.version}`);
	console.log(`rollback candidates: ${document.retained.join(', ') || 'none'}`);
}

Promotion keeps the tested graph and artifacts. The release you tested in testing is byte for byte the release you promote to production. A release that is not ready answers 409 STATE_INVALID.

Preview and acknowledge exposure#

A release freezes its sourcemaps and visibility when it is prepared. When the release publishes source maps, or is public while the application has since become private, promotion requires an acknowledged member that names exactly that exposure. A request without it, or with other values, changes nothing and answers 400 VALIDATION_FAILED with details.exposure:

{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": { "exposure": { "sourcemaps": "public", "visibility": "public", "acknowledgement": true } } } }

That refusal is the preview: it shows what binding the release would expose, with the values frozen in the release and not the application's current settings. Show them to the person who promotes, then send the request again with the confirmation:

{
  "environment": "production",
  "expected_version": 7,
  "acknowledged": { "sourcemaps": "public", "visibility": "public" }
}

Roll back#

Rollback is the same compare-and-set, limited to the retained releases of the environment:

{ "release": "rel_Prev0001x", "expected_version": 8 }

It reuses retained bytes and never re-resolves or rebuilds.

Retire#

Retiring a release that no environment binds means it can no longer be bound, and it stops protecting its closure from garbage collection. A release that is still bound answers 409 STATE_INVALID.

Garbage collection computes what is reachable from active bindings, retained releases and in-flight jobs, including shared references and lazy modules. Inactivity never breaks a published site.