9.3 KiB
Staging, Live, and UAT Readiness
Scope
Use this runbook after local implementation is complete and before a release owner treats the boilerplate as production-ready. It prepares the manual runtime and browser evidence that cannot be proven by local static checks alone.
This document does not approve automatic browser automation, provider-console access, production traffic inspection, or ad hoc live Docker, registry, and Coolify execution outside the configured Gitea deploy workflow. The configured deploy workflow is the automated exception for Docker publish, registry promotion, Coolify, migration, and health checks; all other live actions need manual records with owner, target, date, release label, status, and redacted correlation identifiers.
For authenticated local Playwright fixture preparation, use E2E Readiness Fixtures. Those local fixtures are evidence inputs only; staging/live readiness still requires the manual, redacted records in this runbook.
Readiness stages
| Stage | Goal | Exit record |
|---|---|---|
| Local static gates | Confirm the repo is locally assembled before any deployed target is touched. | Command labels, exit code labels, and short pass or fail summaries. |
| Staging environment contract | Confirm web, API, worker, database, Redis, storage, and provider configuration are present by key name. | Target label, runtime surface labels, missing or present status, and redacted diagnostic codes. |
| Runtime smoke records | Exercise provider-backed flows one surface at a time. | Provider category, request ID or job ID, status label, and redacted outcome. |
| Browser UAT matrix | Review critical user journeys against staging. | Journey label, operator label, target label, status, and safe notes. |
| Final evidence packet | Combine local, staging, provider, browser, rollback, and known-risk records. | Release checklist entry with no raw secrets, customer data, or screenshots containing private data. |
Local static gates
Run these before creating staging evidence:
pnpm run typecheck
pnpm run lint
pnpm run verify:ci-baseline
pnpm run verify:env-drift
pnpm run verify:openapi-security
pnpm run verify:db-migrate-status
pnpm run verify:deploy-workflow
pnpm run verify:release-docs
pnpm run verify:docs-links
pnpm run verify:staging-live-uat-readiness
Record only command name, exit code, checked surface, and a short pass or fail summary. Do not paste environment dumps, provider payloads, stack traces with secrets, database rows, tenant identifiers, or customer data.
Staging environment contract
The staging target should be production-like enough to exercise these runtime surfaces independently:
| Surface | Required status before smoke | Evidence boundary |
|---|---|---|
| Web app | Deployed target label, health status, session-cookie policy label. | No cookies, user data, or customer hostnames. |
| API app | Deployed target label, health/readiness status, OpenAPI status. | Request ID and status only. |
| Worker | Enabled or intentionally disabled label, queue registration status. | Queue names, job IDs, retry counts, and redacted dependency codes only. |
| Postgres | Migration deployment path, migration status, backup or restore-point readiness. | Migration IDs, phase labels, and redacted diagnostic codes only. |
| Redis | Queue connectivity status for worker-backed features. | Key names such as BULLMQ_REDIS_URL or REDIS_URL, not values. |
| S3-compatible storage | Bucket label, signed upload/download status, object access status. | Bucket label, object key class, status, request ID. |
| Mailjet | Sender-domain status, outbound delivery class, webhook signing class. | Provider category, job ID, request ID, delivery status. |
| Stripe | Checkout or billing callback status when billing is in scope. | Provider category, event type label, request ID, no payload. |
| ClamAV | Scanner reachable or intentionally deferred label. | Scanner status, verdict label, job ID, no file contents. |
Runtime smoke records
Run provider-backed checks one at a time. Stop when a surface fails, record the redacted failure, and do not continue dependent journeys until the owner resolves it.
| Smoke | Depends on | Pass record |
|---|---|---|
| Health and readiness | Web, API, database config. | Web status, API status, request ID. |
| Migration status in CI | DATABASE_URL in the target runner. |
Runner label, command label, exit status. |
| Worker queue | Redis and worker enabled. | Queue name, job ID, processor status. |
| Mail delivery | Redis, worker, Mailjet config. | Mail job ID, provider category, delivery status. |
| Mail webhook | API target and Mailjet signing config. | Webhook route label, signing status, request ID. |
| Storage upload/download | API target and S3-compatible storage config. | Upload status, signed download status, request ID. |
| Storage scan | Storage object and ClamAV scanner. | Scan job ID, verdict label, quarantine status. |
| Billing checkout | Web target, API target, Stripe config. | Checkout status, webhook status, request ID. |
Code-gap tracking before live confidence
The staging-blocking local code gaps have repository evidence and should be verified before creating runtime records. Full live confidence still requires manual target evidence in the later sections.
| Area | Repository evidence | Staging impact |
|---|---|---|
| API-key cutover | Stored API-key lookup is hash-first and API_KEY_LEGACY_PLAINTEXT_FALLBACK is disabled by default; enable it only for a bounded pre-cutover migration window. |
Staging records only boolean fallback status and never API-key material. |
| Storage lifecycle | Upload requests have MIME and size enforcement before storage writes, while object access keeps tenant and scan-status authorization checks. | Storage smoke can prove upload rejection, signed download, scan verdict, and blocked or quarantined object behavior separately. |
| Imports | Dry-run persists inspection state through the tenant web internal/imports/dry-run route, and tenant internal/imports/submit creates a final import job and enqueues import.run. |
Browser UAT can cover dry-run, mappings, final submit, worker pickup, and completion status. |
| Retention operations | /v1/maintenance/export-retention/enqueue queues expired-export-artifacts, and the worker uses the maintenance queue to hard-delete expired export artifacts. |
Retention smoke can validate service-token access, enqueue status, job ID, and worker result without exposing storage keys. |
| Legacy API migration | Remaining root-route compatibility is an explicit staging compatibility boundary, not an untracked code gap. | Staging is ready when the release record names the retained compatibility boundary and any post-staging extraction owner. |
Browser UAT matrix
Browser UAT is manual unless separately approved. Use staging accounts and synthetic data only.
| Journey | Required evidence |
|---|---|
| Login and tenant switch | Browser journey label, status, request ID when available. |
| MFA step-up | Admin route label, challenge status, success or denial status. |
| API-key create, copy, rotate, delete | Journey label, one-time-secret display status, redaction status. |
| Workspace settings and onboarding | Settings section labels, onboarding visibility status, redacted diagnostics. |
| Notifications | Notification center status, SSE reconnect status, optional mail job ID. |
| Imports | Dry-run status, mapping diagnostics, final-submit status, worker pickup status. |
| Exports | Enqueue status, worker status, signed download status. |
| AI review-before-apply | Review-required status, approval or rejection status, audit status. |
| Theme, PWA, error, maintenance pages | Visual status labels, installability status if reviewed, no screenshots with private data. |
| Audit and CSV export | Permission status, filter status, export status. |
Final evidence packet
Before a release owner marks staging/live/UAT complete, collect:
- Local static gate summary.
- Deployed target labels for web, API, and worker.
- Migration status and backup or restore-point readiness.
- Runtime smoke table with pass, fail, deferred, or owner-needed status.
- Browser UAT matrix with pass, fail, deferred, or owner-needed status.
- Code-gap table with fixed, compatibility-boundary, defer, or out-of-scope decision.
- Rollback class from docs/production-checklist.md.
- Redaction review status from docs/security.md.
Redaction boundary
Safe evidence includes command names, exit code labels, target labels, route labels, provider categories, request IDs, job IDs, queue names, migration IDs, release labels, and redacted diagnostic codes.
Unsafe evidence includes raw environment values, database URLs, Redis URLs, provider credentials, webhook values, Stripe payloads, Mailjet payloads, object-storage credentials, cookies, bearer tokens, customer data, tenant identifiers, file contents, screenshots containing private data, and full logs that may contain any of those values.
Verification
The static contract for this runbook is:
pnpm run verify:staging-live-uat-readiness
This verifies that the runbook and its supporting release documents exist, that required local command labels are present in package.json, and that the readiness record keeps live runtime and browser activities manual and redacted.