Branching & deployment

Supabase branching

Two shared Supabase projects:

Project	Purpose
movement-mapping-dev	Shared dev project. CI applies merged migrations here.
movement-mapping-prod	Production. Only CI applies migrations here.

No local branch isolation right now

Per-git-branch Supabase branches are disabled. The org is on the Supabase free plan, which doesn’t support Preview Branching at all — it’s a Pro/Team-only feature. We discovered this the hard way: creating a “branch” via the Management API on the free plan doesn’t provision an isolated database — it returns a branch record whose project_ref is identical to the parent project’s, marked is_default: true. In practice this means every git branch was silently applying its migrations directly to the shared movement-mapping-dev project, with no isolation at all, while looking like it worked.

Until we upgrade to Pro, local development works like this instead, managed by scripts/supa (see Migration workflow):

1. Every git branch — protected or not — targets movement-mapping-dev directly. There is no per-branch database; ./scripts/supa pnpm dev and ./scripts/supa db push always point at the same shared project.
2. Migrations are still refused on protected branches (main/master/dev/develop). This is now the only safety net: it forces schema changes to be authored on a feature branch and reviewed via PR before they can be applied — even though, pre-merge, they land on the same shared dev project as everything else. Coordinate schema changes with whoever else is using the dev project.
3. On PR merge, CI applies migrations to movement-mapping-dev again (a no-op if you already pushed them from your feature branch).
4. On release, CI promotes the same migrations to movement-mapping-prod.

Re-evaluate this when the team grows past one developer, or when the ~500MB free-tier database limit gets tight anyway (both are reasons we’ll need Pro regardless). scripts/supa-create-branch.sh and scripts/supa-get-branch-ref.sh still contain the Management API calls for real per-branch isolation and are kept, unused, specifically to be reconnected then — see the header comment in scripts/supa. Once on Pro, the x-supabase-branch header plumbing in src/lib/supabase/server.ts/client.ts doesn’t need to change: it already treats an unset branch ref as “no header,” so restoring branch-ref resolution in scripts/supa is the only change needed.

Project-level provisioning (not covered by migrations)

supabase/migrations/*.sql only reaches the database. A handful of settings live at the Supabase project level instead, and a brand-new project (or a recreated one) starts without them:

• PostgREST’s exposed-schema list defaults to public, graphql_public — app and network are invisible to the API until added, regardless of RLS.
• The Auth site_url defaults to http://localhost:3000 on a new project — it’s what {{ .SiteURL }} resolves to in Auth email templates (confirmation, magic link), so without setting it, confirmation emails link back to localhost no matter what environment sent them.
• The Auth redirect allow-list starts empty, so /auth/confirm and /auth/callback are rejected as invalid redirect targets.

scripts/supa-configure-project.sh [project-ref] sets all three (idempotent), and runs automatically from scripts/supa-first-run.sh whenever a project has no migrations yet — so this covers the local shared/parent project by default. It must also be run once against movement-mapping-dev and movement-mapping-prod when each is first provisioned, since CI only ever applies migrations there, never this script. Run it from a checkout with no local .env (or a temporarily moved-aside one) — the script re-sources .env if present, which silently overrides SUPABASE_PROJECT_REF/SITE_URL passed on the command line:

SUPABASE_PROJECT_REF=<dev-or-prod-ref> SITE_URL=<its-public-url> \
  ./scripts/supa-configure-project.sh

One more setting needs a decision before it can be scripted: Auth email template customisation (the “Confirm signup” and “Magic Link” templates) is blocked by Supabase on the free tier without a custom SMTP provider — without it, both templates keep the default {{ .ConfirmationURL }} link instead of the token_hash-based link /auth/confirm expects, so email confirmation and magic-link sign-in silently fail (you land back on /setup or /login logged out).

This project uses Resend as the custom SMTP provider. Once you have a domain verified in Resend and an API key, set RESEND_API_KEY and SMTP_SENDER_EMAIL (optionally SMTP_SENDER_NAME) and re-run scripts/supa-configure-project.sh — it configures Resend as the project’s SMTP relay and pushes the branded templates from supabase/templates/ (confirmation.html, magic-link.html) via the Management API. Without those variables set, the script skips this step and prints the template text to set by hand instead (Dashboard → Authentication → Email Templates).

Render deployment

Deployment is config-as-code in render.yaml, with two services pinned to the EU (Frankfurt) region:

• a web service for apps/app (the TanStack Start Node server), and
• a static site for apps/docs (built and published from apps/docs/dist).

There is no manual dashboard configuration; secrets are set in Render’s environment, not committed. See Environment variables.

CI

• .github/workflows/ci.yml — on PRs and pushes to main: frozen-lockfile install, biome check, typecheck, build of both apps, and a Socket.dev supply-chain check.
• .github/workflows/db.yml — applies migrations to movement-mapping-dev on merge to main, and promotes them to movement-mapping-prod on release.
• .github/workflows/supabase-branch-cleanup.yml — deletes a git branch’s Supabase branch when the git branch is deleted.