Skip to content
Home

Branching

Use Supabase Branches to test and preview changes

You can deploy directly from GitHub on any plan — connect your repository and changes pushed to main are automatically deployed to your project. Branching takes this further, adding isolated preview environments for each pull request.

Use branching to safely experiment with changes to your Supabase project.

Supabase branches create separate environments that spin off from your base project. You can use these branching environments to create and test changes like new configurations, database schemas, or features without affecting your production setup. When you're ready to ship your changes, merge your branch to update your production instance with the new changes.

How branching works#

  • Separate Environments: Each branch is a separate environment with its own Supabase instance and API credentials.
  • Preview Branches: Preview branches are ephemeral and best suited for focused testing. They are automatically deleted when a PR is merged or closed.
  • Persistent Branches: Persistent branches are long-lived and recommended for environments like staging, QA, or development. They aren't automatically paused or deleted due to inactivity or when a PR is merged or closed.
  • Managing Branches: You can create, review, and merge branches either automatically via our GitHub integration or directly through the Supabase Dashboard (currently in beta). All branches show up in the branches page in the dashboard, regardless of how they were created.
  • Cloned from your base project: Each new branch is created as a clone of your base project. It starts with that project's Edge Functions deployed and the configuration set.
  • Data-less by default: By default, new branches do not start with any data or storage objects from your base project. This is meant to better protect your sensitive production data. To start your branches with data, you can use a seed file if using the GitHub integration, or the Include data option if you create the branch from the Supabase Dashboard.

What a new branch starts with#

Whether you create a branch from a pull request or from the Supabase Dashboard, Supabase creates a project with default settings then copies these settings from your base project:

  • Postgres settings
  • Connection pooler settings
  • Auth, Data API, Realtime, and Storage settings
  • SSL enforcement
  • Network restrictions, when your base project has them
  • Deployed Edge Functions

Auth secrets, such as OAuth provider secrets and SMTP passwords, get placeholder values instead. Set the real values with branch secrets. Supabase also turns on Database Webhooks for every branch.

The database schema isn't cloned. A GitHub-connected branch builds it from the migrations in your repository. A dashboard branch builds it from your base project's migration history. The branch is ready when the settings, the schema, and the Edge Functions are all in place.

Deploying to production#

When you merge any branch into your base project, Supabase automatically runs a deployment workflow to deploy your changes to production. The deployment workflow is expressed as a Directed Acyclic Graph where each node represents one of the following deployment steps.

  1. Clone - Checks out your repository at the specified git branch (optional for Branching via Dashboard)
  2. Pull - Retrieves database migrations from your base project (also initialises the migration history table when Branching via Dashboard)
  3. Health - Waits up to 2 minutes for all Supabase services on your branch to be running and healthy, including Auth, API, Database, Storage, and Realtime
  4. Configure - Updates service configurations based on your config.toml file (only available for Branching via GitHub)
  5. Migrate - Applies pending database migrations and vault secrets to your branch
  6. Seed - Runs seed files to populate your branch with initial data (must be enabled in config.toml for persistent branches)
  7. Deploy - Deploys any changed Edge Functions and updates function secrets

If a parent deployment step fails, all dependent child steps are skipped. For instance, if your database migrations fail at step 5, our runner doesn't seed your branch because step 6 is skipped. If you are using GitHub integration, the same deployment workflow runs on every commit pushed to your git branch. To check each step's status in the Supabase Dashboard, see Monitoring deployments.