How to Use SupaForge with Supabase Branching

What Is Supabase Branching?

Supabase Branching creates isolated database environments for each Git branch. Each branch gets its own Postgres instance with a copy of the production schema, allowing developers to experiment without risk.

The challenge: branch environments diverge from production the moment they're created. Dashboard changes, RLS policy tweaks, and auth setting updates in a branch are invisible to the rest of the team until the branch is merged.

How SupaForge Helps

SupaForge compares a branch environment against production (or any other environment) and surfaces every difference — not just schema, but RLS, auth, storage, cron, and more.

Use cases:

• Pre-merge validation — ensure a branch has no unintended drift before merging.
• Branch review — show the team exactly what changed in a branch, including Dashboard changes that aren't in the migration files.
• Stale branch detection — find branches that have diverged significantly from production.

Step 1 — Point at the Branch Environment

Each Supabase branch has its own connection string. Use it as the source, and your production (or staging) connection as the target:

{
  "environments": {
    "branch": {
      "dbUrl": "postgresql://user:pass@db.BRANCH_REF.supabase.co:5432/postgres",
      "projectRef": "BRANCH_REF",
      "apiKey": "your-branch-service-role-key"
    },
    "production": {
      "dbUrl": "postgresql://user:pass@db.PRODUCTION_REF.supabase.co:5432/postgres",
      "projectRef": "PRODUCTION_REF",
      "apiKey": "your-production-service-role-key"
    }
  },
  "source": "branch",
  "target": "production"
}

Step 2 — Scan the Branch

supaforge scan

Or narrow to a specific check:

supaforge scan --check rls

Step 3 — Review and Decide

The scan output tells you exactly what was changed in the branch. For each drift issue, decide:

• Intentional? — If the change should be promoted to production, include it in your migration plan.
• Accidental? — If the change was a mistake (e.g. a leftover test policy), fix it in the branch before merging.
• Irrelevant? — Some differences are expected between environments (e.g. different OAuth redirect URIs). Note them and move on.

CI Integration for Branch Checks

Run a SupaForge scan in your PR pipeline to automatically validate branch environments:

- name: Check branch drift
  env:
    SUPAFORGE_SOURCE: ${{ secrets.BRANCH_DB_URL }}
    SUPAFORGE_TARGET: ${{ secrets.PRODUCTION_DB_URL }}
  run: |
    npm i -g @akalforge/supaforge
    supaforge scan

The scan will fail the pipeline if unexpected drift is detected, giving reviewers a clear signal to investigate.

Summary

Supabase Branching gives each developer an isolated environment. SupaForge makes those environments comparable — so you know exactly what changed, what's intentional, and what needs to be fixed before merging.