Deploy and run
Previews and safe releases
Preview every pull request, run migrations before a release, test new versions before they take traffic, and roll out gradually with canaries.
CLI gives you several ways to catch a bad version before your users see it. Every pull request gets its own live preview. Database changes can run before the new version starts. Quick automatic tests check a new version before visitors are moved to it. A canary sends a small share of visitors to it first.
How to do it: open an app's Settings and turn on previews, a release command, smoke tests or a canary. If anything fails, the version already running keeps running.
"Turn on pull-request previews and a 10% canary for my web app."
CLI gives you several ways to catch problems before your users do: a live preview for every pull request, a release command for migrations, smoke tests that check a new version before the switch, and canary releases that try a new version on a share of traffic first. In every case, if something fails, the version that's already running keeps serving.
Pull-request previews
With previews on, every pull request into a GitHub service's tracked branch gets its own service, named <name>-pr-<n>, such as web-pr-42. It's built from the PR's head, redeployed on every push, and gets a commit status and a PR comment with its URL. The comment also compares the preview with production: build time, start time, response time, vulnerabilities and cost.
The preview is deleted when the PR closes or merges. PRs from forks aren't built. Previews use the parent service's variables and are billed like any service.
In the dashboard: open the service's Settings and turn on Preview every pull request.
Ask your agent:
"Turn on PR previews for web, with empty preview databases."
With the API:
PATCH /v1/services/:id{ "previews": true }Preview databases
Databases connected to the app get a throwaway copy for each preview, such as postgres-pr-42, on the smallest size, so previews never touch production data. They're deleted with the preview.
By default the copies start empty. To seed them from the latest backup instead, set Preview databases in the service's Settings, or:
{ "previewData": "copy" }Protected previews
To keep previews private, put them behind CLI sign-in. Project members get a 12-hour pass for that preview; anyone else needs a share link, which expires and can be revoked.
With the API:
PATCH /v1/services/:id
POST /v1/services/:previewId/share-links{ "previewAccess": "team" }Send {"hours": 72} to the share-links endpoint to make a link for someone outside the team. In the dashboard, a preview's Deploys tab has its share links.
Release commands
A release command runs once in the new image before it takes traffic. It's the place for database migrations, such as npm run migrate or npx prisma migrate deploy.
If the command fails, the deploy stops with RELEASE_COMMAND_FAILED and the last lines of its output. The new version isn't started, and the current one keeps running.
In the dashboard: open the service's Settings and fill in Release command.
With the API:
{ "releaseCommand": "npm run migrate" }Send null to remove it. You can also run a migration by hand with cli exec (see /docs/scaling).
Rehearse it first
A rehearsal runs the release command against a throwaway copy of the linked database, so you find out whether a migration works on real data before it touches production.
In the dashboard: press Rehearse on a copy of the database beside the release command.
Ask your agent:
"Rehearse the migration on web before deploying it."
With the API:
POST /v1/services/:id/rehearse
GET /v1/rehearsals/:idThe rehearsal ends as passed or failed, with the command's output.
Smoke tests
Smoke tests are requests a new version must pass before it takes traffic. For each one you give a path, and optionally a method (GET, HEAD or POST), the status you expect, and text the response must contain. You can have up to 20.
If one fails, the deploy stops with SMOKE_TEST_FAILED, naming the test and what came back. The new version never takes traffic.
In the dashboard: add them under Smoke tests in the service's Settings.
With the API:
{
"smokeTests": [
{ "path": "/healthz", "status": 200 },
{ "path": "/api/products", "contains": "sku" }
]
}Canary releases
With a canary, a new version doesn't take all the traffic at once. It starts beside the current version and gets a share of requests for a set time while CLI compares the two.
How it works:
- The new version passes its health check (and smoke tests, if any) as usual.
- Instead of switching over, CLI sends it the percentage of traffic you chose, from 1% to 50%. The deploy stays in deploying, with its canary state shown as watching.
- Every minute, CLI compares the new version's 5xx error rate and p95 response time with the current version's.
- If the new version does worse, it's rolled back on its own and the deploy fails with
CANARY_FAILED, with the numbers. By default "worse" means an error rate more than 2 points above the current version's, or a p95 more than twice the current one plus 100 ms. You can set your own limits withmaxErrorRate(a fraction, such as0.01) andmaxP95Ms. - If it's still healthy when the time is up, it's promoted and takes all the traffic.
In the dashboard: canary settings are in the service's Settings, and a running canary shows its numbers on the deploy.
Ask your agent:
"Roll out new versions of api as a canary: 10% of traffic for 10 minutes."
With the API:
PATCH /v1/services/:id{ "canary": { "percent": 10, "minutes": 10 } }Send {"canary": null} to turn canaries off. To decide early, promote or roll back a running canary yourself:
POST /v1/deploys/:id/canary{ "action": "promote" }Putting it together
A careful release for an app with a database might look like this:
- Open a pull request. The preview comes up with an empty copy of the database, and the PR comment shows how it compares with production.
- Rehearse the migration on a copy of the production database.
- Merge. The release command runs the migration in the new image.
- Smoke tests check the key pages.
- The canary takes 10% of traffic for 10 minutes, then is promoted.
If anything goes wrong after that, roll back in one click (see /docs/deploying), and see what changed with the deploy's diff.