Deployment Workflow

Ship to preview first, gate releases with deployment checks, and promote to production deliberately — including staged builds, rolling releases, and skew protection.

By default Vercel ships fast: merge to your production branch and the build goes straight to your production domain. That's convenient, but it means the exact code serving your users may not be the code that was reviewed. This page covers the safer path — rehearse in preview, gate the release with checks, and promote on purpose.

The default flow

Out of the box the lifecycle is:

push / merge to production branch  ->  Vercel builds  ->  build succeeds  ->  auto-promoted to production domain

Vercel automatically promotes the most recent successful production build to your production domain. Everything below is about inserting deliberate steps into that flow.

Two ways to "go to preview first"

There are two distinct mechanisms, and it's worth keeping them straight:

Git preview deployments — every non-production branch and pull request automatically gets its own deployment on a unique URL. This is where day-to-day review happens.
Staged production builds — even on the production branch, you can stop Vercel from auto-serving the build, so a production deployment waits in a staged state until you promote it by hand.

Preview deployments (branches & PRs)

Push a branch or open a PR and Vercel builds a preview on a unique URL, running the same infrastructure as production. Use it for QA and for leaving review comments via the Toolbar. The CLI equivalents:

vercel deploy          # preview deployment
vercel deploy --prod   # production deployment

Staged production builds (manual promotion)

If you want a production-grade build to exist and be testable before it serves any real traffic, turn off automatic domain assignment for production (Project → Settings → Git / Production). Now pushes to your production branch build as normal but land in a Staged state instead of going live.

Production deployments are in one of these states:

State	Meaning
Staged	A commit was pushed to the production branch but no production domain is assigned yet. Can be promoted to Current.
Current (Promoted)	The deployment serving production traffic. A deployment that has already been promoted can't be promoted again — use a rollback to reuse it.

The advantage of a staged production build is that it's already built with your production environment variables, so promoting it is an instant alias swap with no rebuild (more on that below).

Deployment Checks

Deployment Checks are automated safety checks that run after a deployment is built and live, but before it's released to production. They're distinct from build checks — compile errors, missing env vars, a failing build script — which fail the deployment before it ever reaches the "ready" state. Deployment Checks verify the running application.

The workflow with checks enabled:

push to production branch  ->  production deployment created (ready)  ->  checks run  ->  all pass  ->  released to production

Once all checks pass, Vercel aliases the deployment to your production domain(s) automatically (this requires automatic production aliasing to be on).

Where checks come from

There are three sources, and you can combine them:

Native Deployment Checks (Vercel). Vercel clones your repo, installs dependencies, and runs scripts from your package.json — no external CI needed. It looks for a lint script for the lint check, and typecheck, type-check, or check-types for the typecheck. If no matching script exists, that check is simply skipped.
GitHub Checks. With Vercel for GitHub connected, Vercel reads your commit statuses and selected GitHub Actions results and can block promotion until they pass.
Integration Checks. Marketplace integrations (Lighthouse for performance/accessibility, Checkly for synthetic monitoring, E2E testing integrations, etc.) register checks automatically on every deployment.

Required checks and how they gate

In project settings you can mark a check as Required. A failed required check prevents the deployment from being promoted to production. Under the hood, integration checks use the Checks API: when a deployment becomes ready, Vercel fires a webhook to each registered integration; the integration registers a check in a running state (a spinner appears next to the deployment), does its work, then reports a conclusion of succeeded or failed (green check or red). A red required check blocks the release.

If you need to ship despite a failing or pending check, use Force Promote from the deployment details page to bypass.

Promoting to production

When checks are green (or you're promoting manually), promote the build.

Dashboard: Deployments → the ⋯ menu on the target deployment → Promote to Production. The dialog tells you which domain(s) will be linked.

CLI, with verification around it:

# 1. Find deployments that finished building
vercel list --status READY

# 2. Inspect the one you intend to ship
vercel inspect <deployment-url>

# 3. Smoke-test it directly (before it serves real traffic)
vercel curl /api/health --deployment <deployment-url>
vercel logs --deployment <deployment-url> --level error --limit 50

# 4. Promote (--yes skips the confirmation prompt)
vercel promote <deployment-url> --yes
vercel promote status

# 5. Verify production after the swap
vercel logs --environment production --level error --since 5m

The rebuild nuance (important)

Whether promotion is instant depends on what you're promoting:

Staged production build → production: instant alias swap, no rebuild. It was already built with production environment variables.
Instant rollback to a deployment that previously served production: also instant, no rebuild (but note that since nothing rebuilds, environment variables are not re-evaluated — you get exactly what that deployment shipped with).
Preview deployment → production: triggers a full rebuild, because the preview was built with preview environment variables and production needs the production ones. You can't carry preview variables into a production deployment.

This is why the staged-build pattern is the cleaner "test the real thing, then flip it live" workflow: the artifact you tested is the exact artifact that goes live.

Gradual rollout: Rolling Releases

For higher-risk changes you can release to a fraction of traffic first. Rolling Releases are available on Pro (one project) and Enterprise. Instead of serving a new deployment to everyone at once, Vercel routes a configurable share (say 5%) to it while the rest stays on the previous production deployment, and shows you a metrics comparison (Speed Insights and your own observability) between the two.

You configure two or more stages, each sending a larger fraction than the last, with the final stage always at 100%. Many projects just use one fractional stage before full promotion. Once enabled, any promote action — a push, the dashboard Promote button, or vercel promote — starts a rolling release. You then advance it stage by stage, or abort (via the Abort button or an Instant Rollback). The CLI commands are covered in Managing deployments.

Skew Protection

During any rollout you can briefly have two versions live at once, which risks a client loading version A's assets but hitting version B's backend. Skew Protection pins each client to the deployment version it originally loaded, so client and server code always match. Enable it in project settings — it's strongly recommended whenever you use Rolling Releases.

A solid default setup

Putting it together for an internal tool you want to ship carefully:

Turn off auto-promotion so production builds stage instead of going live.
Enable native lint + typecheck checks (add a Lighthouse or E2E integration if you want more coverage) and mark the ones that matter Required.
On green checks, vercel promote the staged build — instant, no rebuild.
For bigger changes, promote through a Rolling Release and keep Skew Protection on.

Deployment Workflow

On this page