deployments-cicd

Vercel deployment and CI/CD expert guidance. Use when deploying, promoting, rolling back, inspecting deployments, building with --prebuilt, or configuring CI…

view source

installs

stars

karma

view original SKILL.md from skills.shclick to expand

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 development 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.

Promote & Rollback

# Promote a preview deployment to production
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 vs deploy --prod: promote is instant — it re-points the production alias without rebuilding. Use it when a preview deployment has been validated and is ready for production.

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

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.

GitHub Actions

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

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 --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

OIDC Federation (Secure Backend Access)

Vercel OIDC federation is for secure backend access — letting your deployed Vercel functions authenticate with third-party services (AWS, GCP, HashiCorp Vault) without storing long-lived secrets. It does not replace VERCEL_TOKEN for CLI deployments.

What OIDC does: Your Vercel function requests a short-lived OIDC token from Vercel at runtime, then exchanges it with an external provider's STS/token endpoint for scoped credentials.

What OIDC does not do: Authenticate the Vercel CLI in CI pipelines. All vercel pull, vercel build, and vercel deploy commands still require --token=${{ secrets.VERCEL_TOKEN }}.

When to use OIDC:

Serverless functions that need to call AWS APIs (S3, DynamoDB, SQS)

Functions authenticating to GCP services via Workload Identity Federation

Any runtime service-to-service auth where you want to avoid storing static secrets in Vercel env vars

GitLab CI

deploy:
  image: node:20
  stage: deploy
  script:
    - npm install -g vercel
    - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
    - vercel build --prod --token=$VERCEL_TOKEN
    - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN
  only:
    - main

Bitbucket Pipelines

pipelines:
  branches:
    main:
      - step:
          name: Deploy to Vercel
          image: node:20
          script:
            - npm install -g vercel
            - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
            - vercel build --prod --token=$VERCEL_TOKEN
            - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN

Common CI Patterns

Preview Deployments on PRs

# GitHub Actions
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g vercel
      - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy
        run: echo "url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT
      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Preview: ${{ steps.deploy.outputs.url }}`
            })

Promote After Tests Pass

jobs:
  deploy-preview:
    # ... deploy preview ...
    outputs:
      url: ${{ steps.deploy.outputs.url }}

  e2e-tests:
    needs: deploy-preview
    runs-on: ubuntu-latest
    steps:
      - run: npx playwright test --base-url=${{ needs.deploy-preview.outputs.url }}

  promote:
    needs: [deploy-preview, e2e-tests]
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - run: npm install -g vercel
      - run: vercel promote ${{ needs.deploy-preview.outputs.url }} --token=${{ secrets.VERCEL_TOKEN }}

Global CLI Flags for CI

Flag
Purpose

--token <token>
Authenticate (required in CI)

--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

Prefer promote over re-deploy — instant, no rebuild, same artifact

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 --remote-cache

Preview for every PR
Default behavior
Auto-creates preview URL per branch

Promote preview to production
CLI promotion
vercel promote <url>

Atomic deploys with DB migrations
Two-phase
Run migration → verify → vercel promote

Edge-first architecture
Edge Functions
Set runtime: 'edge' in route config

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 rootDirectory 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 → "Ensure the correct project root is configured in Vercel project settings. Check vercel.json for rootDirectory."

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

Deployments

Vercel CLI

GitHub Actions

GitLab CI

Bitbucket Pipelines

OIDC Federation

don't have the plugin yet? install it then click "run inline in claude" again.

intent

master vercel's deployment pipeline end-to-end. use this skill when you need to deploy preview or production builds, promote tested previews to production, rollback failed deploys, inspect deployment metadata, or integrate vercel into github actions, gitlab ci, or bitbucket pipelines. covers local builds with --prebuilt, oidc federation for runtime service auth, and deployment strategy selection based on your workflow (git-push, custom ci, monorepo).

inputs

vercel cli

vercel cli installed globally or in ci environment (npm install -g vercel@X.Y.Z, pin version in ci)
project initialized with vercel (vercel link or .vercel/project.json present)

authentication & secrets (ci pipelines)

VERCEL_TOKEN: personal or team token from account settings (https://vercel.com/account/tokens)
VERCEL_ORG_ID: organization id from .vercel/project.json
VERCEL_PROJECT_ID: project id from .vercel/project.json
store all three as secrets in your ci provider (github secrets, gitlab variables, bitbucket repository variables)
never commit tokens to source control

environment variables

pull production/preview env vars with vercel pull --yes --environment=<production|preview>
or manually set them in ci as secrets
env vars with "Sensitive" flag are only available at deploy time, not in vercel pull output

external integrations (optional)

github integration: required for auto preview deploys on non-main branches (configured in vercel dashboard)
gitlab ci / bitbucket pipelines: self-hosted or saas runners with node.js 18+ and npm/yarn/pnpm
oidc federation (aws, gcp, hashicorp vault): configure in vercel project settings > oidc federation to allow vercel functions to request short-lived tokens at runtime

git context

commit sha, branch name (used for deploy metadata and rollback targeting)
for promote strategy, need the preview deployment url or id from prior build

procedure

1. preview deployment (automatic or manual)

inputs: git push to non-production branch (with git integration enabled), or run vercel from local project root

steps:

if using git integration: push to branch -> vercel auto-creates preview url
if manual: cd to project root -> run vercel (or vercel deploy) -> unique preview url generated
preview url format: https://--.vercel.app

outputs: preview url, deployment id, build logs

edge cases:

git integration not enabled: manual preview deploy still works, but no auto-deploys on push
preview env vars not synced: run vercel pull --yes --environment=preview before build
network timeout during deploy: cli will retry; if hung, ctrl-c and retry

2. production deployment (direct or prebuilt)

option a: direct production deploy

inputs: project root with all source code, production env vars available locally

steps:

cd to project root
run vercel --prod (or vercel deploy --prod)
vercel pulls env vars, builds remotely, deploys to production alias
deployment becomes live at yourdomain.com

outputs: production url, build logs, deployment id

edge case: force rebuild (skip cache): vercel --prod --force

option b: prebuilt production deploy (recommended for ci)

inputs: project root with vercel.json, node_modules or lock file, ci environment with VERCEL_TOKEN / VERCEL_ORG_ID / VERCEL_PROJECT_ID set

steps:

run vercel pull --yes --environment=production --token=$VERCEL_TOKEN (syncs env vars and project config)
run vercel build --prod --token=$VERCEL_TOKEN (builds locally, outputs to .vercel/output)
optionally: run tests, lint, security checks against .vercel/output
run vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN (deploys pre-built artifact, no remote build)
deployment becomes live at yourdomain.com

outputs: production url, build logs, deployment id

edge cases:

build step uses development env vars by default; --prod flag switches to production env vars
.vercel/output directory must exist and be valid before deploy; if corrupted, rebuild
rate limit (10 deploys per 60 seconds): wait before retrying
auth token expired or invalid: vercel deploy will fail with 401; refresh token in ci secrets

3. promote preview to production (zero-downtime, no rebuild)

inputs: deployment url or id from prior preview deploy, VERCEL_TOKEN in ci (or cli authenticated locally)

steps:

run vercel promote --token=$VERCEL_TOKEN
vercel re-points the production alias to the preview deployment
no rebuild occurs; same artifact goes live instantly

outputs: confirmation message, production url now points to promoted deployment

edge case: if deployed code is stale or has issues, rollback is fastest fix (vercel rollback)

4. local build with vercel build

inputs: project root with package.json, lock file, .vercelignore (optional)

steps:

run vercel build (uses development env vars by default)
or run vercel build --prod (uses production env vars from .env.production or vercel dashboard)
output written to .vercel/output (build cache, static files, serverless function metadata)
inspect output: ls -la .vercel/output

outputs: .vercel/output directory, build logs, exit code (0 on success)

edge cases:

lock file mismatch (pnpm): run pnpm install, commit updated lock file
next_not_found: project root misconfigured; check vercel.json rootDirectory or project settings
missing env var at build time: run vercel pull --yes --environment= first
disk space exhausted: ci image may need larger storage allocation

5. rollback to previous production deployment

inputs: VERCEL_TOKEN, deployment id (optional, only if rolling back to specific deploy)

steps:

to rollback to immediately previous deployment: run vercel rollback --token=$VERCEL_TOKEN
to rollback to a specific deployment: run vercel rollback --token=$VERCEL_TOKEN
vercel re-points production alias to the prior (or specified) deployment
old code becomes live; no rebuild

outputs: confirmation message, production alias now points to previous deployment

edge case: rollback fails if the target deployment was deleted or is unavailable; use vercel ls to find alternative deployment id

6. inspect deployment metadata

inputs: deployment url or id

steps:

run vercel inspect --token=$VERCEL_TOKEN (shows build time, env vars, function details, metadata)
or run vercel ls --token=$VERCEL_TOKEN (lists recent deployments with status and timestamps)
or run vercel logs --token=$VERCEL_TOKEN (streams deployment logs)
for live tail: vercel logs --follow --token=$VERCEL_TOKEN
filter by level: vercel logs --level error --token=$VERCEL_TOKEN

outputs: json metadata, function list, log stream

edge cases:

deployment is deleted: logs unavailable; inspect and promote only work on live deployments
logs older than 3 days: not retained in free tier; check project settings for log retention upgrade
follow mode will hang until ctrl-c; use in ci with timeout

7. ci pipeline integration (github actions example)

inputs:

github secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID
github branch context (github.ref)
upstream artifacts (optional): test results, build outputs

steps:

trigger on push to main or pull_request event
checkout code: actions/checkout@v4
install vercel cli: npm install -g vercel@
pull vercel env: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
build locally: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
run tests (optional): npm test, npx playwright test (use .vercel/output or deployed preview url)
deploy prebuilt: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
capture output: url=$(vercel deploy ...) >> $GITHUB_OUTPUT or export to next step

outputs: github actions job status, deployment url in logs or workflow output

edge cases:

workflow times out (default 6 hours): build or deploy hung; add timeout-minutes: 30 to step
secrets not available: ensure VERCEL_TOKEN is set in github > settings > secrets
concurrent deploys: vercel will queue; check deployment status with vercel ls or inspect

8. ci pipeline integration (gitlab ci / bitbucket pipelines)

gitlab ci:

inputs: gitlab runner with node.js 18+, gl variables: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID

steps:

image: node:20
script: npm install -g vercel@
vercel pull --yes --environment=production --token=$VERCEL_TOKEN
vercel build --prod --token=$VERCEL_TOKEN
vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN
only: [main]

bitbucket pipelines:

inputs: bitbucket repository variables: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID

steps:

image: node:20
step script: same as gitlab ci above
trigger on branch: main

outputs: pipeline status, deployment url in logs

edge cases:

variable interpolation: $VERCEL_TOKEN (gitlab), $VERCEL_TOKEN (bitbucket) or $(VERCEL_TOKEN) depending on runner
docker image size: add caching (npm ci vs npm install) to speed up
self-hosted runners: ensure outbound https to vercel.com is allowed

9. preview deployments on pull requests

inputs: pull_request event, upstream preview deployment url, playwright or e2e test suite

steps:

trigger on pull_request opened / synchronize
vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
vercel build --token=${{ secrets.VERCEL_TOKEN }} (builds without --prod flag, uses preview env vars)
vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }} (deploys to preview, outputs url)
capture url: echo "url=$(vercel deploy ...)" >> $GITHUB_OUTPUT
comment on pr: github.rest.issues.createComment with preview url
downstream job runs e2e tests: npx playwright test --base-url=${{ preview_url }}

outputs: github pr comment with preview url, test results

edge cases:

pr from fork: secrets may not be available; use github's pull_request_target event with caution
preview url expires after 30 days of no deploys; redeploy to refresh
rate limiting: 10 deploys per 60 seconds across team; queue if hit

10. promote after tests pass

inputs: prior preview deployment url (from step 9), e2e test results passing, main branch context

steps:

deploy-preview job: outputs preview url
e2e-tests job: depends_on deploy-preview, runs tests against preview url, passes
promote job: depends_on [deploy-preview, e2e-tests], only if github.ref == 'refs/heads/main' and e2e-tests passed
run: npm install -g vercel@
run: vercel promote ${{ preview_url }} --token=${{ secrets.VERCEL_TOKEN }}
production alias now points to validated preview; zero downtime

outputs: production url, promotion confirmation

edge cases:

e2e tests fail: promote job does not run; fix tests, push again, repeat
preview url no longer exists: promote fails; redeploy preview first
network outage during promote: idempotent; retry safely

decision points

when to use preview deploy vs production deploy

if feature branch or pr: use preview deploy (vercel or vercel build && vercel deploy --prebuilt). provides unique url for testing without affecting production.

if main branch and ready for live traffic: use production deploy (vercel --prod or vercel deploy --prebuilt --prod). makes code live at your domain.

when to use --prebuilt

if custom ci pipeline (github actions, gitlab ci, bitbucket): always use --prebuilt. separates build from deploy, enables build caching, test gates between build and deploy, and faster rollback (no rebuild).

if simple git-push workflow (no custom ci): skip --prebuilt. vercel builds remotely after every push; simpler, less config.

if monorepo with selective builds (turborepo affected): use --prebuilt with custom ci to cache builds and skip unaffected projects.

when to use promote vs re-deploy

if preview deployment has been validated (tests passed, qa approved, manual review done): use promote (vercel promote ). instant, zero downtime, same artifact as tested.

if code needs rebuild (e.g. env var changed, build script updated, dependency conflict): use deploy (vercel deploy --prod). slower but guarantees fresh build.

when to use oidc federation

if vercel serverless function needs to call aws apis (s3, dynamodb, sqs): configure oidc federation. function requests short-lived token from vercel at runtime, exchanges it with aws sts for scoped credentials. no static secrets stored in env vars.

if vercel function needs to auth to gcp workload identity federation: same as aws, use oidc.

if vercel function only calls your own api (no third-party service auth needed): skip oidc. use regular env var secrets.

note: oidc does not authenticate the vercel cli in ci. vercel pull, vercel build, vercel deploy still require --token=$VERCEL_TOKEN.

when to use vercel pull

before every ci build: run vercel pull --yes --environment=. syncs production/preview env vars and project config (rootDirectory, functions, etc.) from dashboard.

if env vars are huge or sensitive: some env vars flagged "sensitive" are not available in pull output; set them directly in ci secrets.

if env vars are not syncing: check vercel dashboard > settings > environment variables; manually set in ci as backup.

when to use vercel logs vs vercel inspect

if you need build metadata (build duration, framework detected, functions list): use vercel inspect .

if you need runtime logs (errors during execution, serverless function logs): use vercel logs .

if logs are older than 3 days: upgrade to pro plan for longer retention; otherwise logs discarded.

when to rollback vs re-deploy

if current production is broken and you need to revert code instantly: use vercel rollback. points alias to prior deployment, takes seconds.

if you need to fix and push new code: use re-deploy (vercel deploy --prod or promote a new preview). slower but ships fix.

if rollback target was deleted: use vercel ls to find an older live deployment, then vercel rollback .

output contract

preview deployment result:

url: https://--.vercel.app
deployment id:
status: READY or ERROR
build logs: plain text from vercel cli stdout
expires after 30 days of no activity

production deployment result:

url: yourdomain.com (or vercel domain if custom domain not set)
deployment id:
status: READY or ERROR
build logs: plain text from vercel cli stdout
aliases pointing to this deployment id are now live

promote result:

confirmation message: "Promotion successful"
production alias now points to the promoted deployment id
no rebuild occurred

rollback result:

confirmation message: "Rollback successful" or error if target deployment unavailable
production alias now points to the prior (or specified) deployment id

vercel inspect output:

json: {deployment_id, url, created, creator, project, status, framework, build_time_ms, functions: [...], env: {...}, etc.}
or human-readable: deployment details printed to stdout

vercel logs output:

plain text stream: one log line per deployment event
format: timestamp message [level]
if --follow: streams live until ctrl-c

ci pipeline output:

github actions: job status (success / failure), deployment url in logs or workflow output
gitlab ci / bitbucket pipelines: pipeline status, deployment url in logs

all deploy outputs include short git commit sha for traceability.

outcome signal

successful preview deploy

vercel cli outputs: "✓ Preview: https://"
url is accessible in browser, renders expected content
preview url appears in pr comment (if using ci with github integration)

successful production deploy

vercel cli outputs: "✓ Production: https://yourdomain.com"
yourdomain.com (or vercel domain) serves new code
vercel inspect shows status: READY
vercel logs show no ERROR level entries (or expected errors only)

successful promote

vercel cli outputs: "✓ Promotion successful"
yourdomain.com instantly serves code from the promoted preview deployment
no rebuild occurred (deploy duration was < 5 seconds)

successful rollback

vercel cli outputs: "✓ Rollback successful"
yourdomain.com serves the prior deployment code
no rebuild occurred

ci pipeline success (github actions example)

github actions job shows green checkmark, duration < 5 minutes (most time spent building)
deployment url appears in workflow logs or github output
if pr: preview url comments on pr automatically

failed deploy

vercel cli outputs error: "error: build failed" or "error: deployment failed"
exit code is non-zero
error message indicates root cause: missing env var, lockfile mismatch, syntax error in code, quota exceeded, etc.
action: check logs with vercel logs --level error