Roll back or promote a release
Roll a service back to a release that ran before, redeploy its active release, or promote a release's image to another environment, from the console or the API.
When a release misbehaves, you roll the service back to one that ran before. When a release works in one environment, you promote its image to the next. Both start a deployment, and in a protected environment both follow the approval and freeze rules.
Before you begin
- You need the
deployerrole or higher to roll back, redeploy or promote. Approving a request in a protected environment needs theadminorownerrole. - Rollback needs a release that was healthy at some point. A release that failed, was cancelled or rejected, or was built but never deployed is not eligible. The API refuses it with a
409whose message containsrelease was never active. - The cluster keeps the three newest removed releases of a service at zero replicas. Older removed releases are no longer held on the cluster.
Roll back to an earlier release
Choose the environment in the top bar, select the service on the canvas, then open the Deployments tab. It lists releases and builds, newest first, up to 50 of each.
Find a row with the status Removed and select Rollback. The active release shows Redeploy instead. A dialog titled "Roll back SERVICE to r-N?" opens.
Read the dialog, then select Roll back. In a protected environment the dialog says the rollback waits for an admin's approval; if the organization's policy lets rollbacks skip approval, it says so instead.
A toast confirms the request. Select Watch deployment to open it. In a protected environment that waits for approval, the toast reads "Rolling back to r-N is waiting for approval" and the row shows Awaiting approval.
The rollback reuses the release's image, process settings, release command and file mounts exactly as they were frozen. Variables are not frozen: the earlier release starts with the environment's current variable values. The current release keeps serving until the earlier one passes its health checks. Then the earlier release becomes Active and the one it replaced becomes Removed. A rollback also ends the service's queued and running builds in that environment.
A rollback counts against the project's Deploy concurrency limit like any other deployment. If the project is at its limit, the rollback is refused. See Approve changes and set deploy freezes.
Redeploy the active release
Redeploy creates a new release from the active image and the environment's current configuration. Use it to apply a change to variables, processes or file mounts. It does not return to an earlier image.
On the Deployments tab, select Redeploy on the Active row. No dialog opens.
A toast reads "Redeploying r-N". A new row appears and moves through its deployment stages.
If the environment has never had a healthy release, the API answers 409 with environment has no active release to re-release.
Promote a release to another environment
Promotion creates a new release in the target environment from the source release's image digest. The new release carries the target environment's own variables and settings, not the source's.
On the Deployments tab, select the row of the release you want to carry forward. Under its details, select Promote r-N….
In the dialog, choose the environment under Promote into. The hint below it reads "Replaces r-M in ENVIRONMENT." or, for an empty environment, "ENVIRONMENT has nothing live yet — this becomes its first release." A protected target adds "Production deploys wait for an approval before they go live."
Select Promote. A toast reads "Promoting to ENVIRONMENT", or "Promotion to ENVIRONMENT is waiting for approval" when the target is protected.
To promote every service at once, open the environment menu in the top bar and select Promote staging → production. The first name is the project's last non-production environment in creation order, and the entry appears when the project also has a production environment. It shows how many services differ. Selecting it stages one release item per differing service in the production change set and opens the review. Nothing ships until you select Request approval.
What approvals and freezes apply
The rules apply only to a protected environment. A non-protected environment needs no approval and ignores deploy freezes.
| Action | Approval | During a deploy freeze |
|---|---|---|
| Roll back | Waits for an admin, unless the policy Rollbacks skip approval is on | Allowed |
| Redeploy, promote, deploy | Waits for an admin | Refused |
An admin who requests a change approves it at once only when the organization allows approving your own requests. Under the default policy a second person decides. See Approve changes and set deploy freezes.
During a freeze, a refused request returns 403 with a message that begins:
production is in a deploy freeze until Mon 08:00 UTC; rollbacks are still allowed, or change the freeze windows in the organization's policyThe time and zone name the end of the freeze in the organization's time zone.
Verify
- On the Deployments tab, the target row shows Active once its health checks pass.
- For an API request, read the deployment (
getDeployment,GET /api/v1/deployments/DEPLOYMENT_ID, with theidfrom the response'sdeployment). Itsstateishealthywhen the deployment finished, andawaiting-approvalwhile it waits for a decision.
Next steps
Create and connect a database
Create a PostgreSQL, Valkey, MySQL or MongoDB database service, connect services to it, and run queries, readers, point-in-time recovery, dump backups and restores.
Deploy a preview for each pull request
Turn on pull request previews for a project so every same-repository pull request gets its own environment, deployed from its branch and deleted when the pull request closes or goes idle.