Skip to main content
This guide covers hosted QA and release promotion only. Follow Agentic Development for feature branches, worktree creation, pull requests, commit history, and integration ownership.

​
Deployment lanes

Overlay has two backend lanes that must stay paired with their matching web deployment: A feature worktree must never change production Convex. The main app and production Convex are a single release unit: deploy them only from an up-to-date, clean main worktree. The development Convex deployment is shared by local development and staging.getoverlay.io. A Convex change from one branch changes that backend for every user of this lane. Do not run concurrent staging QA sessions that make incompatible changes under convex/.

​
Prepare the staging release candidate

Use one dedicated, long-lived worktree for the shared staging branch. Reuse it for every sequential Builder pull request; the Integration agent does not create a new worktree per PR or check out each feature branch into this worktree. This prevents a feature worktree from accidentally becoming the staging or production deployment source while avoiding duplicate checkouts.
The Builder normally opens its pull request against staging and stops at submission. The Integration agent reviews the diff and required checks, then merges the Builder PR into staging through GitHub. If DevelopedByDev explicitly authorizes the owner-only direct-push fast path, the Integration agent instead performs the documented local review and checks, integrates in this dedicated staging worktree, confirms a fast-forward update, and pushes without force. A direct staging push normally starts the staging Vercel build. Review feature branches through GitHub and the pull request diff. After each merge, update this same staging worktree to the exact remote staging revision before testing. Create a short-lived additional worktree only when an unusual conflict or side-by-side investigation cannot be performed safely in the dedicated staging worktree; remove it after the investigation. After that merge, update the dedicated staging worktree to the exact remote revision:
Both SHAs must match. Record the staging SHA before testing. Do not force-push staging; if a candidate must be removed, create a revert commit so staging history stays auditable. Prefer one release candidate at a time. If the Integration agent intentionally batches several Builder PRs, record every included PR and test the combined staging revision. The staging Vercel project is branch-gated to staging to keep build costs predictable:
  • Its Git production branch is staging.
  • DEPLOY_BRANCH=staging is configured for both the Preview and Production environments.
  • bash scripts/vercel-ignore-build.sh is the project’s Ignored Build Step. With the staging target, it runs only when VERCEL_GIT_COMMIT_REF exactly matches DEPLOY_BRANCH; missing variables, missing branch refs, pull-request branches, manual deployments, and deploy hooks are skipped (Vercel exit 0). If the shared script is ever reused for another explicit target, its no-ref manual-release behavior remains available for that target.
  • Preview deployment sources remain disabled. The project therefore has one hosted QA lane: the staging branch’s deployment.
When changing this policy, verify the project settings and run the guard locally with both matching and non-matching branch refs before merging. Do not rely on an account-level deployment-source policy alone; the repository guard is the defense that travels with the project configuration.

​
Push Convex for staging QA

If and only if the staged change includes convex/ changes, deploy the exact staging revision to the shared development deployment before testing the staging website:
Then wait for the staging Vercel build to finish and open https://staging.getoverlay.io. For every staging QA run, verify the changed flow plus these basics where applicable:
  • Authentication/session loading succeeds.
  • The affected API route or UI flow returns the expected result.
  • A chat change streams, completes, and persists after a refresh.
  • A billing or entitlement change creates and finalizes its expected usage state.
  • Browser console and staging runtime logs have no new errors.
If staging is broken after a Convex schema or function change, first restore the shared development deployment by checking out the last known-good staging commit in the dedicated staging worktree and running npm run convex:push:dev. Never use a feature worktree or production deployment as the rollback source.

​
Remote Postgres contract QA

overlay-web-postgres.vercel.app is the dedicated Vercel/Neon lane for Postgres checks. When local disk or Docker is unavailable, do not start Postgres or Redis locally. Deploy the reviewed revision with npm run smoke:remote-postgres running in the Vercel build environment; the script applies app-data migrations and executes the Postgres repository contract suite using the linked production project environment. Record the migration schema version, the complete contract count, and the Vercel build result before claiming Postgres parity. This lane currently has no remote Redis resource; Redis checks remain unverified until a remote Redis environment is explicitly configured.

​
Promote a verified release

After staging passes, confirm that the tested staging SHA is still current and that the latest main is included in the candidate:
If either staging SHA differs from the recorded QA revision, or if the ancestry check fails, update staging and repeat the affected QA before promotion. The Integration agent normally opens or updates a release pull request from staging to main, waits for the main-branch checks, and merges it with a merge commit. The release PR must identify every included Builder PR and the exact tested staging SHA. If DevelopedByDev explicitly authorizes a direct push to main, the Integration agent may instead fast-forward main to the exact tested staging revision after completing the owner fast-path checks in Agentic Development. The direct path must not change the tested tree or rewrite either branch. Before merging a release PR, confirm root vercel.json sets git.deploymentEnabled.main to false. Vercel evaluates this source-controlled rule for Git events, so staging continues to deploy for hosted QA while a release PR merge updates main without creating a production deployment. Do not rely on an account-level deployment-source policy alone. After the merge, verify both the exact origin/main SHA and that Vercel created no production deployment for it, then align staging with the accepted merge commit so the next Builder PR has a clean comparison:
This is a non-rewriting fast-forward: the release merge commit has the tested staging revision as a parent. If it cannot fast-forward, stop and inspect the unexpected branch movement instead of force-pushing. If Vercel unexpectedly creates a production deployment, cancel it before aliases are assigned and treat the deployment gate as failed until the trigger configuration is corrected. After alignment and the no-deployment check, report the accepted SHA as merged but not deployed, then stop unless the user explicitly authorizes production deployment. Before any production Convex deploy, use the canonical main worktree and verify it is clean and matches origin/main:
After explicit user authorization, create a production build without immediately assigning the production domain:
Inspect the returned deployment and verify it was built from the accepted origin/main SHA. Promote that verified deployment explicitly:
After main is deployed to Vercel, and only when that main revision contains convex/ changes, sync production Convex from this main checkout:
Then run an authenticated smoke test on https://www.getoverlay.io. For chat, send a message, confirm the streamed answer completes, refresh the page, and confirm the message remains in the conversation.

​
Integration agent checklist

Before the Integration agent runs a Convex command, it must state:
  1. its current branch and worktree path;
  2. whether it is targeting the shared development or production deployment;
  3. why that deployment is the correct lane for the revision being tested.
The Integration agent may run npm run convex:push:dev only from the dedicated staging worktree for a staging release candidate. It may run npm run convex:push:prod only after explicit production-deployment authorization, from the clean canonical main worktree, and after main’s web deployment is live. convex:push:all is not part of the worktree workflow. The Builder never deploys Convex.