Web release flow

dev is the trunk branch. Product work merges there through the normal PR and merge-queue path.

Production releases do not use main. A release is frozen on a temporary release/web-* branch, promoted from a Vercel production candidate, and archived by a protected web-prod-* tag. Release-only fixes return to dev through a normal backmerge PR.

Naming

Use two names consistently:

• lane staging: https://staging.today.ai, built from a release/web-* branch with NEXT_PUBLIC_TRAFFIC_LANE=staging. Browser requests and BFF upstream calls send X-Traffic-Lane: staging.
• production candidate: a production-mode Vercel deployment built from the same release branch without NEXT_PUBLIC_TRAFFIC_LANE. It has a preview URL and is promoted to https://today.ai only after approval.

The lane staging artifact cannot be promoted to production because the browser bundle already contains the staging lane value. The production candidate is a separate rebuild from the release SHA.

Normal Release

1. Run Cut Web Release Branch from dev. This creates a temporary release/web-* branch at the chosen dev SHA.
2. The release branch push starts CI and Deploy Web Lane Staging. The workflow builds with production API/auth settings plus NEXT_PUBLIC_TRAFFIC_LANE=staging, then aliases the deployment to https://staging.today.ai.
3. During validation, add release fixes only to the release branch. Do not rebase the release branch after staging validation starts.
4. Run Promote Web Production from the release branch. Leave skip_staging=false for the normal path.
5. The workflow builds a production candidate from the release SHA without a traffic lane and prints the candidate preview URL.
6. The web-production environment approval pauses the workflow. Validate the candidate preview URL, then approve.
7. The workflow checks that the release branch still points at the same SHA, runs vercel promote <candidate>, verifies https://today.ai, creates a web-prod-* tag, and opens a release-to-dev backmerge PR if needed.

Skip Staging

For an urgent or low-risk release, run Promote Web Production directly from a release/web-* branch with skip_staging=true.

This skips the https://staging.today.ai check but still rebuilds and pauses on the production candidate preview before promote.

Backmerge

Release fixes must land back on dev. The production workflow creates the PR after promotion when dev does not already contain the promoted release SHA. It creates a backmerge/web-* branch from the promoted SHA and uses that branch as the PR head so the release/web-* branch stays frozen as release evidence. Resolve conflicts in the backmerge PR manually and let the merge queue own the final merge. Do not force conflict resolution into the production promote workflow.

Branch Cleanup

Keep release/web-* branches through the immediate hotfix window. After the release tag exists and release-only fixes are backmerged, delete the release branch. The durable production record is the web-prod-* tag and the Vercel deployment promoted to today.ai.

Backmerge branches are work branches only. Delete backmerge/web-* after the backmerge PR is merged or closed.