# Roll back a deployment

Run what an earlier deployment ran again, with the environment it started with or with today's.

A rollback runs exactly what that generation ran (its image, or its pinned compose file, and its
release command) **and puts the app's environment back to what it was when that deployment
started**: every variable and every secret binding, a secret coming back at its active version.
Domains, size and machines stay as they are today.

## Prerequisites

- Permission for `deploy:DeployApp` on the app, and, when the environment is restored (the
  default for a rollback of a deployment that recorded one), `deploy:ManageEnv`.
- To bring back a secret the app does not use right now, `secrets:GetSecretValue` on it, as when
  you bind it by hand.
- In the console, also `deploy:DescribeApp` to open the app's page (without it the page is not
  found).

## Roll back

**Console**
1. Open the app's **Deployments** tab.
2. Under **Deployment history**, open the menu of the deployment's row and choose **Roll back to
   this deployment…**. The rows of what runs now have no menu. The item is unavailable, with the
   reason under it, without `deploy:DeployApp`, for a deployment that never produced an image or
   pinned a compose file, and while another deployment is in flight.
3. Read the dialog: it shows what changes against what serves now (image or compose file, commit,
   release command) and lists each variable that comes back, is removed or gets its earlier value.
   A secret's value is never shown.
4. (Optional) For **Why (optional)**, enter why you roll back.
5. Choose **Roll back to generation** _n_.

**CLI**
```sh
dcloud deploy deployments create app-id --trigger rollback \
  --from-deployment-id deployment-id --reason "Bad release"
```

Replace app-id with the app's id and deployment-id with the earlier deployment's
id (`dcloud deploy deployments list app-id`). `--no-restore-environment` keeps the
current environment.

**API**
```http
POST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/deployments
{ "trigger": "rollback", "fromDeploymentId": "7a8b9c0d-1e2f-4a3b-9c4d-5e6f7a8b9c0d", "reason": "Bad release" }
```

`"restoreEnvironment": false` runs the old image with the current environment instead.
`"trigger": "manual"` with `fromDeploymentId` does the same unless you set `restoreEnvironment` to
`true`.

**Terraform:** not available. A rollback is an action, not a resource.

## Result

A new deployment runs the earlier generation's image with its environment. The reason is shown on
the deployment next to who started it.

Refusals:

- A deployment made before environments were recorded runs with the current environment. Only an
  explicit `"restoreEnvironment": true` is refused, with `409` "Generation N predates recorded
  environments, so it cannot be restored; …". The console says so in the dialog and keeps the
  current environment.
- A secret bound in that deployment and deleted since cannot come back: `409` "The secret bound to
  KEY in that deployment no longer exists; …".
- `fromDeploymentId` of another app, or of none: `404` "The deployment to redeploy was not found on
  this app".
- An app being deleted: `409` "The app is being deleted".

The console offers no rollback while another deployment is in flight; the API does not check this.

Lifecycle rules of your registry never expire an image used by an app's live deployment or its last
ten deployments, so a rollback to one of them still pulls.

## Related

- [Deployments](deployments.md)
- `deploy.deployments.create` · `dcloud deploy deployments create`
