tpmjs/DEPLOYMENT.md

Deployment Configuration

This document explains how to configure Vercel to only deploy when GitHub Actions CI passes.

Overview

The project is configured to run comprehensive CI checks on every push and pull request:

• Linting - Code style and quality
• Type checking - TypeScript validation
• Tests - Unit and integration tests
• Build - Production build verification
• Architecture - Dependency rules validation
• Dead code - Unused code detection

Vercel should only deploy after all these checks pass on the main branch.

Configuration Options

There are two ways to prevent Vercel from deploying when CI fails:

Option 1: Vercel Deployment Protection (Recommended)

This is the simplest and most reliable approach.

1. Enable Deployment Protection in Vercel:

   • Go to your Vercel project settings
   • Navigate to Git → Deployment Protection
   • Enable "Wait for Checks to Complete"
   • This makes Vercel wait for all GitHub status checks before deploying

2. Configure Branch Protection (GitHub):

   • Go to GitHub repository settings
   • Navigate to Branches → Branch protection rules
   • Add rule for main branch
   • Enable "Require status checks to pass before merging"
   • Select all CI jobs: lint, type-check, test, build, architecture, deadcode
   • Enable "Require branches to be up to date before merging"

This ensures:

• ✅ PRs cannot be merged unless CI passes
• ✅ Vercel waits for CI to complete before deploying
• ✅ Production always has passing CI

Option 2: Ignored Build Step (Advanced)

Use a custom script to check CI status before building.

1. Add GitHub Token to Vercel:

   • Go to Vercel project settings
   • Navigate to Environment Variables
   • Add GITHUB_TOKEN with a Personal Access Token
   • Scope: repo:status (read commit status)
   • Apply to: Production, Preview, Development

2. Configure Ignored Build Step:

   • Go to Vercel project settings
   • Navigate to Git → Ignored Build Step
   • Set custom command:

     bash scripts/vercel-should-deploy.sh
     

3. How it works:

   • Script checks if CI has passed via GitHub API
   • Exit code 0 = skip build (CI failed/pending)
   • Exit code 1 = proceed with build (CI passed)
   • Preview deployments always proceed
   • Production deployments wait for CI

Deployment Workflow

For Pull Requests (Preview)

1. Push commits to PR branch
2. GitHub Actions runs CI checks
3. Vercel creates preview deployment (regardless of CI status)
4. CI status is shown on PR
5. Can only merge if CI passes (branch protection)

For Production (Main Branch)

1. PR is merged to main
2. GitHub Actions runs CI checks
3. Vercel waits for CI to complete (if Deployment Protection enabled)
4. Once CI passes, Vercel deploys to production
5. If CI fails, deployment is blocked

CI Jobs

The following jobs must pass for deployment:

Job	Description	Blocks Deploy
lint	ESLint + Biome formatting	✅ Yes
type-check	TypeScript compilation	✅ Yes
test	Vitest unit tests	✅ Yes
build	Production build	✅ Yes
architecture	Dependency rules	✅ Yes
deadcode	Unused code detection	⚠️ Warning only

Manual Deployment Override

If you need to deploy even when CI fails (emergency hotfix):

1. Temporarily disable branch protection:

   • GitHub → Settings → Branches → Edit rule
   • Uncheck "Require status checks to pass"
   • Merge PR
   • Re-enable protection immediately after

2. Or push directly to main (not recommended):

   git push origin main --no-verify
   

Troubleshooting

Vercel deploys even though CI failed

Solution: Enable "Deployment Protection" in Vercel settings.

CI is stuck in pending state

Solution: Check GitHub Actions workflow logs. Ensure all jobs complete.

Preview deployments are blocked

Solution: Preview deployments should never be blocked. Check Ignored Build Step script logic.

Need to deploy urgently

Solution: Use manual override (see above), but fix CI issues immediately after.

Best Practices

1. ✅ Always ensure CI passes before merging
2. ✅ Use preview deployments to test changes
3. ✅ Fix CI failures immediately - don't merge broken code
4. ✅ Review CI logs when checks fail
5. ❌ Don't bypass CI unless absolutely necessary
6. ❌ Don't merge with failing tests "to fix later"

Verification

To verify the setup is working:

1. Create a PR with intentionally broken code (e.g., TypeScript error)
2. Verify CI fails
3. Verify PR cannot be merged
4. Verify Vercel deployment is blocked/skipped
5. Fix the code
6. Verify CI passes
7. Verify PR can be merged
8. Verify Vercel deploys successfully

Environment Variables

Required environment variables in Vercel:

Variable	Required For	Description
GITHUB_TOKEN	Option 2 only	GitHub Personal Access Token with repo:status scope

Not needed for Option 1 (Deployment Protection).

Status Badge

Add to README.md to show CI status:

[![CI](https://github.com/tpmjs/tpmjs/actions/workflows/ci.yml/badge.svg)](https://github.com/tpmjs/tpmjs/actions/workflows/ci.yml)

Summary

Recommended Setup:

1. Enable Vercel "Deployment Protection" (wait for checks)
2. Enable GitHub branch protection for main
3. Require all CI jobs to pass before merging

This ensures production always has high-quality, tested code.