feat(deploy): prepare manual Paradev staging deployment

Merged
KI
5d ago
+547-0

What & why

Prepare a manual deployment of the separate Paradev API/web projects using existing production configuration, with browser traffic restricted to api.stage.paradev.com and app.stage.paradev.com. API token identity remains api.superset.sh.

#9687 is merged; this PR targets main. This workflow runs only by manual dispatch on main. It does not run migrations, redeploy workers, change marketing links, or move live domains. Exact project/domain ownership checks and --skip-domain prevent implicit promotion of attached domains; only the two staging aliases are assigned after both builds succeed.

The new projects, public project variables, and verified staging domain attachments are configured. The workflow was executed after merge on main 6dcb20252acb34dd8deb99c35a5f4ad646b6604f; both staging deployments now use production configuration.

Validation

  • actionlint passed with the existing Blacksmith runner configured.
  • Embedded Bash syntax and Python compilation passed.
  • Environment/runtime passthrough parity checked against existing API/web production jobs, with explicit staging overrides.
  • Eleven mocked ownership/identity/failure scenarios passed, with no writes on rejected cases.
  • Independent review completed with no blocking defect; pinned Vercel 50.22.1 --skip-domain support independently confirmed from published CLI source.
  • Coordinator reran actionlint and eleven mocked guard scenarios successfully. Stage aliases point only to their expected new projects. Google staging callback was appended and persisted with existing callbacks preserved.
  • Production staging runtime validation completed successfully; see the final acceptance evidence below.

Production secrets remain exclusively in GitHub Actions. The runbook describes designated-account sign-in and marketing-to-stage analytics testing, plus vendor callback prerequisites. Review and merge are required before a staging dispatch.


Summary by cubic

Prepares a manual-only Paradev staging deploy workflow and runbook so api.stage.paradev.com and app.stage.paradev.com can serve production state without touching live domains.

  • The workflow dispatches manually on main only, and never runs migrations, redeploys workers, or updates marketing links.
  • Projects, public project variables, and verified staging domain attachments are preconfigured; the two staging aliases are assigned only after both builds succeed.
  • Ownership, identity, domain, and alias checks run before and during the deploy; --skip-domain prevents implicit promotion of attached domains.
  • Secrets stay in GitHub Actions, and missing or mismatched project variables fail closed.
  • docs/paradev-staging.md documents prerequisites, restricted testing expectations, and the Google OAuth redirect registration for the stage auth callback.

Migration

  • Confirm both projects exist with root directories apps/api and apps/web under VERCEL_ORG_ID.
  • Verify api.stage.paradev.com and app.stage.paradev.com are already verified on their respective projects without redirects, branch targeting, or custom environments.
  • Register https://api.stage.paradev.com/api/auth/callback/google as an Authorized redirect URI on the production Google OAuth client before dispatching.

Latest GitHub CI (Lint, Test, Typecheck, CLI build, page-storage integration) and ordinary isolated preview deployment run passed on 12222c79a3. Those previews are separate from the unexecuted production staging workflow.

Summary by CodeRabbit

  • New Features
    • Added a manually triggered staging deployment for the API and web app from the main branch. Staging addresses are assigned only after both deployments pass validation.
  • Documentation
    • Added guidance for staging deployments, configuration, testing prerequisites, and known limitations.

Final production staging acceptance

Manual staging run 43332717765 passed all ownership guards, both production builds, and stage-only alias assignments. All normal production deployments triggered by the three merges also passed.

  • 22 live staging HTTP checks passed: health, OAuth/OIDC/MCP/connector metadata, CORS, desktop OAuth starts/state-cookie scope, invalid inputs, untrusted callback rejection and all six unauthenticated integration guards. No vendor grants were changed.
  • Real Browser Use Google staging sign-in, authenticated account navigation and hard reload passed with the designated existing account.
  • Real desktop Google flow completed API -> Google -> stage success -> localhost test receiver. Desktop session authenticated as the expected user, and issued JWT verified against legacy api.superset.sh JWKS, with legacy issuer/audience and correct subject. Only the new test desktop session was signed out; the browser session remained valid. Test receivers stopped; tokens were never logged or persisted.
  • Cua Driver drove real Chrome from https://paradev.com/?domain_validation=20261112-staging to stage sign-in, Google login, and the authenticated stage account page. Account reload preserved authentication.
  • Production PostHog project264803 confirms marketing pageview (2026-11-12 23:59:39 UTC), stage sign-in pageview, signed-in pageview, and identify (2026-11-13 00:02:52 UTC) all resolve to one identified person. $identify carries the exact original marketing anonymous ID 01a1d1e7-cfa2-7a0c-b489-0466aa4355bf into account ID 1cb76e90-6e41-46c9-b587-50a690bb59d7; persons row is_identified=1.
  • Existing production app.superset.sh account/session/reload/integrations and real Google reauthentication passed after #9687 deployed. Both API hosts remain healthy with the legacy issuer/authorization endpoint.
  • Verified live API domains still belong to original API project and live app domains to original web project. app.paradev.com still redirects to app.superset.sh. Marketing destination links and released-client redirects were not switched.

No public cutover, integration authorization/sync, billing mutation, or installed-desktop session replacement was performed. Production event writes were confined to the explicit designated-account validation journey. Full vendor authorization flows and the eventual public cutover still require their own validation.