{"id":24836,"plugin_id":"plugin_connector_690a90ec05c881918afb6a55dc9bbaa1","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:18:43.694Z","digest":"c8fe79367382811971450f04bc2d36900ee61d0a32527af3d7f4db387cb9ea78","against":5236,"payload":{"name":"deployments-cicd","description":"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.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":113}],"skill_md_contents":"---\nname: deployments-cicd\ndescription: 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.\nmetadata:\n  priority: 6\n  docs:\n    - \"https://vercel.com/docs/deployments/overview\"\n    - \"https://vercel.com/docs/git\"\n  sitemap: \"https://vercel.com/sitemap/docs.xml\"\n  pathPatterns:\n    - '.github/workflows/*.yml'\n    - '.github/workflows/*.yaml'\n    - '.gitlab-ci.yml'\n    - 'bitbucket-pipelines.yml'\n    - 'vercel.json'\n    - 'apps/*/vercel.json'\n  bashPatterns:\n    - '\\bvercel\\s+deploy\\b'\n    - '\\bvercel\\s+--prod\\b'\n    - '\\bvercel\\s+promote\\b'\n    - '\\bvercel\\s+rollback\\b'\n    - '\\bvercel\\s+inspect\\b'\n    - '\\bvercel\\s+build\\b'\n    - '\\bvercel\\s+deploy\\s+--prebuilt\\b'\n---\n\n# Vercel Deployments & CI/CD\n\nYou 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.\n\n## Deployment Commands\n\n### Preview Deployment\n\n```bash\n# Deploy from project root (creates preview URL)\nvercel\n\n# Equivalent explicit form\nvercel deploy\n```\n\nPreview deployments are created automatically for every push to a non-production branch when using Git integration. They provide a unique URL for testing.\n\n### Production Deployment\n\n```bash\n# Deploy directly to production\nvercel --prod\nvercel deploy --prod\n\n# Force a new deployment (skip cache)\nvercel --prod --force\n```\n\n### Build Locally, Deploy Build Output\n\n```bash\n# Build locally (uses development env vars by default)\nvercel build\n\n# Build with production env vars\nvercel build --prod\n\n# Deploy only the build output (no remote build)\nvercel deploy --prebuilt\nvercel deploy --prebuilt --prod\n```\n\n**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.\n\n### Promote & Rollback\n\n```bash\n# Promote a preview deployment to production\nvercel promote <deployment-url-or-id>\n\n# Rollback to the previous production deployment\nvercel rollback\n\n# Rollback to a specific deployment\nvercel rollback <deployment-url-or-id>\n```\n\n**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.\n\n### Inspect Deployments\n\n```bash\n# View deployment details (build info, functions, metadata)\nvercel inspect <deployment-url>\n\n# List recent deployments\nvercel ls\n\n# View logs for a deployment\nvercel logs <deployment-url>\nvercel logs <deployment-url> --follow\n```\n\n## CI/CD Integration\n\n### Required Environment Variables\n\nEvery CI pipeline needs these three variables:\n\n```bash\nVERCEL_TOKEN=<your-token>        # Personal or team token\nVERCEL_ORG_ID=<org-id>           # From .vercel/project.json\nVERCEL_PROJECT_ID=<project-id>   # From .vercel/project.json\n```\n\nSet these as secrets in your CI provider. Never commit them to source control.\n\n### GitHub Actions\n\n```yaml\nname: Deploy to Vercel\non:\n  push:\n    branches: [main]\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Install Vercel CLI\n        run: npm install -g vercel\n\n      - name: Pull Vercel Environment\n        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}\n\n      - name: Build\n        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}\n\n      - name: Deploy\n        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}\n```\n\n### OIDC Federation (Secure Backend Access)\n\nVercel 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.\n\n**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.\n\n**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 }}`.\n\n**When to use OIDC:**\n- Serverless functions that need to call AWS APIs (S3, DynamoDB, SQS)\n- Functions authenticating to GCP services via Workload Identity Federation\n- Any runtime service-to-service auth where you want to avoid storing static secrets in Vercel env vars\n\n### GitLab CI\n\n```yaml\ndeploy:\n  image: node:20\n  stage: deploy\n  script:\n    - npm install -g vercel\n    - vercel pull --yes --environment=production --token=$VERCEL_TOKEN\n    - vercel build --prod --token=$VERCEL_TOKEN\n    - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN\n  only:\n    - main\n```\n\n### Bitbucket Pipelines\n\n```yaml\npipelines:\n  branches:\n    main:\n      - step:\n          name: Deploy to Vercel\n          image: node:20\n          script:\n            - npm install -g vercel\n            - vercel pull --yes --environment=production --token=$VERCEL_TOKEN\n            - vercel build --prod --token=$VERCEL_TOKEN\n            - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN\n```\n\n## Common CI Patterns\n\n### Preview Deployments on PRs\n\n```yaml\n# GitHub Actions\non:\n  pull_request:\n    types: [opened, synchronize]\n\njobs:\n  preview:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: npm install -g vercel\n      - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}\n      - run: vercel build --token=${{ secrets.VERCEL_TOKEN }}\n      - id: deploy\n        run: echo \"url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})\" >> $GITHUB_OUTPUT\n      - name: Comment PR\n        uses: actions/github-script@v7\n        with:\n          script: |\n            github.rest.issues.createComment({\n              issue_number: context.issue.number,\n              owner: context.repo.owner,\n              repo: context.repo.repo,\n              body: `Preview: ${{ steps.deploy.outputs.url }}`\n            })\n```\n\n### Promote After Tests Pass\n\n```yaml\njobs:\n  deploy-preview:\n    # ... deploy preview ...\n    outputs:\n      url: ${{ steps.deploy.outputs.url }}\n\n  e2e-tests:\n    needs: deploy-preview\n    runs-on: ubuntu-latest\n    steps:\n      - run: npx playwright test --base-url=${{ needs.deploy-preview.outputs.url }}\n\n  promote:\n    needs: [deploy-preview, e2e-tests]\n    runs-on: ubuntu-latest\n    if: github.ref == 'refs/heads/main'\n    steps:\n      - run: npm install -g vercel\n      - run: vercel promote ${{ needs.deploy-preview.outputs.url }} --token=${{ secrets.VERCEL_TOKEN }}\n```\n\n## Global CLI Flags for CI\n\n| Flag | Purpose |\n|------|---------|\n| `--token <token>` | Authenticate (required in CI) |\n| `--yes` / `-y` | Skip confirmation prompts |\n| `--scope <team>` | Execute as a specific team |\n| `--cwd <dir>` | Set working directory |\n\n## Best Practices\n\n1. **Always use `--prebuilt` in CI** — separates build from deploy, enables build caching and test gates\n2. **Use `vercel pull` before build** — ensures correct env vars and project settings\n3. **Prefer `promote` over re-deploy** — instant, no rebuild, same artifact\n4. **Use OIDC federation for runtime backend access** — lets Vercel functions auth to AWS/GCP without static secrets (does not replace `VERCEL_TOKEN` for CLI)\n5. **Pin the Vercel CLI version in CI** — `npm install -g vercel@latest` can break unexpectedly\n6. **Add `--yes` flag in CI** — prevents interactive prompts from hanging pipelines\n\n## Deployment Strategy Matrix\n\n| Scenario | Strategy | Commands |\n|----------|----------|----------|\n| Standard team workflow | Git-push deploy | Push to main/feature branches |\n| Custom CI/CD (Actions, CircleCI) | Prebuilt deploy | `vercel build && vercel deploy --prebuilt` |\n| Monorepo with Turborepo | Affected + remote cache | `turbo run build --affected --remote-cache` |\n| Preview for every PR | Default behavior | Auto-creates preview URL per branch |\n| Promote preview to production | CLI promotion | `vercel promote <url>` |\n| Atomic deploys with DB migrations | Two-phase | Run migration → verify → `vercel promote` |\n| Edge-first architecture | Edge Functions | Set `runtime: 'edge'` in route config |\n\n## Common Build Errors\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| `ERR_PNPM_OUTDATED_LOCKFILE` | Lockfile doesn't match package.json | Run `pnpm install`, commit lockfile |\n| `NEXT_NOT_FOUND` | Root directory misconfigured | Set `rootDirectory` in Project Settings |\n| `Invalid next.config.js` | Config syntax error | Validate config locally with `next build` |\n| `functions/api/*.js` mismatch | Wrong file structure | Move to `app/api/` directory (App Router) |\n| `Error: EPERM` | File permission issue in build | Don't `chmod` in build scripts; use postinstall |\n\n## Deploy Summary Format\n\nPresent a structured deploy result block:\n\n```\n## Deploy Result\n- **URL**: <deployment-url>\n- **Target**: production | preview\n- **Status**: READY | ERROR | BUILDING | QUEUED\n- **Commit**: <short-sha>\n- **Framework**: <detected-framework>\n- **Build Duration**: <duration>\n```\n\nIf the deployment failed, append:\n\n```\n- **Error**: <summary of failure from logs>\n```\n\nFor production deploys, also include:\n\n```\n### Post-Deploy Observability\n- **Error scan**: <N errors found / clean> (scanned via vercel logs --level error --since 1h)\n- **Drains**: <N configured / none>\n- **Monitoring**: <active / gaps identified>\n```\n\n## Deploy Next Steps\n\nBased on the deployment outcome:\n\n- **Success (preview)** → \"Visit the preview URL to verify. When ready, run `/deploy prod` to promote to production.\"\n- **Success (production)** → \"Your production site is live. Run `/status` to see the full project overview.\"\n- **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.\"\n- **Missing env vars** → \"Run `/env pull` to sync environment variables locally, or `/env list` to review what's configured on Vercel.\"\n- **Monorepo issues** → \"Ensure the correct project root is configured in Vercel project settings. Check `vercel.json` for `rootDirectory`.\"\n- **Post-deploy errors detected** → \"Review errors above. Check `vercel logs <url> --level error` for details. If drains are configured, correlate with external monitoring.\"\n- **No monitoring configured** → \"Set up drains or install an error tracking integration before the next production deploy. Run `/status` for a full observability diagnostic.\"\n\n## Official Documentation\n\n- [Deployments](https://vercel.com/docs/deployments)\n- [Vercel CLI](https://vercel.com/docs/cli)\n- [GitHub Actions](https://vercel.com/docs/deployments/git/vercel-for-github)\n- [GitLab CI](https://vercel.com/docs/deployments/git/vercel-for-gitlab)\n- [Bitbucket Pipelines](https://vercel.com/docs/deployments/git/vercel-for-bitbucket)\n- [OIDC Federation](https://vercel.com/docs/oidc)\n"},"changes":[{"path":"/included_files","type":"changed","before":[],"after":[{"relative_path":"agents/openai.yaml","size_in_bytes":113}]}],"summary":"Fields changed: 1. /included_files.","summary_kind":"deterministic","summary_metadata":{}}