Build an approval-gated production release pipeline

[kelvinkipruto]

Closes #580

Stacked on #589 (issue #578). This is blocked by #578, so the PR targets claude/issue-578; rebase onto main once #589 merges. The diff shown here is only the #580 changes.

What changed

Build once, promote by digest (AC1, AC2)

• build-image.yml builds the immutable runtime and migrator images once and outputs each pinned by content digest (image@sha256:…). Deploy/release jobs promote the exact digest — mutable tags are never deployed.
• Builds need no database. The Dockerfile defaults DATABASE_URI/PAYLOAD_SECRET to build-time placeholders (next build imports the config but never connects), so producing the artifact requires no reachable — or real — DB.

Approval-gated production (AC3)

• release.yml: verify → build → staging → production. The production job runs in the production GitHub environment; enabling required reviewers there makes production deployment (including migrations) pause for human approval.

Single-instance, observable migrations (AC4, AC5)

• A dedicated migrator image (same commit, retains the Payload CLI + migrations/ that the slim runner prunes) runs pnpm migrate once as a one-off container in promote.yml — never in every replica (the entrypoint runs no migrations). The migrate step runs before the promote step, so a migration failure fails the job and traffic is never switched. Forward-fix/rollback handling is documented.

Bounded liveness & readiness (AC6, AC7)

• GET /api/health/live — process-only, no dependency calls (so a dep outage never kills a healthy process).
• GET /api/health/ready — time-bounded MongoDB (mongoose ping) + Apache Tika (HTTP, skipped when TIKA_ENABLED=0) checks; 200/503.
• Wired into the Docker HEALTHCHECK (liveness) and the Dokku app.json startup/liveness/readiness probes, and used as the post-deploy readiness gate in promote.yml. The timeout races the dependency call so a hung driver can't outlast the bound.

Rollback & restore, rehearsed (AC8)

• Runbooks: release-pipeline.md and rollback-and-restore.md. Image-by-digest rollback and mongodump/mongorestore procedures were rehearsed locally (results recorded in the runbook).

Verification (run locally)

• Full integration suite 245/245 passing (incl. new health.int.spec.ts); tsc --noEmit clean; lint clean; all workflow YAML + app.json parse.
• Migrator image built and run end-to-end against a fresh mongo:7 — all three migrations applied once, cleanly.
• DB restore rehearsal: seed → mongodump → drop → mongorestore --drop recovered the document exactly; image-by-digest run confirmed.

Notes / follow-ups

• Requires repo config: staging/production environments (required reviewers on production), plus STAGING_DATABASE_URI/STAGING_PAYLOAD_SECRET secrets. Documented in the runbook.
• The migrate step and readiness gate assume the runner can reach the target DB/URL; the runbook gives the dokku run alternative for network-isolated environments.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
PromiseTracker	Ready	Preview, Comment	Jul 21, 2026 8:44am