Vercel ↔ Supabase Environment Alignment

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

• Day-to-day PRs only touch the Dev environment.
• Promotions to live production are an explicit prod → production release PR.
• Supabase Branching only spins up preview DBs in one Supabase project per PR (no more duplicated Supabase Preview failures from two competing projects, as seen on PR #123/#124).

​

1. Canonical mapping

Naming gotcha. The GitHub default branch is named prod, but it is the dev tier. The branch literally named production is the live production tier. This mismatch is intentional (preserves history) but easy to misread. Do not rename.

[remotes.dev]        # paired with GitHub `prod`        and Vercel encoreos_dev
project_id = "zkgxozahyczcnzpwhbbf"

[remotes.production] # paired with GitHub `production`  and Vercel encoreos_prod
project_id = "srcaoozjkrughebmbvfb"

​

2. PR / deployment lifecycle

​

2.1 Feature work (default)

1. Branch off prod: git checkout -b cursor/<task>-####.
2. Open a PR with base = prod.
3. On open, the following side effects occur:
   • Vercel encoreos_dev builds a Preview Deployment, statically pinned to Supabase zkgxozahyczcnzpwhbbf.
   • Supabase Encore OS (zkgxozahyczcnzpwhbbf) Branching creates a per-PR preview DB and replays migrations. The Supabase Preview GitHub check reports its status.
   • Vercel encoreos_prod and Supabase encore_os_prod are not touched (see §3 for how this is enforced).
4. Merge to prod ⇒ Vercel encoreos_dev deploys to its production URL (the dev environment), and Supabase Encore OS is updated by a successful Branching deploy run.

​

2.2 Promotion to live production

1. Open a release PR with head = prod and base = production.
2. On open, only the production tier is touched:
   • Vercel encoreos_prod builds a Preview Deployment.
   • Supabase encore_os_prod (srcaoozjkrughebmbvfb) Branching creates a per-PR preview DB.
3. Merge ⇒ Vercel encoreos_prod deploys to the live production URL; Supabase encore_os_prod Branching applies migrations to the live production DB.

Production is a one-way door. Do not direct-commit to production.

​

2.3 Promotion order: Branching preview, GitHub merge, and db push

1. Open the release PR (prod → production) and wait until Supabase Preview (and your usual Vercel preview checks) are green.
2. GitHub branch protection: mark the Supabase GitHub check as a required status on production, so merges are blocked when preview fails.
3. Merge the PR on GitHub. With Deploy to production enabled in the Supabase GitHub integration (see §3.2), Branching applies the same migration chain to the live production database.
4. Deploy Supabase (production) workflow (.github/workflows/supabase-deploy-prod.yml) still runs supabase db push --yes on push to production as a reconcile with the repo. Keep migration files identical to what Branching replays so both paths stay aligned.
5. Break-glass: if migrations were applied only via the Supabase Dashboard (or another one-off path) and db push would be redundant or risky, run the same workflow manually with skip_db_push enabled so Edge Functions and other steps can still run without a second push.

​

3. Supabase dashboard configuration (operator)

​

3.1 Encore OS (zkgxozahyczcnzpwhbbf) — Dev tier

​

3.2 encore_os_prod (srcaoozjkrughebmbvfb) — Production tier

If “Automatic branching = OFF” turns out to be too restrictive (e.g. you want a smoke deploy on every release-candidate PR), set it to ON + “Supabase changes only = ON” so only PRs that touch supabase/** and target production consume a production-tier preview DB.

​

3.3 Verification

# Should list ONE non-default branch row per active PR base (excluding the
# default branch row itself), keyed to the GitHub branch the PR targets.
gh api /repos/Encore-OS/encoreos/pulls -q '.[] | {n: .number, base: .base.ref, head: .head.ref}'

• Encore OS (zkgxozahyczcnzpwhbbf) list_branches should show default_branch_row.git_branch = "prod" and one row per PR targeting prod.
• encore_os_prod (srcaoozjkrughebmbvfb) list_branches should show default_branch_row.git_branch = "production" and one row only when there is an open prod → production release PR.

​

4. Vercel dashboard configuration (operator)

​

4.1 encoreos_dev (prj_iMHAljBMLDQXONzL9g7XUHH6CzrP)

​

4.2 encoreos_prod (prj_NZTWEPkUXJ3jM51uh91Ty8Np9K7c)

​

4.3 Optional: prevent both Vercel projects from previewing the same PR

• In encoreos_dev → Settings → Git → “Ignored Build Step”, keep the in-repo vercel.json ignoreCommand (already set). It will short-circuit identical builds.
• In encoreos_prod → Settings → Git → “Branch Tracking”, set “Only deploy preview branches matching pattern” to prod. That stops it from building previews for arbitrary cursor/* branches.

​

5. Repo-side guardrails

​

6. One-time cleanup actions

1. Close stale duplicate-tier PRs. PR #123 (Gr-ux → production) and PR #124 (Gr-ux → prod) both exist for historical reasons. Once branching is realigned, decide which target is correct:
   • If the change is dev-bound, keep PR #124 (→ prod) and close PR #123.
   • If it is also intended for live production, do not target production directly from a feature branch; merge to prod first, then open a release PR prod → production.
2. Re-run the Supabase Preview check on the surviving PR after §3 is applied. It should now run against only one Supabase project.
3. Optional but recommended: delete or repurpose the legacy GitHub branch named production if the team decides the dev/prod separation should be prod → main or develop → prod instead. Keep this document in sync if you do.

​

7. Failure-mode reference

​

8. References

• supabase/config.toml
• vite.config.ts (SUPABASE_PROJECTS, VERCEL_PROJECT_TO_SUPABASE)
• docs/development/supabase/SUPABASE_MULTI_ENV_SETUP.md
• docs/development/supabase/SUPABASE_RECONCILE_2026-04.md
• docs/development/VERCEL_ENV_REMOVAL_EXECUTION_2026-04-20.md
• Supabase Branching — GitHub Integration
• Supabase Branching — Working with branches
• Vercel for GitHub