Labsco
vercel logo

deployments-cicd

✓ Official★ 207

by vercel · part of vercel/vercel-plugin

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

🔥🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#scraping#cloud#devops#git#monitoring
🧩 One of 7 skills in the vercel/vercel-plugin package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

by vercel

Vercel deployment and CI/CD expert guidance. Use when deploying, promoting, rolling back, inspecting deployments, building with --prebuilt, or configuring CI… npx skills add https://github.com/vercel/vercel-plugin --skill deployments-cicd Download ZIPGitHub207

CI/CD Integration

Required Environment Variables

Every CI pipeline needs these three variables:

VERCEL_TOKEN= # Personal or team token
VERCEL_ORG_ID= # From .vercel/project.json
VERCEL_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

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

Official Documentation