Skip to Content
Platform
ShipRoll back a release

Roll back a release

Yank a version that must never serve again, or pin production to an older one.
UseWhenUndo
YankA version is bad. Every environment it served moves to the newest good build.--unyank
Pin productionA version is fine, but production should stay on an older one for now.Unpin

You need: introspection login (or, for the API, a project API key with the runtimes capability, the default for introspection api-keys create) and the version ID.

Find the version

introspection runtimes list --runtime support-agent      # what each environment runs
introspection runtimes versions <version-id>             # every version of the runtime

Every command below takes a version ID, not the slug.

Yank a bad version

introspection runtimes update <version-id> --yank --reason "approves final-sale refunds"

What happens:

  • New tasks no longer get this version.
  • Every environment it served, pinned or not, moves to the newest good default-branch build.
  • Running tasks finish on it.
  • A running experiment that uses it is stopped.

The dashboard calls this Deactivate deployment. To restore it: runtimes update <version-id> --unyank.

Pin production to a version

In the dashboard, open the runtime, choose the version, then Version actions → Pin production → Pin to commit. Unpin production returns it to the newest build.

From CI or a script, use the API:

curl -X PATCH "https://api.introspection.dev/v1/runtimes/<version-id>" \
  -H "Authorization: Bearer $INTROSPECTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment_ref": {"production": "<commit-sha>"}}'

<commit-sha> is the commit the version was built from: runtimes get <version-id> gives its recipe_id, and introspection recipes get <recipe-id> shows git_commit_sha. The API accepts any hex value, so copy the SHA exactly, then verify.

To unpin, send {"environment_ref": {"production": null}}. Production moves to the newest good default-branch build.

While production is pinned, merges reach staging only. Unpin once the fix is merged, or production keeps serving the old version.

Verify

introspection runtimes get <version-id> -o json

Check environments (where the version serves), environment_ref, and yanked_at. A commit SHA under production means production is pinned; no production entry means it follows the newest default-branch build (all rules). Then rerun a failing case in production and read its conversation.

Limits

Not supportedDo this instead
runtimes pin for productionUse the dashboard or the API above.
Pinning a yanked versionProduction stays where it is and stops taking merges. Unyank it first.
Rolling back with runtimes deleteIt deletes the whole runtime and every version. Yank instead.
Moving tasks that already startedYanks and pins affect new tasks only. Cancel running tasks if needed (Task operations).

Or ask your agent: “Production is misbehaving since the last release. Find the cause and roll it back.”

Last updated on