Deployments & Environments

A deployment is a single immutable build of your project with its own permanent URL. An environment is the context a deployment runs in — which variables it sees and which domain (if any) points at it.

Immutable deployments

Every build is frozen once created and gets a unique URL. Nothing about a deployment changes after the fact; "shipping to production" simply aliases your production domain to one of these existing deployments. This is why rollbacks are instant and why old URLs keep working. (More on the mechanics in How it works.)

The three default environments

Vercel provides three environments out of the box:

Each environment can define its own environment variables — for example a test database in Preview and the real one in Production.

Preview deployments

Every push to a non-production branch, and every pull request, creates a preview deployment with a unique URL. Previews run the same infrastructure as production, so what you test is what you ship. Teammates can leave comments directly on a preview using the Vercel Toolbar.

Production deployments

Pushes to your production branch (typically main) are promoted to production and served on your production domain. You can also promote manually from the CLI or dashboard without rebuilding.

Custom environments

On Pro and Enterprise plans you can create custom environments — for example staging or qa — with their own variables and (optionally) their own branch tracking. They behave like additional named targets:

# Deploy to a custom environment named "staging"
vercel deploy --target=staging

# Pull that environment's variables and settings
vercel pull --environment=staging

Promotion and rollback

Promoting a staged production build and rolling back are just re-aliasing operations, so they're instant; promoting a preview deployment, by contrast, triggers a rebuild (preview and production use different environment variables). The full preview-to-production path — including deployment checks and gradual rollouts — is covered in Deployment workflow.

# Promote a specific deployment to production
vercel promote <deployment-url>

# Roll back to the previous production deployment
vercel rollback

# Roll back to a specific deployment
vercel rollback <deployment-url>

For staged production releases (build now, promote later) and gradual rollouts, see rolling-release.

Inspecting deployments

vercel list                       # list recent deployments
vercel inspect <deployment-url>   # details about one deployment
vercel logs <deployment-url>      # runtime logs

Full coverage of these in Managing deployments (CLI).

Related

• Deployment workflow
• Environment variables
• Domains and DNS
• CLI: deploying