Roll back to an earlier release with the Apps API

Roll back when a new version misbehaves and you want the one before it back. A rollback is a new release of an earlier release's build output or image, so it skips the build and goes live as soon as its replicas are healthy. The API names a release deployment, in its paths and its objects.

In the dashboard, Roll back to this… on a release of the app's Releases tab does the same (Roll back). This page covers the Apps API, which scripts written for Apps keep using.

• Send your access token as Authorization: Bearer $CORITAN_TOKEN (Authentication). The request takes the app's uuid and the uuid of the release you want back, which the app's history lists (List releases).
• The app must be active.
• The release you roll back to must have gone live at some point, and must not be the live release. Its can_rollback field says whether it qualifies.
• For an organization's app, you need the owner or admin role in the organization.

POST /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/rollback rolls the app back to the release in the path. For an organization's app, send it to POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/rollback.

curl -X POST https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21/deployments/8c4e1a7d-2f9b-4d6e-b3a8-6e1f9c2d5a10/rollback \
  -H "Authorization: Bearer $CORITAN_TOKEN"

It answers 201 with the new release in deployment:

{
  "deployment": {
    "uuid": "6a2f9d1c-4e8b-4b7a-a5c3-9d0e1f2a3b4c",
    "status": "deploying",
    "source": "rollback",
    "trigger": "rollback",
    "git_ref": "main",
    "git_sha": "3e7d2c1b0a9f8e7d6c5b4a3928170f6e5d4c3b2a",
    "image_ref": null,
    "artifact_sha256": "8c4e1a7d2f9b4d6eb3a86e1f9c2d5a108c4e1a7d2f9b4d6eb3a86e1f9c2d5a10",
    "artifact_size": 48220416,
    "runtime_image": "ghcr.io/parkervcp/yolks:nodejs_22",
    "regions": ["fra", "iad"],
    "is_current": false,
    "in_flight": true
  }
}

The example shortens the release (App and release fields). The live release keeps serving until the new one is ready.

A rollback runs the earlier release's build output, or an image app's image, so the code and every value the build read are as they were when it was built. The variables the running app reads, the regions and the number of replicas in each come from the app as it is now. A static site gets the earlier release's files back instead, served at once, and a hybrid site its files with its build output.

Replicas of the earlier release that we have not removed yet start again instead of new ones, which makes the rollback quicker. We remove a replica 30 minutes after it stops taking requests (Going live).

The push webhook keeps working after a rollback, so the next push to the app's branch deploys that push. To keep the old version running, stop pushing to the branch, or fix the problem and push the fix.

A new release appears first in the app's history, with the earlier release's commit, and its source and trigger are both rollback. The Releases tab reads it as Rollback. It goes live once its replicas are healthy, like any other release, and the one it replaces becomes superseded, which the dashboard shows as Replaced. If the rollback fails, the live release keeps serving.

• Deploy an app with the Apps API
• Read a release and its build log with the Apps API
• How the Apps API runs an app