Release, Deployment, and Rollback Runbook

Current release checkpoint — October 7, 2026

Use the current handoff for source, image and rollback identity. Production serves 0ce1ccbe; pushed source at capture is 6400fe9f, with additional shared discovery edits. Full combined gates and signed-in acceptance are not complete. Preserve prior static assets as described in deployment. Recent releases used an admitted isolated build on the build host and supported prebuilt-image promotion on the app host; do not bypass admission/capacity gates or push HostSSH main merely for documentation synchronization.

This runbook supplements Deployment and Database Migrations.

Release Readiness

Before release, confirm:

• npm run verify:launch -- --dry-run --json reports Node 24.x, valid core

environment, and the expected launch gate plan.

• npm run typecheck passes.
• npm run lint passes.
• npm run lint:warning-budget reports 0/0.
• Focused tests for changed behavior pass.
• Relevant Playwright smoke passes for changed workflows.
• Database migrations are reviewed for zero-downtime safety.
• Environment variables are present in the deployment target.
• Provider integrations are classified as ready, preview-only, or externally

blocked.

Build and Deploy

The standard build command is:

npm run build

The standalone runtime check is:

npm run self-hosted:standalone-check

The production deployment path is described in docs/deployment.md. Keep the deployment target's Node runtime aligned with package.json (24.x). The local launch verifier auto re-execs with Node 24 when it finds an installed runtime, but the full npm run verify:launch command should run only against a controlled launch database because the browser workflow gates create app records.

Release Checklist

1. Pull latest main.
2. Install dependencies with npm ci.
3. Run local focused verification.
4. Run broad gates for launch-sensitive changes.
5. Confirm migrations with npm run db:status.
6. Apply migrations with npm run db:deploy in the deployment pre-step.
7. Deploy.
8. Smoke the deployed URL.
9. Watch logs, queues, and provider callback health.

Rollback

Rollback depends on whether the release included schema changes.

For code-only releases:

1. Revert or redeploy the previous known-good commit.
2. Confirm /api/version and login load.
3. Smoke affected workflows.
4. Keep the incident notes with commit SHA and reason.

For releases with migrations:

1. Stop additional deploys.
2. Inspect whether the migration is backward compatible.
3. If the old code can run on the new schema, roll back code only.
4. If data repair is needed, write a forward fix migration or script.
5. Avoid destructive down migrations unless explicitly reviewed.

Hotfixes

Hotfix PRs should be narrow and include:

• Failing behavior summary.
• Root cause.
• Focused regression test or explicit reason testing is not possible.
• Deployment and rollback notes.
• Owner for follow-up hardening.

Post-Release Checks

After release, verify:

• Authenticated dashboard load.
• Case CRUD smoke.
• Task mutation smoke.
• Document upload smoke.
• Portal entry smoke.
• Integration readiness and reliability dashboards.
• Background worker health and failed-job counts.
• Error logs and Sentry events, if configured.