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.
• Most preview workflows are manual-only from main with a required preview_ref; vercel-preview-platform.yaml also triggers on protected main pushes so the staging database workflow receives a same-SHA platform build signal.
• 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 build-validation 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.
• Platform preview is build validation only; on-premise machines own the actual apps/web runtime deployment.
• Satellite preview deploys remain the normal Vercel validation surface for branch work and merged main changes.
• Platform preview and production build validation workflows cross-credit successful same-SHA build markers. If one has already passed for a commit, the other can record success without reinstalling dependencies or rebuilding.

​

Staging Database

• supabase-staging.yaml is tied to the Vercel Platform Preview Deployment workflow on main.
• The staging migration runs only when the triggering platform preview build 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.
• If a production commit was promoted before the same-SHA staging migration run existed, manually dispatch supabase-staging.yaml from main; production migration re-evaluates after that staging run succeeds.

​

Production

• Satellite production web deploys run through vercel-production-<app>.yaml.
• apps/web production build validation is handled by vercel-production-platform.yaml; on-premise machines handle the actual runtime deployment.
• 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 its build validation on production or Supabase Staging Migration completes on main.
2. The production platform build validation 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 build validation finishes before staging migration does. The production migration job still checks out the verified target commit explicitly before running supabase db push --include-all. This keeps production schema changes behind application build validation, 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 build validation.
6. For self-hosted rollout, deploy from the intended commit and prefer bun serve:web:docker:bg.

​

Rollback Guidance

• Vercel-hosted rollback: for satellite apps, 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 platform build and a completed successful main staging migration.
• Do not use the in-place Docker path when you specifically need rebuild-before-restart semantics.