deployments-cicd

Getting a project live on Vercel and back off again: a preview or production build; from your own machine or from an automated pipeline; promoting one that passed review; and rolling back to an earlier version when it did not.

WHEN TO USE

SCOPE

USE FOR

Deploy a project to a preview URL or straight to production from the CLI.
Wire a GitHub Actions, GitLab, or Bitbucket pipeline that deploys to Vercel.
Promote a validated preview deployment to production without rebuilding.
Roll back production to the previous or a specific past deployment.
Diagnose a failed build from a stale lockfile or misconfigured root directory.

NOT FOR

Authenticating CLI deploys in CI — OIDC federation does not replace a deploy token.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (11)

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>

# Rollback to the previous production deployment
vercel rollback

# 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 logs for a deployment
vercel logs <deployment-url>
vercel logs <deployment-url> --follow

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

Always use --prebuilt in CI — separates build from deploy, enables build caching and test gates
Use vercel pull before build — ensures correct env vars and project settings
Release only tested builds — Deployment Checks (Git) or staged production builds (CLI)
Use OIDC federation for runtime backend access — lets Vercel functions auth to AWS/GCP without static secrets (does not replace VERCEL_TOKEN for CLI)
Pin the Vercel CLI version in CI — npm install -g vercel@latest can break unexpectedly
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 --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 <url> --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

Account or credentials required

1 FOR YOU

01
Add your Vercel token and project IDs as CI secrets
Set VERCEL_TOKEN, VERCEL_ORG_ID, and VERCEL_PROJECT_ID (the latter two from .vercel/project.json) as secrets in your CI provider before any pipeline step runs.
You set: VERCEL_TOKEN

Setup details: Expect some account or credential setup.

This skill ships inside the Vercel Plugin. Listed package contents include 4 slash commands, 3 agents, hooks and an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add vercel/vercel-plugin --skill "deployments-cicd" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Vercel Plugin package selected for your AI tool.

Run this command in a terminal

npx plugins add vercel/vercel-plugin

Plugins CLI 1.3.4 sends an install report by default, including the source exactly as entered, plugin names, target tools and scope; it does not check whether repositories are public or private. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable this report. For data sent by an installed plugin, check that plugin's documentation.

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub