Deploy

Deploy

Full pre-flight validation → deploy pipeline. Closes the audit-to-production loop.

Process

Step 1: Detect Deploy Target

Check project for deploy configuration:

• vercel.json or .vercel/ → Vercel (git push)
• railway.toml or railway.json → Railway
• fly.toml → Fly.io
• wrangler.toml → Cloudflare Workers
• .github/workflows/ with deploy steps → CI/CD pipeline
• Dockerfile → Container-based deploy
• None found → ask user for deploy target

Step 2: Pre-Flight Checks

Run these checks BEFORE deploying (fail fast):

2a. Environment Validation

node ${CLAUDE_PLUGIN_ROOT}/tools/env-validator.mjs <project-directory>

If deploy_ready: false → STOP. Show missing vars. Do not deploy.

2b. Migration Safety

node ${CLAUDE_PLUGIN_ROOT}/tools/migration-checker.mjs <project-directory>

If deploy_safe: false → WARN. Show pending migrations. Ask user to confirm.

If a Supabase MCP server is connected (check your available tools for supabase), verify migration state against the actual database before deploying, not just the local migration files: list applied migrations and confirm the pending ones aren't already applied or in conflict. This catches the "migration ran on the dashboard but not in the repo" drift that breaks deploys.

If there are pending migrations, verify they are reversible:

• For Drizzle: check that corresponding down SQL or rollback logic exists
• For Prisma: confirm prisma migrate resolve can undo the migration
• For Knex: verify the down() function exists and is not empty
• If the migration is destructive (dropping columns, renaming tables, deleting data) and has no rollback path → STOP. This is not safe to deploy without a manual rollback plan.

2c. Bundle Size Check

node ${CLAUDE_PLUGIN_ROOT}/tools/bundle-tracker.mjs <project-directory> --save

If bundle grew >50KB since last check → WARN. Show diff.

2d. Git Status Check for uncommitted changes:

git status --porcelain

If dirty working tree → WARN. Suggest committing first.

2e. Rollback Plan

Before deploying, establish a rollback plan. Every deploy must have a way back.

Record the current production commit hash:

git rev-parse HEAD

Store this value — it is your safety net. If anything goes wrong after deploy, this is the commit you revert to.

Verify the rollback command is ready:

git revert <commit> --no-edit

Do not execute this yet. Confirm the command is syntactically correct and the commit hash is valid. The goal is to have a copy-paste rollback ready before you need it — not after you're panicking at 2am.

For database changes:

• Confirm the migration has a working down migration (checked in Step 2b)
• If the migration drops a column or table, the data is gone. There is no rollback. You need a backup strategy instead: pg_dump the affected tables before deploying, or use a feature flag to decouple the schema change from the code change
• For additive-only migrations (new columns, new tables), rollback is safe — the old code simply ignores the new schema

For breaking API changes:

• Confirm that API consumers can handle both the old and new response shapes during the transition window
• If the API serves mobile clients or third-party integrations, a breaking change without versioning is not a rollback — it is a second outage
• Prefer additive changes (new fields) over destructive changes (removed/renamed fields)

Document the rollback steps in a format that can be executed under pressure:

ROLLBACK PLAN:
1. git revert <new-commit-hash> --no-edit
2. git push origin main
3. [If DB migration]: run down migration or restore from backup
4. Verify health check passes after rollback

Step 3: Run Ship Audit

Run the full /ship scorecard. If overall score < 60 → WARN but don't block (user decides).

A score below 60 means there are known issues going to production. That is a conscious decision, not an accident. Log it so the post-deploy summary reflects the risk accepted.

Step 4: Deploy

Based on detected target:

Vercel (git push — REQUIRED for this user):

git push origin main

NEVER use vercel CLI. Always git push.

Railway:

railway up

Fly.io:

fly deploy

Cloudflare Workers:

npx wrangler deploy

CI/CD:

git push origin main

Then check CI status:

gh run list --limit 1 --json status,conclusion

Record the deploy start time. You will need this for the post-deploy summary.

Step 4b: Smoke Tests

After deploy lands but before declaring success, verify the application actually works for real users. A successful git push is not a successful deploy — it is a successful file transfer.

Hit 3-5 critical user paths against the production URL:

node ${CLAUDE_PLUGIN_ROOT}/tools/api-smoke-test.mjs <production-url>

At minimum, verify:

1. Homepage returns 200 (not 500, not a redirect loop, not a blank page)
2. Login/auth endpoint responds (does not need to complete auth — just confirm it is not crashing)
3. Core feature endpoint returns valid JSON with the expected shape
4. API health endpoint (if one exists) returns 200 with a response body
5. Static assets load (CSS/JS files return 200, not 404 — a broken asset build is invisible to health checks but catastrophic to users)

Verify response codes and content types:

• 200 responses should return the expected Content-Type (HTML for pages, JSON for APIs)
• Watch for soft failures: a 200 that returns an error page, or a JSON response with { "error": true } inside a 200 status code
• Check that responses are not empty (a 200 with a 0-byte body is not healthy)

If Playwright MCP is available, run a quick browser check on the production URL:

• Navigate to the homepage, confirm it renders (not a white screen)
• Click one critical CTA and confirm navigation works
• Check the browser console for JavaScript errors — a deploy that throws uncaught exceptions on load is broken even if the server returns 200

If any smoke test fails, execute the rollback plan immediately. Do not debug in production. Do not "just check one more thing." Roll back, confirm the rollback is healthy, then investigate the failure from safety. The cost of a 5-minute rollback is always less than the cost of a 30-minute production outage while you debug.

Step 5: Post-Deploy Health Check

After deploy completes, run health check against production URL:

node ${CLAUDE_PLUGIN_ROOT}/tools/health-check.mjs <production-url>

Report: status code, response time, SSL status, security headers.

If the health check fails on the first attempt, wait 30 seconds and retry once. Some platforms (Vercel, Railway) have a cold-start window where the first request after deploy is slow or fails. Two consecutive failures means the deploy is broken — trigger rollback.

If a Vercel MCP server is connected (check your available tools for vercel), don't infer deploy state from a single HTTP probe: read the actual deployment status, build logs, and which commit is live. This confirms the deploy you intended is the one serving traffic, surfaces build-time failures the health check can't see, and gives you the exact deployment to promote or roll back.

Step 5b: Performance Baseline

After confirming the deploy is healthy, record performance metrics as the new baseline.

Record the response time from the health check as the post-deploy baseline:

node ${CLAUDE_PLUGIN_ROOT}/tools/health-check.mjs <production-url>

Compare to the pre-deploy baseline:

• If response time is >50% slower than the previous deploy → flag as a performance regression. This does not necessarily mean rollback, but it means something changed that deserves investigation before the next deploy.
• If response time is >200% slower (3x the previous baseline) → treat this as a deploy failure. Something is fundamentally wrong — likely an unoptimized query, a missing index on a new migration, or a cold-start loop.

Check platform-level metrics if available:

• Railway: check the dashboard for memory usage and CPU spikes in the minutes after deploy
• Fly.io: fly status and fly logs for health check failures or OOM kills
• Vercel: check function execution duration in the Vercel dashboard — serverless cold starts can mask real performance regressions
• Cloudflare Workers: check CPU time in the dashboard (Workers have a 50ms CPU limit on the free plan)

Store the performance baseline for comparison on the next deploy:

node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <project-dir> response_time <ms>

Step 6: Save Audit History

Save all scores for before/after comparison:

node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <project-dir> seo <score>
node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <project-dir> performance <score>
node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <project-dir> security <score>

Step 7: Post-Deploy Summary

Output deployment summary:

====================================
  DEPLOY COMPLETE
====================================
  Target:     Vercel (git push)
  Branch:     main
  Commit:     abc1234
  URL:        https://example.com
  Health:     HEALTHY (247ms)
  SSL:        Valid (89 days remaining)
====================================
  Pre-flight: 3/3 passed
  Ship Score: 90/100
====================================
  Response Time:  247ms (prev: 210ms, +17%)
  Deploy Duration: 2m 14s (push → health check pass)
====================================
  ROLLBACK COMMAND (ready to copy-paste):
  git revert abc1234 --no-edit && git push origin main
====================================

Include in every post-deploy summary:

• Rollback command: ready to copy-paste, no thinking required. If something breaks in the next 30 minutes, the person responding should be able to roll back without understanding the change.
• Time from deploy start to health check pass: this is your deploy duration. Track it over time. If deploys are getting slower, your build pipeline needs attention.
• Response time comparison: current vs. previous deploy. A consistent upward trend across deploys means you are accumulating technical debt in your runtime, not just your codebase.
• Risk accepted: if any pre-flight check was overridden or the ship score was below 60, note it here. Future-you deserves to know what past-you decided to ship anyway.

Deploy Checklist for Different Stages

Not all deploys carry the same risk. A staging deploy that breaks is a Slack message. A production deploy that breaks is revenue loss and user trust damage. Treat them differently.