feat(web-deploy): deploy web to vercel with previews and branch promotion

[tataihono]

Background

The web app needs a deployment model that supports continuous preview for pull requests plus deterministic branch promotion (stage -> stage, main -> production). Environment variable management must use AWS SSM Parameter Store, and deployment triggering must be constrained by Turbo affected detection to avoid unnecessary runs.

Expected outcome

A Terraform-managed Vercel setup and CI pipeline where PR previews are automatic, stage and main map to stage/prod targets, and secrets flow from AWS SSM Parameter Store. Deploy runs are branch-aware, gated, auditable, and documented.

Acceptance criteria

• Vercel project and environment wiring are managed from infra/vercel.
• Every PR receives an automatic preview deployment.
• Pushes to stage deploy to stage target.
• Pushes to main deploy to production target.
• Web deployment secrets are sourced from AWS SSM Parameter Store for the required environments and integrated into the deployment workflow.
• Web deploy jobs run only when Turbo affected indicates @forge/web (or dependency graph impact).
• Deploy flow includes environment protection/approval where required.
• Rollback and verification runbook exists and is validated.

Possible solution(s)

1. Single Vercel project with branch-based environment mapping (recommended)
   • Keep one project; use branch policies and environment-specific variables.
   • Simpler management of previews and promotion.
2. Separate Vercel projects per environment
   • Stronger physical separation but higher operational overhead.
3. Hybrid with explicit deployment aliases
   • Keep single project but enforce aliasing/promotion rules in CI for tighter control.

References

• Existing Vercel Terraform entrypoint: infra/vercel/main.tf
• Existing web env contract: apps/web/src/env.ts
• CI baseline: .github/workflows/ci.yml
• Terraform plan baseline: .github/workflows/terraform-plan.yml
• Related planning artifact: /Users/macuser/.cursor/plans/deployment-epic-plan_bde653f7.plan.md
• Depends on CMS AWS outputs (stage/prod CMS endpoints + token contracts) from epic feat(cms-deploy): deploy cms to aws with stage/prod #67

[tataihono]

Sub-ticket breakdown created for this epic:

• feat(infra-vercel): provision web project previews and branch environments #74 feat(infra-vercel): provision web project previews and branch environments
• feat(ci): automate web deploy pipeline with turbo affected gating #75 feat(secrets): integrate doppler project web for preview stage prod
• feat(secrets): integrate doppler project web for preview stage prod #76 feat(ci): automate web deploy pipeline with turbo affected gating
• docs(runbook): web vercel deployment rollback and verification guide #77 docs(runbook): web vercel deployment rollback and verification guide

Suggested execution order: #74 -> #75 -> #76 -> #77.

Dependency note: begin after CMS epic #67 defines stable stage/prod CMS endpoint + token contract.

[tataihono]

Updated to reflect the current direction: AWS SSM Parameter Store is now the secrets/config source of truth for this deployment work, replacing prior Doppler assumptions in the issue definition.