Key idea
Every deploy records a version of your service. Rolling back puts an earlier version back in front of your users, so you can fix a bad release without doing it under pressure.
Versions
A version (v1, v2, v3…) is a snapshot of one release: the image plus the service's settings at that moment. It also records how the rollout went: Running if it went live, Failed if it didn't.
A new version is recorded when the service is created, when you deploy with csph deploy (even the same image again), and when a build from your repository deploys.
Restart, stop, start and scaling don't record one. Neither do settings you change in the console: they're saved on the service and captured in the next version you deploy.
One version is marked current: the one most recently put in place. After a failed deploy, the failed version is current, even though the version before it is still serving (lesson 5.7.2). That's the moment to roll back.
What a rollback does
Rolling back redeploys the service from an earlier version's snapshot and marks that version current. It doesn't record a new version.
| Rollback restores, from that version | Rollback keeps, as it is now |
|---|---|
| The image | The spherelet count |
| Variables and secrets | Autoscaling settings |
| Port and health check | The URL and custom domains |
Secrets go back too. If you rotated a leaked secret after that version, set it again once the rollback is done.
A rollback is refused while the service is mid-action (Deploying, Redeploying, Restarting, Stopping or Starting). Wait for it to finish or fail.
Check yourself
Roll back
Open the service, choose ⋯ in its header, then Roll back. The dialog lists your versions, newest first:
Roll back hello-web
Select a version to restore:
v3 27/09/2026, 14:02 current (dimmed)
● v2 27/09/2026, 13:40
○ v1 27/09/2026, 13:15
The current version is dimmed; up to five earlier ones are listed, with the most recent selected. Pick one and choose Roll back to v2 (the button names your pick).
csph deployments rollback <deployment-id>
This rolls back to the version before the current one, then waits for the service to be running. csph can't list versions yet, so to pick a specific one, use the console.
“The version before” is counted from the current one, so running it twice goes back two versions, not back and forth.
The service redeploys from that version and returns to Running when it's healthy.
Roll back first, investigate second
- Roll back to the last version that was Running.
- Confirm the service is Running and answering.
- Investigate the failed version's deploy log and runtime log, with no users waiting.
- Ship the fix as a new deploy, which records a new version.
API routes, and rollback with automatic deploys
Through the API, GET /deployments/{id}/versions lists a service's versions with their status, GET /deployments/{id}/versions/current returns the current one, and POST /deployments/{id}/rollback with {"deployment_id": "<version-id>"} rolls back.
Automatic deploys on push are coming. When they arrive, a rollback pauses them so your next push doesn't replace the version you restored.