Deploy, promote and roll back releases

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).

• 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).

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).
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), 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.

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).

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). The same works for a site you deploy from a terminal (The Coritan CLI).

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

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.

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.

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).

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).

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.

• Deploy from a git repository builds a release for each push.
• The Coritan CLI lists releases, promotes and rolls back from a terminal.

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:

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.