vercel-deploy-preview

Vercel Deploy Preview

Overview

Deploy preview environments for branches and pull requests. Every git push to a non-production branch generates a unique preview URL. Covers CLI-based previews, API-based previews, deployment protection, and comment integration.

Prerequisites

• Completed vercel-install-auth setup
• Project linked via vercel link
• Git repository connected in Vercel dashboard

Instructions

Step 1: Deploy Preview via CLI

# Deploy current directory to a preview URL (default — not --prod)
vercel

# Output:
# 🔗 Linked to your-team/my-app
# 🔍 Inspect: https://vercel.com/your-team/my-app/AbCdEfG
# ✅ Preview: https://my-app-git-feature-branch-your-team.vercel.app

# Deploy a specific directory
vercel ./dist

# Deploy and wait for build to complete (useful in CI)
vercel --no-wait  # returns immediately with deployment URL

Step 2: Deploy Preview via REST API

# Create a deployment via API — useful for custom CI pipelines
curl -X POST "https://api.vercel.com/v13/deployments" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "target": "preview",
    "gitSource": {
      "type": "github",
      "repoId": "123456789",
      "ref": "feature/new-feature",
      "sha": "abc123def456"
    }
  }'

Step 3: Check Deployment Status

# Poll deployment status until READY
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v13/deployments/dpl_xxxxxxxxxxxx" \
  | jq '{state: .state, url: .url, readyState: .readyState}'

# States: QUEUED → BUILDING → READY (or ERROR/CANCELED)

// Programmatic polling
async function waitForDeployment(client: VercelClient, deploymentId: string) {
  while (true) {
    const d = await client.getDeployment(deploymentId);
    if (d.state === 'READY') return d;
    if (d.state === 'ERROR' || d.state === 'CANCELED') {
      throw new Error(`Deployment ${d.state}: ${deploymentId}`);
    }
    await new Promise(r => setTimeout(r, 5000)); // poll every 5s
  }
}

Step 4: Configure Preview Environment Variables

# Add env vars scoped to preview only
vercel env add DATABASE_URL preview
# Enter value when prompted

# Or via API — scope to preview environment
curl -X POST "https://api.vercel.com/v9/projects/my-app/env" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "DATABASE_URL",
    "value": "postgres://preview-db:5432/myapp",
    "type": "encrypted",
    "target": ["preview"]
  }'

Step 5: Deployment Protection

Vercel supports password-protecting preview deployments:

// vercel.json — require authentication for previews
{
  "deploymentProtection": {
    "preview": "vercel-authentication"
  }
}

Options:

• "vercel-authentication" — requires Vercel team login
• "standard-protection" — bypass for automation with x-vercel-protection-bypass header
• Disabled — previews are publicly accessible

Step 6: GitHub Integration — PR Comments

When a GitHub repo is connected, Vercel automatically:

1. Creates a preview deployment on every push
2. Posts a comment on the PR with the preview URL
3. Updates the GitHub commit status (pending → success/failure)
4. Adds "Visit Preview" link in the PR checks section

To configure in the Vercel dashboard:

• Settings > Git > Deploy Hooks for manual triggers
• Settings > Git > Ignored Build Step to skip builds for certain paths

# Ignored Build Step — skip deploy when only docs changed
# vercel.json
{
  "ignoreCommand": "git diff HEAD^ HEAD --quiet -- . ':!docs' ':!*.md'"
}

Preview URL Patterns

Branch	URL Pattern
feature/auth	my-app-git-feature-auth-team.vercel.app
fix/bug-123	my-app-git-fix-bug-123-team.vercel.app
Random deploy	my-app-abc123def.vercel.app

Output

• Preview deployment URL unique to each branch/commit
• Build logs accessible via Vercel dashboard or API
• PR comment with preview link (GitHub integration)
• Environment variables scoped to preview only

Error Handling

Error	Cause	Solution
BUILD_FAILED	Build command failed	Check build logs: vercel inspect <url>
FUNCTION_INVOCATION_FAILED	Runtime error in function	Review function logs: vercel logs <url>
NO_BUILDS	No output detected	Verify outputDirectory in vercel.json
Preview not updating	Cached old deployment	Force rebuild: vercel --force
DEPLOYMENT_BLOCKED	Deployment protection active	Use x-vercel-protection-bypass header

Resources

• Preview Deployments
• Deployment Protection
• CLI Deploy Command
• REST API: Create Deployment

Next Steps

For edge function development, see vercel-edge-functions.