vercel-ci-integration

# Vercel CI Integration

## Overview
Set up automated Vercel deployments in GitHub Actions with preview deployments on PRs, production deploys on merge to main, and optional test gating. Covers both Vercel's built-in Git integration and custom CI pipelines using the Vercel CLI.

## Prerequisites
- GitHub repository with Actions enabled
- Vercel project linked to the repo
- `VERCEL_TOKEN` stored as GitHub Secret
- `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` from `.vercel/project.json`

## Instructions

### Step 1: Store CI Secrets in GitHub
```bash
# Get project and org IDs
cat .vercel/project.json
# {"orgId":"team_xxx","projectId":"prj_xxx"}

# Add secrets to GitHub repo
gh secret set VERCEL_TOKEN --body "your-vercel-token"
gh secret set VERCEL_ORG_ID --body "team_xxx"
gh secret set VERCEL_PROJECT_ID --body "prj_xxx"
```

### Step 2: GitHub Actions — Preview on PR
```yaml
# .github/workflows/vercel-preview.yml
name: Vercel Preview Deployment
on:
  pull_request:
    branches: [main]

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install -g vercel@latest

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

      - name: Build Project
        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

      - name: Deploy Preview
        id: deploy
        run: |
          url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})
          echo "preview_url=$url" >> $GITHUB_OUTPUT
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

      - name: Comment PR with Preview URL
        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 deployed: ${{ steps.deploy.outputs.preview_url }}`
            })
```

### Step 3: GitHub Actions — Production on Merge
```yaml
# .github/workflows/vercel-production.yml
name: Vercel Production Deployment
on:
  push:
    branches: [main]

jobs:
  deploy-production:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install -g vercel@latest

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

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

      - name: Deploy Production
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
```

### Step 4: Test Gating — Run Tests Before Deploy
```yaml
# .github/workflows/vercel-gated.yml
name: Gated Vercel Deploy
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm test
      - run: npm run lint
      - run: npx tsc --noEmit

  deploy:
    needs: test  # Only deploy if tests pass
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g vercel@latest
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
      - run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
```

### Step 5: Skip Builds for Non-Code Changes
```json
// vercel.json — skip build when only docs change
{
  "ignoreCommand": "git diff HEAD^ HEAD --quiet -- . ':!docs' ':!*.md' ':!.github'"
}
```

Or in the dashboard: **Settings > Git > Ignored Build Step**

### Step 6: Vercel's Built-In Git Integration (Alternative)
If you prefer Vercel's automatic deployments over custom CI:

1. Connect your GitHub repo in the Vercel dashboard
2. Vercel auto-deploys: preview on every push, production on merge to main
3. Configure in **Settings > Git**:
   - Production branch: `main`
   - Preview branches: all other branches
   - Auto-assign custom domains to production

This approach requires zero CI configuration but gives less control over test gating.

## Output
- Preview deployments on every PR with URL comment
- Production deployments on merge to main (after tests pass)
- Test gating preventing broken code from reaching production
- Build skip rules for documentation-only changes

## Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| `Error: VERCEL_TOKEN is not set` | Secret not configured | Add `VERCEL_TOKEN` as GitHub repo secret |
| `Error: Could not find project` | Wrong ORG_ID or PROJECT_ID | Check `.vercel/project.json` values |
| `vercel pull` fails | Token lacks project access | Regenerate token with correct scope |
| Preview not commenting on PR | Missing `actions/github-script` | Add the comment step with correct permissions |
| Build cache not working | CI runs on fresh runner | Use `actions/cache` for `node_modules` and `.vercel/output` |

## Resources
- [Vercel CLI in CI](https://vercel.com/docs/cli/deploying-from-cli)
- [GitHub Actions](https://docs.github.com/en/actions)
- [Vercel Git Integration](https://vercel.com/docs/deployments/git)
- [Ignored Build Step](https://vercel.com/docs/project-configuration#ignorecommand)

## Next Steps
For deployment orchestration, see `vercel-deploy-integration`.