How to Use SupaForge with Supabase Branching

What Is Supabase Branching?

Supabase Branching gives each Git branch its own Supabase environment, so changes can be tried without touching production.

A branch drifts from production the moment people start using it: a policy tweaked in the dashboard, a bucket added, an auth setting changed. Those changes aren't in the branch's migration files, so nobody reviewing the pull request sees them.

How SupaForge Helps

SupaForge compares the branch with production - or any other environment - across the whole project, not just the schema:

• Pre-merge review - see exactly what the branch changes, dashboard edits included.
• Catching leftovers - a test policy or a public bucket that shouldn't ship.
• Long-lived branches - find out how far a branch has drifted before merging it.

Step 1 - Point at the Branch

Each branch has its own project ref and connection string. Make the branch the source and production the target:

{
  "environments": {
    "branch": {
      "dbUrl": "$BRANCH_DATABASE_URL",
      "projectRef": "BRANCH_REF",
      "accessToken": "$SUPABASE_ACCESS_TOKEN"
    },
    "production": {
      "dbUrl": "$PRODUCTION_DATABASE_URL",
      "projectRef": "PRODUCTION_REF",
      "accessToken": "$SUPABASE_ACCESS_TOKEN"
    }
  },
  "source": "branch",
  "target": "production"
}

Step 2 - Compare

supaforge diff

supaforge diff --check=rls

Step 3 - Review and Decide

• Intended? Make sure it's in the branch's migrations, or that it will be applied when the branch merges.
• Accidental? Fix it in the branch before merging.
• Expected to differ? Some settings, like each environment's site URL, differ by design. Note them, or leave the check out with --skip.

In the Pull Request

- name: Diff the branch against production
  env:
    BRANCH_DATABASE_URL: ${{ secrets.BRANCH_DATABASE_URL }}
    PRODUCTION_DATABASE_URL: ${{ secrets.PRODUCTION_DATABASE_URL }}
    SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
  run: npx @akal/supaforge diff --ci

Findings appear as annotations on the pull request, and the step fails when the branch differs from production in a way you haven't accounted for.

Install

npm install -g @akal/supaforge

Summary

Branching gives every change its own environment. SupaForge shows what each one actually changes - so you know what's intended, what's left over, and what needs fixing before the merge.