Promote Deployment

Two-Stage Model

feature branch → staging (preview) → main (production)

• staging: Integration branch. Vercel deploys a preview against Neon staging database.
• main: Production. Vercel deploys to production against Neon main database.

Usage

Promote to staging (from a feature branch):

./scripts/promote.sh staging

Promote to production (from staging):

./scripts/promote.sh production

The script runs quality gates automatically, checks for uncommitted changes, and creates a PR via gh.

Manual Promotion Checklist

If the script doesn't fit the situation, follow this sequence exactly:

1. Generate migrations: bunx drizzle-kit generate (if schema changed)
2. Validate migrations: bun run db:check
3. Run all gates: ./scripts/gates.sh
4. Open PR to staging
5. Validate preview deployment against Neon staging
6. Open promotion PR from staging → main
7. Migrations apply automatically during Vercel build via DATABASE_URL_UNPOOLED
8. If migration fails, STOP. Do not retry. Fix the schema/migration drift first.

Database Safety

• Migrations run during Vercel's build step using DATABASE_URL_UNPOOLED (direct connection).
• Production DATABASE_URL points to Neon main branch (ep-rapid-pond-akug8qa3).
• Run ./scripts/db-branch-check.sh if unsure which database you're targeting.
• See the db-health skill for full database safety rules.

Environment Mapping

Git Branch	Vercel Environment	Neon Branch
staging	Preview	staging
main	Production	main
feature branches	Preview (PR)	preview/* (auto-forked)

Guardrails

• Never push directly to main. Always go through staging first.
• Never skip quality gates to speed up deployment.
• Treat migration failures as hard blockers — no retry without a fix.
• Never run drizzle-kit push against any shared branch.

If You're Lost

• Vercel deployments & environments
• Neon + Vercel integration
• Drizzle ORM migrations
• See docs/release-flow.md for the full delivery checklist