# Deploy, promote and roll back releases

> Start a release, follow its build, promote a preview, roll back to an earlier release, and send part of the traffic to a new one first.

Source: https://www.coritan.com/docs/managed-containers/releases/

In the dashboard:

- /dashboard/deployments/…/releases: https://www.coritan.com/dashboard/deployments

A *release* is one version of a deployment: a build of a commit, a container image, or the files of a static site. Each push to the production branch starts one, and you can start one yourself. A new release builds and starts beside the release serving now, which keeps serving until the new one passes its health check, so visitors never see the switch. The **Releases** tab lists every release, production and previews, newest first.

A game server or a database has no releases: you change its software on its **Software** tab instead ([Change the server software](/docs/managed-containers/software/)).

## Before you begin

- The deployment builds from a git repository or runs a container image, or it is a static site or a hybrid site.
- Builds use build minutes from your plan's monthly allowance, and your plan sets how many of your builds run at once; the rest wait their turn ([How App Deployment is billed](/docs/managed-containers/how-billing-works/)).

## Start a release {#start-a-release}

1. Open the deployment and select **Deploy…**.
2. For a deployment built from git, type a branch, a tag or a commit under **Branch, tag or commit**, or leave it empty to build the newest commit on the production branch. A commit takes its full ID. For an image, type the image under **Image**, or leave it empty to pull the current one again.
3. For a deployment built from git, choose where the release goes. **Production** takes over from the release serving now once it is ready. **Preview**, which a branch other than the production branch picks for you, builds that branch at its own address and leaves production as it is; it needs previews turned on ([Turn on previews](/docs/managed-containers/deploy-from-git/#turn-on-previews)).
4. Select **Deploy**, or **Deploy preview**.

The release's page opens with its build log, which follows the build as it is written. Secret values are hidden in the log. A release is queued, then built in a build container of its own ([How a release is built](/docs/managed-containers/deploy-from-git/#how-it-builds)), then its instances start, and it goes live once they pass their health check. Its **Details** show the **Runtime** its instances run on, such as Node 22, and the size of its **Build output**; a release of a container image shows the **Image** instead.

To run the current release again with the settings and variables saved now, select **Redeploy…**. It reuses the current build unless you tick **Build it again**, which you need after changing a build setting or a variable the build reads.

## Promote a preview {#promote-a-preview}

A preview that is ready can go to production as it is, without building it again. Open it on the **Releases** tab and select **Promote to production…**. Production moves to it once its instances pass their health check, and the preview keeps answering at its own addresses ([Turn on previews](/docs/managed-containers/deploy-from-git/#turn-on-previews)).

## Roll back {#roll-back}

To put production back on an earlier release that went live, open it on the **Releases** tab and select **Roll back to this…**. We make a new release of that release's build, without building anything: its build output, or its image for a web service that runs one, its files for a static site, and both for a hybrid site. A static site serves those files at once, and the others move production to the new release once its instances are ready. A later push starts a new release as usual, so pause pushes to the production branch if you need production to stay where it is.

A static site keeps each release's files for at least 30 days, so roll it back within those days ([Limits](/docs/managed-containers/static-sites/#limits)). The same works for a site you deploy from a terminal ([The Coritan CLI](/docs/managed-containers/cli/)).

## Cancel a release {#cancel-a-release}

A release that is still queued, building or starting can be stopped with **Cancel release…**. The release serving now carries on.

## Send part of the traffic to a new release {#canary}

A *canary* gives a newer production release a share of the traffic, from 1% to 99%, while the current release takes the rest. Watch its errors on the **Metrics** tab, then promote it to take all the traffic, or abort it to send everyone back.

- A visitor stays on the release they were given for an hour, so their pages, assets and API calls never mix two releases.
- Nothing is cached at the edge while two releases share an address.
- One canary at a time: promote or abort it before starting another.

## Result

The **Releases** tab marks the release production serves as **Current**. A release that was replaced says **A newer release replaced this one**, and a failed release keeps its build log, with production still on the release before it.

## Troubleshooting

The release failed while building
: Open it and read the **Build log**. The last lines usually name the command that failed. Fix it and push, or select **Deploy…** again.

The release built, but never went live
: Its instances did not pass their health check. Check that the app listens on the port in `PORT` and answers the health check path, and read the instances' output under **Logs** ([Logs and metrics](/docs/managed-containers/logs-and-metrics/)).

Builds wait before they start
: Your plan's builds at once are all running, or the month's build minutes are used up and the deployment is set to **Stop at the allowance** ([At a limit](/docs/managed-containers/how-billing-works/#at-a-limit)).

`Too many releases or placement changes for this deployment. Wait a few minutes.`
: A deployment can start 30 releases or placement changes in 10 minutes.

**Roll back to this…** is not offered
: Only an earlier production release that went live can be rolled back to. A preview goes to production with **Promote to production…** instead.

`Only a release that was ready once can be rolled back to`
: The release never went live, such as one that failed or was cancelled, so there is nothing of it to go back to. Roll back to a release that went live, or select **Deploy…** and type its commit under **Branch, tag or commit** to build it again. The dashboard offers **Roll back to this…** only where it works, so this comes from the API or the CLI.

## Related

- [Deploy from a git repository](/docs/managed-containers/deploy-from-git/) builds a release for each push.
- [The Coritan CLI](/docs/managed-containers/cli/) lists releases, promotes and rolls back from a terminal.

## With the API

The routes are under `/api/v1/client/deployments/{uuid}` for your own deployment and `/api/v1/orgs/{org_slug}/deployments/{uuid}` for an organization's. Any member of an organization reads them; owners and admins start and change releases.

`POST /releases` starts a release, with `git_ref` (a branch, a tag or a commit) or `image_ref`, or neither for the defaults:

```bash
curl -X POST https://api.coritan.com/api/v1/client/deployments/$DEPLOYMENT/releases \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"git_ref": "main"}'
```

`GET /releases` lists them, newest first, and `GET /releases/{release}` answers one with its instances. A release built from git or an upload has `artifact_size` (its build output, in bytes), `artifact_sha256` and `runtime_image`, and its `image_ref` is `null`; a release of a container image has `image_ref`. `GET /releases/{release}/log` answers the end of its build log. `POST /releases/{release}/promote`, `/rollback` and `/cancel` do what the buttons do, and `POST /redeploy` takes `{"rebuild": true}` to build again.

`PUT /canary` with `{"release": "<uuid>", "traffic_percent": 10}` gives that release its share, and without `release` changes the share of the canary there is. `POST /canary/promote` and `POST /canary/abort` end it; send the canary's `release` with either, so you never act on a canary that changed since you read it.

## API

- `GET /api/v1/client/deployments/{deployment_uuid}/releases`: The deployment's releases, newest first, production and preview alike (https://www.coritan.com/docs/api/reference/client/deployments/deployments-releases/#op-get-api-v1-client-deployments-deployment-uuid-releases)
- `POST /api/v1/client/deployments/{deployment_uuid}/releases`: Create release (https://www.coritan.com/docs/api/reference/client/deployments/deployments-releases/#op-post-api-v1-client-deployments-deployment-uuid-releases)
- `GET /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}`: One release with each of its instances (instancelist) (https://www.coritan.com/docs/api/reference/client/deployments/deployments-releases/#op-get-api-v1-client-deployments-deployment-uuid-releases-release-uuid)
- `POST /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/cancel`: Cancel release (https://www.coritan.com/docs/api/reference/client/deployments/deployments-releases/#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-cancel)
- `GET /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/log`: The end of the release's build log, secrets redacted as it was written (https://www.coritan.com/docs/api/reference/client/deployments/deployments-releases/#op-get-api-v1-client-deployments-deployment-uuid-releases-release-uuid-log)
- `POST /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/promote`: Promote release (https://www.coritan.com/docs/api/reference/client/deployments/deployments-releases/#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-promote)
- `POST /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/rollback`: Rollback release (https://www.coritan.com/docs/api/reference/client/deployments/deployments-releases/#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-rollback)
- `POST /api/v1/client/deployments/{deployment_uuid}/redeploy`: Redeploy (https://www.coritan.com/docs/api/reference/client/deployments/deployments/#op-post-api-v1-client-deployments-deployment-uuid-redeploy)
- `GET /api/v1/client/deployments/{deployment_uuid}/canary`: Get canary (https://www.coritan.com/docs/api/reference/client/deployments/deployments-canary/#op-get-api-v1-client-deployments-deployment-uuid-canary)
- `PUT /api/v1/client/deployments/{deployment_uuid}/canary`: Start or change a canary (https://www.coritan.com/docs/api/reference/client/deployments/deployments-canary/#op-put-api-v1-client-deployments-deployment-uuid-canary)
- `POST /api/v1/client/deployments/{deployment_uuid}/canary/abort`: Abort canary (https://www.coritan.com/docs/api/reference/client/deployments/deployments-canary/#op-post-api-v1-client-deployments-deployment-uuid-canary-abort)
- `POST /api/v1/client/deployments/{deployment_uuid}/canary/promote`: Promote canary (https://www.coritan.com/docs/api/reference/client/deployments/deployments-canary/#op-post-api-v1-client-deployments-deployment-uuid-canary-promote)
- `GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/releases`: The deployment's releases, newest first, production and preview alike (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-releases/#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-releases)
- `POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/releases`: Create release (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-releases/#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-releases)
- `GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/releases/{release_uuid}`: One release with each of its instances (instancelist) (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-releases/#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-releases-release-uuid)
- `POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/releases/{release_uuid}/cancel`: Cancel release (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-releases/#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-releases-release-uuid-canc)
- `GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/releases/{release_uuid}/log`: The end of the release's build log, secrets redacted as it was written (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-releases/#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-releases-release-uuid-log)
- `POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/releases/{release_uuid}/promote`: Promote release (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-releases/#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-releases-release-uuid-prom)
- `POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/releases/{release_uuid}/rollback`: Rollback release (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-releases/#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-releases-release-uuid-roll)
- `POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/redeploy`: Redeploy (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-redeploy)
- `GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary`: Get canary (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-canary/#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-canary)
- `PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary`: Start or change a canary (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-canary/#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-canary)
- `POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary/abort`: Abort canary (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-canary/#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-canary-abort)
- `POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary/promote`: Promote canary (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-canary/#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-canary-promote)