| name | deploy-checklist |
| description | Use when preparing to deploy code to production, merging to main, running migrations on production databases, or setting environment variables on Render. Use when the user mentions "deploy", "push to production", "merge to main", "run migrations", or asks about pending deploy items. Also use when reviewing what needs to happen before a feature goes live. |
Deploy Checklist
Overview
A structured pre-deployment validation process that ensures nothing is missed when moving code from dev to production. Deployments have many moving parts (migrations, env vars, feature flags, service restarts) and forgetting any one can cause downtime or data loss.
When to Use
- Before merging dev to main
- Before running migrations on production DB
- Before setting/changing env vars on Render
- When user asks "what needs to be deployed" or "is this ready for prod"
When NOT to Use
- Local development workflow
- Pushing to dev branch (that's normal workflow)
- Running migrations on dev DB (lower risk)
Pre-Deploy Validation Checklist
1. Code Readiness
2. Migration Safety
Check pending migrations:
ls prisma/migrations/
For each pending migration:
Migration ordering matters: Check for number collisions. Both files in each collision pair must run.
3. Environment Variables
Before deploying, check if new env vars are needed:
diff <(grep -oP '^[A-Z_]+=' .env | sort) <(grep -oP '^[A-Z_]+=' .env.example | sort)
For each new env var:
CRITICAL: Never use PUT on Render env vars API — it WIPES ALL existing variables. Always use APPEND/PATCH.
4. Dependency Check
5. Feature Flags
6. Database Extensions
Check if new extensions are needed:
pgcrypto — for UUID generationpg_trgm — for fuzzy text search- Verify extension exists on production before running migrations that depend on it
7. Deploy Sequence
Execute in this exact order:
- Set env vars on Render (PATCH endpoint)
- Install DB extensions if needed
- Run migrations in batch order (see migration plan)
- Push code to main (
git push origin main)
- Verify service restarts successfully on Render
- Run smoke test (hit key API endpoints)
- Monitor logs for 15 minutes
8. Rollback Plan
Before deploying, document:
Post-Deploy Verification
Common Mistakes
| Mistake | Impact | Prevention |
|---|
| PUT on Render env vars | Wipes ALL vars, full outage | Always PATCH/append |
| Skip migration order | Foreign key violations, data loss | Run in sequence |
| Deploy without env vars | Features crash on missing config | Set vars BEFORE push |
| No rollback plan | Extended downtime | Document rollback for each migration |
| Push to master directly | Bypasses CI, no review | Always merge via PR or controlled push |
