npx skills add ...
npx skills add vercel/vercel-plugin --skill deployments-cicd
npx skills add vercel/vercel-plugin --skill deployments-cicd
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.
The same skill content is published under more than one repo. The install counts are split across them; any of these commands works.
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.
Preview deployments are created automatically for every push to a non-production branch when using Git integration. They provide a unique URL for testing.
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 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.
Every CI pipeline needs these three variables:
Set these as secrets in your CI provider. Never commit them to source control.
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:
| 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 |
--prebuilt in CI — separates build from deploy, enables build caching and test gatesvercel pull before build — ensures correct env vars and project settingspromote over re-deploy — instant, no rebuild, same artifactVERCEL_TOKEN for CLI)npm install -g vercel@latest can break unexpectedly--yes flag in CI — prevents interactive prompts from hanging pipelines| 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 |
| 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 |
Present a structured deploy result block:
If the deployment failed, append:
For production deploys, also include:
Based on the deployment outcome:
/deploy prod to promote to production."/status to see the full project overview."build script in package.json, check for missing env vars with /env list, ensure dependencies are installed."/env pull to sync environment variables locally, or /env list to review what's configured on Vercel."vercel.json for rootDirectory."vercel logs <url> --level error for details. If drains are configured, correlate with external monitoring."/status for a full observability diagnostic."# 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># 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> --followVERCEL_TOKEN=<your-token> # Personal or team token
VERCEL_ORG_ID=<org-id> # From .vercel/project.json
VERCEL_PROJECT_ID=<project-id> # From .vercel/project.jsonname: 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 }}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:
- mainpipelines:
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# 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 }}`
})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 }}## Deploy Result
- **URL**: <deployment-url>
- **Target**: production | preview
- **Status**: READY | ERROR | BUILDING | QUEUED
- **Commit**: <short-sha>
- **Framework**: <detected-framework>
- **Build Duration**: <duration>- **Error**: <summary of failure from logs>### 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>