How to deploy to Vercel

Vercel Deployment Guide

This template ships with first-class Vercel support for Preview and Production deployments, plus PR cleanup. Use this when your project selects Vercel as the provider.

Overview

• Preview: deploy-preview.yml (on PR open/sync) → creates Neon DB branch, runs migrations, deploys to Vercel, comments Preview URL on PR
• Production: deploy-production.yml (on main) → runs CI checks, applies migrations, deploys to Vercel Prod
• Cleanup: cleanup-preview.yml (on PR close) → deletes Neon DB branch; Vercel cleanup step is scaffolded

Prerequisites

• Vercel account and project linked to this GitHub repo
• Repo Secrets/Variables
  • Secrets
    • VERCEL_TOKEN: Vercel personal token
    • NEON_API_KEY: Neon API key
  • Variables
    • NEON_PROJECT_ID: Neon project ID
    • (Optional) Any public env variables for Next.js (e.g., NEXT_PUBLIC_*)

Preview Deployments (PRs)

Workflow: .github/workflows/deploy-preview.yml

• prepare_db job
  • Creates a Neon branch named preview/pr-<PR_NUMBER>-<branch>
  • Exposes outputs: neon_branch_id, neon_branch_name, neon_db_url, pr_branch_name
  • Runs pnpm run db:migrate against the preview DB URL
• deploy_vercel job
  • Uses composite action .github/workflows/cd/vercel/deploy-preview
  • Pulls Vercel envs, builds, and deploys prebuilt artifacts
  • Outputs preview_url
• comment_pr job
  • Posts the Vercel Preview URL and Neon branch link on the PR

Required Secrets/Vars

• VERCEL_TOKEN (Secret)
• NEON_API_KEY (Secret)
• NEON_PROJECT_ID (Variable)

Notes

• The composite action already pulls Vercel envs for the Preview environment using the CLI (vercel env pull and vercel pull).
• Ensure any required runtime/build envs are configured in your Vercel project settings.

Production Deployments (main)

Workflow: .github/workflows/deploy-production.yml

• ci_checks job reuses .github/workflows/ci.yml (lint/typecheck/format)
• apply_migrations runs pnpm run db:migrate against secrets.DATABASE_URL
• deploy_vercel_production uses composite action .github/workflows/cd/vercel/deploy-production

Required Secrets

• VERCEL_TOKEN
• DATABASE_URL

Branch Protection (Recommended)

• In GitHub → Settings → Branches → Branch protection rules
  • Protect main
  • Require status checks to pass: add the workflow name CI
  • Optionally require PRs before merging

Cleanup on PR Close

Workflow: .github/workflows/cleanup-preview.yml

• Deletes the Neon branch associated with the PR
• Vercel cleanup composite is scaffolded (currently logs TODO)

Troubleshooting

• Preview URL missing in PR: verify VERCEL_TOKEN is set and the deploy job completed successfully
• Migrations failing: confirm Neon credentials and that pnpm run db:migrate runs locally with the same version
• Env variable not present at runtime: verify it exists in Vercel Project Settings for the correct environment (Preview/Production)

Edit on GitHub