Land feature branches on
development through PR.Deployment & release
¶ Release Checklist
Ten steps to promote development to main and prove the release landed. main is production, nothing runs on the pull request, and every gate fires after the merge.
10 steps, in order
Exactly one Alembic head
Owner approval per release
Evidence in SHIPPED.md
Phase 1 · Prepare
¶ Get development ready to promote
Check split Alembic heads from
apps/api; exactly one head is required.
Check
cd apps/api && alembic heads # must print exactly one lineIf needed, merge heads on
development before opening the promote PR.
Merge heads
alembic merge heads -m "merge <branch-a> and <branch-b>"Doing this before the merge means one push, one diff window, and both components build in a single clean run. See the Alembic split-head checklist.
Phase 2 · Promote
¶ Open the promote PR and merge it deliberately
Open
development to main.Remember that
Checks 0 is expected and proves nothing.Neither deploy workflow has a pull_request trigger, so CI never blocks the merge.
Step 6 · Approval gate
¶ Merge only with owner approval for this specific release
Approval does not carry over from an earlier release. Merging to main starts the production deploy.
No approval, no merge
Approval is per release
Phase 3 · Deploy & verify
¶ Watch the pipeline and prove production is healthy
Watch GitHub Actions and inspect the printed changed-file list.
A green run can still deploy nothing if the changed-file detection marks both components false. Check the list, and use workflow_dispatch if a component was missed (failure modes).
Confirm DigitalOcean deployment reaches
ACTIVE.Probe
/healthz.Frontend changes are staged, not live. The Vercel production deploy waits for a manual promote. Promote it only after steps 8–9 pass, so the new frontend never talks to the old API. See deploy-web.yml → Promoting.
Feature rollouts
¶ Releases that need their own order
¶ Pairing import queue
Order: connector change first, then the API, then the web client immediately after. Following that order avoids a connector/API mismatch during the rollout.
Migration: run 0147_pairing_import_queue before promoting the API. It is safe (it uses IF NOT EXISTS) but must be present for the API to rely on the new columns.
Verify: the heartbeat reports import_capacity in connector logs. Exercise a first-time WhatsApp pairing to observe the queue position, then scan the QR when admitted. Check PAIRING_QUEUE_ENABLED and lease renewals if troubleshooting.
¶ Workspace types (Personal vs Business)
Migrations first: alembic upgrade head adds organizations.workspace_type. Existing orgs are backfilled to business, and the column has a server default of business.
Environment: set PLATFORM_ACCOUNT_EMAIL on the API process to the Developer Team's email to enable Business auto-add. Empty means the feature is off: no auto-add and no guard.
Order: API first with the env set, then web, so older browser tabs do not hit unexpected errors when the UI dialog field is required. Business workspaces auto-add the configured platform account as admin at creation; Personal workspaces refuse that account on invite and share-link joins.
Phase 4 · Record
¶ 10. Append SHIPPED.md
Record rerunnable evidence for the release, in the same one-line format as the Shipped Log.
Actions run idThe GitHub Actions deploy run
Deployment idThe ACTIVE App Platform deployment
Image digestsThe deployed image
sha256: digests
ProbesHealth and live checks you ran