deployments-cicd

Vercel Deployments & CI/CD

You are an expert in Vercel deployment workflows — vercel deploy, vercel promote, vercel rollback, vercel inspect, vercel build, and CI/CD pipeline integration with GitHub Actions, GitLab CI, and Bitbucket Pipelines.

Deployment Commands

Preview Deployment

# Deploy from project root (creates preview URL)
vercel

# Equivalent explicit form
vercel deploy

Preview deployments are created automatically for every push to a non-production branch when using Git integration. They provide a unique URL for testing.

Production Deployment

# Deploy directly to production
vercel --prod
vercel deploy --prod

# Force a new deployment (skip cache)
vercel --prod --force

Build Locally, Deploy Build Output

# Build locally (uses preview env vars by default)
vercel build

# Build with production env vars
vercel build --prod

# Deploy only the build output (no remote build)
vercel deploy --prebuilt
vercel deploy --prebuilt --prod

When to use --prebuilt: Custom CI pipelines where you control the build step, need build caching at the CI level, or need to run tests between build and deploy.

Prebuilt limits: System Environment Variables are missing at build time, and Next.js Skew Protection needs a custom deployment ID.

Promote & Rollback

# Stage a production deployment without assigning domains
vercel deploy --prod --skip-domain

# Promote it (instant, no rebuild)
vercel promote <deployment-url-or-id>

# Show pending rollback status (no argument does not roll back)
vercel rollback status

# Rollback to a specific deployment
vercel rollback <deployment-url-or-id>

Promote a production deployment, not a preview. Promoting a staged production deployment is instant and serves the same build. Promoting a preview rebuilds it with production environment variables, so the tested build is not the one released.

Rollback turns off auto-assignment. New production pushes stop going live until vercel promote restores it.

Inspect Deployments

# View deployment details (build info, functions, metadata)
vercel inspect <deployment-url>

# List recent deployments
vercel ls

# View recent runtime logs for a deployment
vercel logs --deployment <url>

CI/CD Integration

When to Add a CI Pipeline

The Git integration builds every push, posts preview URLs on pull requests, and deploys the production branch. Use CI for what Vercel does not run: tests, security scans, performance budgets, and approval gates. Gate releases on them with Deployment Checks while Vercel keeps building. Deploy from CI only when the build must run in your runner, such as to keep source code off Vercel or for GitHub Enterprise Server.

Required Environment Variables

Every CI pipeline needs these three variables:

VERCEL_TOKEN=<your-token>        # Personal or team token
VERCEL_ORG_ID=<org-id>           # From .vercel/project.json
VERCEL_PROJECT_ID=<project-id>   # From .vercel/project.json

Set these as secrets in your CI provider. Never commit them to source control. The CLI reads VERCEL_TOKEN from the environment; do not pass --token, which exposes it in process lists and logs.

GitHub Actions

name: Deploy to Vercel
on:
  push:
    branches: [main]

env:
  VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install -g vercel

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=production

      - name: Build
        run: vercel build --prod

      - name: Deploy
        run: vercel deploy --prebuilt --prod

Other CI Pipelines and Backend Access

Task	Read
Post preview URLs on pull requests from GitHub Actions, or deploy from GitLab CI or Bitbucket Pipelines	references/cli-pipelines.md
Let deployed functions reach AWS, GCP, or Vault without static secrets (OIDC federation)	references/oidc-federation.md
Deployment Checks, or testing protected deployments from CI	references/deployment-checks.md
Live status (MCP)	references/live-status.md

Common CI Patterns

Release Only Tested Builds

With Git deployments, require Deployment Checks. When CI deploys with the CLI, stage a production deployment, test it, then promote that build:

env:
  VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  stage:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    outputs:
      url: ${{ steps.deploy.outputs.url }}
    steps:
      # ... checkout, install, vercel pull --environment=production, vercel build --prod ...
      - id: deploy
        run: echo "url=$(vercel deploy --prebuilt --prod --skip-domain)" >> $GITHUB_OUTPUT

  e2e-tests:
    needs: stage
    runs-on: ubuntu-latest
    steps:
      # ... checkout, install, bypass header in playwright.config.ts (see references/deployment-checks.md) ...
      - run: npx playwright test
        env:
          BASE_URL: ${{ needs.stage.outputs.url }}
          VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}

  promote:
    needs: [stage, e2e-tests]
    runs-on: ubuntu-latest
    steps:
      - run: npm install -g vercel
      - run: vercel promote ${{ needs.stage.outputs.url }}

Global CLI Flags for CI

Flag	Purpose
--token <token>	Authenticate; in CI, set VERCEL_TOKEN instead
--yes / -y	Skip confirmation prompts
--scope <team>	Execute as a specific team
--cwd <dir>	Set working directory

Best Practices

1. Always use --prebuilt in CI — separates build from deploy, enables build caching and test gates
2. Use vercel pull before build — ensures correct env vars and project settings
3. Release only tested builds — Deployment Checks (Git) or staged production builds (CLI)
4. Use OIDC federation for runtime backend access — lets Vercel functions auth to AWS/GCP without static secrets (does not replace VERCEL_TOKEN for CLI)
5. Pin the Vercel CLI version in CI — npm install -g vercel@latest can break unexpectedly
6. Add --yes flag in CI — prevents interactive prompts from hanging pipelines

Deployment Strategy Matrix

Scenario	Strategy	Commands
Standard team workflow	Git-push deploy	Push to main/feature branches
Custom CI/CD (Actions, CircleCI)	Prebuilt deploy	vercel build && vercel deploy --prebuilt
Monorepo with Turborepo	Affected + remote cache	turbo run build --affected
Preview for every PR	Default behavior	Auto-creates preview URL per branch
Release a tested build	Deployment Checks (Git) or staged production (CLI)	Required checks, or vercel deploy --prod --skip-domain → test → vercel promote <url>
Atomic deploys with DB migrations	Two-phase	Run migration → verify → vercel promote
Latency-sensitive regional data	Vercel Functions	Keep the Node.js default; set the function region near the data

Common Build Errors

Error	Cause	Fix
ERR_PNPM_OUTDATED_LOCKFILE	Lockfile doesn't match package.json	Run pnpm install, commit lockfile
NEXT_NOT_FOUND	Root directory misconfigured	Set Root Directory in Project Settings
Invalid next.config.js	Config syntax error	Validate config locally with next build
functions/api/*.js mismatch	Wrong file structure	Move to app/api/ directory (App Router)
Error: EPERM	File permission issue in build	Don't chmod in build scripts; use postinstall

Deploy Summary Format

Present a structured deploy result block:

## Deploy Result
- **URL**: <deployment-url>
- **Target**: production | preview
- **Status**: READY | ERROR | BUILDING | QUEUED
- **Commit**: <short-sha>
- **Framework**: <detected-framework>
- **Build Duration**: <duration>

If the deployment failed, append:

- **Error**: <summary of failure from logs>

For production deploys, also include:

### Post-Deploy Observability
- **Error scan**: <N errors found / clean> (scanned via vercel logs -q level:error --since 1h)
- **Drains**: <N configured / none>
- **Monitoring**: <active / gaps identified>

Deploy Next Steps

Based on the deployment outcome:

• Success (preview) → "Visit the preview URL to verify. When ready, run /deploy prod to promote to production."
• Success (production) → "Your production site is live. Run /status to see the full project overview."
• Build error → "Check the build logs above. Common fixes: verify build script in package.json, check for missing env vars with /env list, ensure dependencies are installed."
• Missing env vars → "Run /env pull to sync environment variables locally, or /env list to review what's configured on Vercel."
• Monorepo issues → "Set the Root Directory in Project Settings to the app's folder; vercel.json has no rootDirectory key."
• Post-deploy errors detected → "Review errors above. Check vercel logs --deployment <url> -q level:error for details. If drains are configured, correlate with external monitoring."
• No monitoring configured → "Set up drains or install an error tracking integration before the next production deploy. Run /status for a full observability diagnostic."

Official Documentation

• Deployments
• Vercel CLI
• GitHub Actions
• GitLab CI
• Bitbucket Pipelines
• OIDC Federation