Vercel — GitHub Branch Preview Workflow

How to use a dedicated Git branch (e.g. dev) for preview deployments, then promote to production — all driven by pushing to GitHub, no CLI required.

The key idea

Any branch that isn't your production branch produces a preview deployment automatically. There is no "enable previews for this branch" setting — it's the default behavior. You create the branch, push to it, and Vercel builds a preview with its own URL.

main branch    ──push──▶  Production deployment   (your live domain)
dev branch     ──push──▶  Preview deployment      (preview URL)
any-other      ──push──▶  Preview deployment      (preview URL)

So a branch becomes a "preview branch" simply by not being main.

One-time setup

1. Confirm the production branch

In the Vercel dashboard: Settings → Git → Production Branch. This is the one branch whose pushes go live (normally main). Everything else is preview by definition. You usually don't need to change this — just confirm it's main.

2. Create your preview branch

Locally, from your project root:

git checkout -b dev
git push -u origin dev

That first push triggers Vercel to build a preview deployment for dev. From now on, every push to dev updates that preview.

The everyday loop

1. Make changes on dev and push them.
2. Vercel automatically builds a preview deployment and (if GitHub integration is on) comments the preview URL on the commit / PR.
3. Open the preview URL and test your changes against the live preview environment.
4. When you're happy, promote to production (see below).

Your live site is never touched until you explicitly promote, so broken work in progress stays safely on the preview side.

Promoting to production — two paths

Path A — Merge to main (recommended)

Open a pull request from dev into main and merge it. The merge triggers a production deployment automatically.

• Pro: main always reflects exactly what's live. Your Git history is the source of truth.
• This is the conventional workflow most teams settle on.

Path B — Promote a preview directly

Go to the Deployments tab, find the dev preview deployment, click the (...) menu, and choose Promote to Production. This takes that exact build live without merging.

• Pro: no merge needed; instant.
• Watch out: main will no longer match what's live, since you promoted straight off dev. Over time this can blur "what's actually deployed." Prefer Path A unless you have a reason.

Note: promoting (either path) rebuilds using your production environment variables, so the live build isn't byte-identical to the preview if your prod/preview vars differ.

Optional: a manual gate even on main

If you want pushes to main to build but wait for your click before going live:

1. Go to Settings → Environments → Production → Branch Tracking.
2. Disable Auto-assign Custom Production Domains.

Now merging to main creates a staged production deployment that isn't live yet. Verify it, then Deployments → (...) → Promote to Production when ready.

Combined with the branch flow you get: preview on dev → merge to main builds staged → you click Promote.

Optional: a stable preview URL

By default the dev branch gets an auto-generated preview URL. To pin it to something memorable:

1. Go to Settings → Domains.
2. Add a subdomain (e.g. dev.yourtool.com) and assign it to the dev branch.

Now that URL always shows the latest push on dev — bookmarkable and shareable with colleagues.

Safety net: rollback

If something does slip through to production, go to the Deployments tab, find a previous known-good deployment, and use the (...) menu to roll back. It reassigns your domain with no rebuild, so recovery is near-instant.

Recommended setup (summary)

• Make dev your daily working branch; keep main as production.
• Give dev a branch domain so you have a fixed preview URL to test against.
• Merge dev → main (Path A) when a feature is solid.
• Add the auto-assign toggle later only if you want an extra click of control on production.