Deployment

The repo's active deploy paths are split by ownership:

• apps/web is owned by GitHub Actions prebuilt deploys.
• apps/dev-docs and apps/webview-bridge-docs are owned by Vercel's Git Integration.

The admin console (today-admin Vercel project, admin.today.ai) is deployed from todayai-labs/today-admin.

For the underlying conceptual model, see Architecture -> Vercel deploy model.

Web Environments

Use the terms precisely:

• lane staging is staging.today.ai, tied to backend lane routing. Its web build injects NEXT_PUBLIC_TRAFFIC_LANE=staging, so browser clients and BFF upstream fetches send X-Traffic-Lane: staging.
• production candidate is a separate production build from the same release SHA without NEXT_PUBLIC_TRAFFIC_LANE. It is the only artifact that may be promoted to today.ai.

Because NEXT_PUBLIC_TRAFFIC_LANE is baked into browser JavaScript, promoting a lane staging build to production would leak the staging lane into production traffic. The production candidate therefore rebuilds from the release SHA.

Web Release Pipeline

See Web release flow for the operator checklist. The workflow files map to these stages:

1. cut-web-release.yml creates a temporary release/web-* branch from dev or another explicit source ref.
2. deploy-web-lane-staging.yml waits for CI, builds a production-mode artifact with NEXT_PUBLIC_TRAFFIC_LANE=staging, deploys with --prod --skip-domain, and aliases it to staging.today.ai.
3. promote-web-production.yml waits for CI, builds the production candidate without lane env, pauses on the web-production approval gate, verifies the release branch SHA did not move, promotes to today.ai, tags the release, and opens a backmerge/web-* PR to dev when needed.

promote-web-production.yml has skip_staging. Use it only when you want to skip the lane staging check and inspect the production candidate preview directly.

Required Vercel Setup

For today-web:

• Actions own CLI deploys. Keep Vercel Git auto-deploy disabled for the project.
• today.ai is the production domain.
• staging.today.ai is an Actions-owned alias for lane staging deployments.
• The custom Vercel staging environment should not track main; lane staging is built by GitHub Actions from release/web-* using the production environment plus workflow-injected lane variables.
• Do not set X-Traffic-Env or LANE_STAGING_TRAFFIC_ENV; the web lane contract is NEXT_PUBLIC_TRAFFIC_LANE=staging at build time and X-Traffic-Lane: staging on requests.

GitHub needs these shared variables/secrets:

• vars.VERCEL_ORG_ID
• vars.VERCEL_PROJECT_ID_WEB
• secrets.VERCEL_TOKEN
• vars.TODAY_PLATFORM_CI_APP_ID
• secrets.TODAY_PLATFORM_CI_APP_PRIVATE_KEY
• secrets.POSTHOG_PROJECT_TOKEN_DEV
• secrets.POSTHOG_PROJECT_TOKEN_PROD
• optional source-map upload secrets: POSTHOG_API_KEY, POSTHOG_PROJECT_ID_DEV, POSTHOG_PROJECT_ID_PROD, SENTRY_AUTH_TOKEN

PR Previews

deploy-web.yml handles only dev and PR preview deployments. It uses Vercel preview env vars, waits for the required CI checks on the same SHA, deploys a prebuilt preview artifact, and comments the preview URL on PRs.

Docs Sites

apps/dev-docs and apps/webview-bridge-docs deploy through Vercel's Git Integration. Do not add GitHub Actions deploy workflows for them unless the app is explicitly migrated to Actions-owned prebuilt deploys and its vercel.json disables Vercel Git deploys at the same time.

Rollback

Vercel keeps every deploy. Runtime rollback is a human-selected Vercel rollback or promotion of a previous deployment.

For code-level rollback, create a revert PR against dev, let it land through the merge queue, cut a new release/web-* branch, and run the normal promote flow. The durable production archive is the web-prod-* tag, not main.