Environments & Release Flow

This page explains how Tuturuuu moves from code to running environments.

​

Branch-to-Environment Map

​

Hosted Web Release Flow

​

Preview

• Preview workflows are named vercel-preview-<app>.yaml.
• They trigger on non-production pushes, including main.
• e2e-tests.yaml also runs only on non-production pushes; production promotion relies on the already-green validation before the branch is promoted plus the production deployment gates below.
• Each workflow checks whether a newer commit exists on the same branch before spending time on install/build/deploy.
• Each deploy job is bound to a vercel-preview-<app> GitHub Environment and introduces Vercel credentials only after dependency installation.
• Preview deploys are the normal validation surface for branch work and merged main changes.

​

Staging Database

• supabase-staging.yaml is tied to the Vercel Platform Preview Deployment workflow on main.
• The staging migration runs only when the triggering preview deployment concludes successfully, or when manually dispatched.
• The staging deploy step runs supabase db push --include-all after linking the staging Supabase project, so staging can converge after main migration history changes.
• This means main is where app preview and staging schema advancement are meant to stay aligned.

​

Production

• Production web deploys run through vercel-production-<app>.yaml.
• apps/web production deploys are handled by vercel-production-platform.yaml.
• apps/apps production deploys are handled by vercel-production-apps.yaml.
• apps/qr production deploys are handled by vercel-production-qr.yaml.
• The production workflow also skips if a newer commit already exists on production.
• Production deploy jobs are bound to vercel-production-<app> GitHub Environments and reject manual dispatches unless the selected branch is production.

​

Browser App Version Metadata

• Browser apps share one platform version from packages/utils/src/platform-release.ts; do not read visible app versions from individual app package.json files.
• The current shared browser app version is 0.1.32.
• Every Vercel browser app workflow runs bun run --silent scripts/ci/generate-build-metadata.ts before vercel build. The generated metadata includes the commit hash, short hash, commit message, ref, environment, deployment URL, deployment stamp, and build timestamp.
• The account-scoped version badge uses public.user_configs key SHOW_VERSION_BADGE. It is hidden by default and only exact @tuturuuu.com accounts may enable a truthy value.
• Exact-domain enforcement happens on the server through isExactTuturuuuDotComEmail; subdomains such as @xwf.tuturuuu.com are not eligible, and client cookies cannot make the badge render for ineligible users.

​

Production Database

supabase-production.yaml is stricter than staging:

1. It re-evaluates automatically after either Vercel Platform Production Deployment completes on production or Supabase Staging Migration completes on main.
2. The production Vercel deployment for the target commit must have concluded successfully on production.
3. The main staging migration for the same target commit must have completed with a success conclusion.
4. A manual dispatch can still be used when an operator explicitly wants to run it, but the dispatch must select the production branch and still satisfy the same production-deployment and staging-migration SHA checks.

The staging-triggered path is an automatic retry for the case where production deployment finishes before staging migration does. The production migration job still checks out the verified target commit explicitly before running supabase db push. This keeps production schema changes behind application deployment success, staging validation, and branch promotion for the same commit.

​

Self-Hosted Web Release Flow

If a server receives code through git pull, use the Docker production commands from the checked-out commit:

• bun serve:web:docker for in-place replacement
• bun serve:web:docker:bg for blue/green rebuild-before-cutover deployment

Blue/green is the safer path when uptime matters because the new image is built and health-checked before the proxy is reloaded.

​

Team Release Checklist

1. Merge the change set with green CI.
2. If Docker behavior changed, make sure docker-setup-check.yaml is green.
3. If database migrations changed, confirm the main-driven staging path first.
4. Promote to production only after preview and staging behavior is understood.
5. Confirm the follow-up Supabase workflow after production deployment.
6. For self-hosted rollout, deploy from the intended commit and prefer bun serve:web:docker:bg.

​

Rollback Guidance

• Vercel-hosted rollback: redeploy the previous known-good commit or use Vercel rollback tooling.
• Supabase rollback: use a corrective migration instead of editing applied migration history.
• Self-hosted Docker rollback: checkout the previous known-good commit and rerun bun serve:web:docker:bg.

​

What Not To Do

• Do not push production schema changes directly from a laptop as the normal path.
• Do not assume staging and production migrations are interchangeable; they are gated differently.
• Do not manually dispatch production Supabase migration from main; the only valid main path is the automatic staging-migration re-evaluation, and the production gate still requires the same commit to have both a successful production deployment and a completed successful main staging migration.
• Do not use the in-place Docker path when you specifically need rebuild-before-restart semantics.