Index of every page on this site: llms.txt
All skills
vercel avatar

/deployments-cicd

@250769d official
by vercelvercel/vercel-plugin340 stars
82
Run it yourself

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

  • 6 files
  • 19.4 KB
  • Updated 2 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/vercel/vercel-plugin/deployments-cicd

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈51 tokens for metadata: the name and description. ≈2.6k when used: this file. ≈2k more on demand in 4 files.

Description uses 2.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈203 characters, or 2.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

Git pushes to non-production branches make previews. A project's first deploy goes to production. To undo it, ask the user, then run vercel remove <id> --yes.

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 250769d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago
Other metadata
metadata
{
  "priority": 6,
  "docs": [
    "https://vercel.com/docs/deployments",
    "https://vercel.com/docs/git",
    "https://vercel.com/docs/deployments/promoting-a-deployment",
    "https://vercel.com/docs/deployment-checks"
  ],
  "sitemap": "https://vercel.com/sitemap.xml",
  "pathPatterns": [
    ".github/workflows/*.yml",
    ".github/workflows/*.yaml",
    ".gitlab-ci.yml",
    "bitbucket-pipelines.yml",
    "vercel.json",
    "apps/*/vercel.json"
  ],
  "bashPatterns": [
    "\\bvercel\\s+deploy\\b",
    "\\bvercel\\s+--prod\\b",
    "\\bvercel\\s+promote\\b",
    "\\bvercel\\s+rollback\\b",
    "\\bvercel\\s+inspect\\b",
    "\\bvercel\\s+build\\b",
    "\\bvercel\\s+deploy\\s+--prebuilt\\b"
  ]
}
validate
[
  {
    "pattern": "cron:\\s*['\"]|from\\s+['\"](node-cron)['\"]|cron\\.schedule\\(",
    "message": "Manual cron scheduling detected. Use Vercel Schedules (beta), not legacy Cron Jobs.",
    "severity": "recommended",
    "skipIfFileContains": "vercel\\.json.*(crons|schedules)|@vercel/schedules"
  }
]
retrieval
{
  "aliases": [
    "deploy",
    "ci cd",
    "continuous deployment",
    "release pipeline"
  ],
  "intents": [
    "deploy to vercel",
    "set up ci cd",
    "promote deployment",
    "rollback deploy"
  ],
  "entities": [
    "vercel deploy",
    "preview",
    "production",
    "rollback",
    "promote",
    "CI workflow"
  ]
}

README badge

README badge for vercel/vercel-plugin/deployments-cicd