> ## 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.

# Supabase Branching + CI integration (spike notes)

> Version: 1.0.1 Last Updated: 2026-04-24 Status: Reference for deferred automation (PR diff comments, Branching-first promotion).

**Version:** 1.0.1\
**Last Updated:** 2026-04-24\
**Status:** Reference for deferred automation (PR diff comments, Branching-first promotion).

## Goal

Pick **one** supported integration path to:

1. Resolve the **preview branch** (or migration apply status) for a `prod → production` PR on project **`srcaoozjkrughebmbvfb`**.
2. Surface “what will run in prod” in GitHub (check run body, PR comment, or artifact) without leaking secrets.

## Option A — Supabase CLI in GitHub Actions (current baseline)

**Auth:** `SUPABASE_ACCESS_TOKEN` + `supabase link --project-ref … --password …` (already used in deploy workflows).

**Useful commands (verify flags with `npx supabase <cmd> --help` on the pinned CLI version):**

* `supabase migration list --linked` — local vs remote migration filenames (post-link in [`scripts/supabase/deploy-preflight.ts`](../../../scripts/supabase/deploy-preflight.ts)).
* `supabase db diff --linked` — requires Docker on the runner; compares linked remote to local migration state (used for dev drift gate).
* Branch-specific subcommands evolve by CLI version; re-check [Supabase CLI reference](https://supabase.com/docs/reference/cli/introduction) before building “link to preview DB” automation.

**Limits:** CI may not get a stable **per-PR preview connection string** without Dashboard or Management API support; linking always targets the **primary** linked project, not ephemeral preview DBs.

## Option B — Supabase Management API

* **Branches:** [Supabase API docs](https://supabase.com/docs/reference/api) (branch list, merge status — endpoints and auth scopes change with product releases).
* **Typical need:** personal access token / org token with permission to read branch metadata for project `srcaoozjkrughebmbvfb`.

**Limits:** Rate limits; token storage in GitHub secrets; response shape must be pinned or schema-checked in CI.

## Option C — GitHub Check + Dashboard (lowest automation)

* Rely on the **Supabase Preview** GitHub check from the GitHub integration (see [`VERCEL_SUPABASE_ENV_ALIGNMENT.md`](../VERCEL_SUPABASE_ENV_ALIGNMENT.md) §2.2–§3.2).
* PR automation only posts **links** to Dashboard branches + migration list from **git diff** (see [`scripts/supabase/release-pr-db-summary.ts`](../../../scripts/supabase/release-pr-db-summary.ts)).

**Limits:** No embedded live SQL diff from the preview DB without Option A/B.

## Recommendation (until spike is re-run on current product)

1. **Require** Supabase Preview check on `production` PRs (branch protection).
2. Use **git-based** summaries + Dashboard links in CI ([`supabase-promote-pr.yml`](../../../.github/workflows/supabase-promote-pr.yml)).
3. Re-spike **Option B** when implementing “real Branching diff” comments; keep `db push` reconcile documented as break-glass in deploy workflow inputs.

## Related

* [MIGRATION\_LANES.md](./MIGRATION_LANES.md) — lane inventory + retrofit.
* [SUPABASE\_MULTI\_ENV\_SETUP.md](./SUPABASE_MULTI_ENV_SETUP.md) — workflow map.