GitHub integration

Supabase Branching uses the Supabase GitHub integration to read files from your GitHub repository. With this integration, Supabase watches all commits, branches, and pull requests of your GitHub repository.

Installation#

In the Supabase Dashboard:

1. Go to Project Settings > Integrations.
2. Under GitHub Integration, click Authorize GitHub.
3. You are redirected to a GitHub authorization page. Click Authorize Supabase.
4. You are redirected back to the Integrations page. Choose a GitHub repository to connect your project to.
5. Set the Working directory field.
6. Configure the other options as needed to automate your GitHub connection.
7. Click Enable integration.

Set the working directory#

The working directory is the path from your repository root to the directory that contains the supabase/ folder. Enter . when supabase/ is at the repository root.

If supabase/ is nested deeper in your repository, enter its parent directory instead. For example, if your layout is apps/web/supabase/, enter apps/web.

Preparing your Git repository#

You will be using the Supabase CLI to initialize your local ./supabase directory:

1
supabase init

1
supabase db pull --db-url <db_connection_string>
2
3
# Your Database connection string will look like this:
4
# postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:5432/postgres

1
git add supabase
2
git commit -m "Initial migration"
3
git push

Syncing GitHub branches#

Enable the Automatic branching option in your GitHub Integration configuration to automatically sync GitHub branches with Supabase branches.

When a new branch is created in GitHub, a corresponding branch is created in Supabase. (You can enable the Supabase changes only option to only create Supabase branches when Supabase files change.)

Every Supabase branch, preview or persistent, is created as a clone of your base project. The new branch starts with the Edge Functions and configuration of that project. Its database schema is not cloned. Instead, it is built from the migrations you commit to your repository. For the full list of what a branch inherits, see What a new branch starts with.

What runs on each push#

After Supabase creates the branch and copies your base project's settings, it runs the branching workflow against the files in your repository. The workflow applies your config.toml first, then runs any migrations the branch hasn't applied yet. After that it seeds the database and Storage buckets, and finally deploys your Edge Functions. On a persistent branch, including your production branch, the config.toml and seed steps apply only when a [remotes] block names that branch, as described in Configuration. The same workflow runs again on every push to the git branch. You don't need a GitHub Action to deploy migrations or sync config.toml to a branch.

For what each step does, see Deploying to production. To check a step's status and read its logs, see Monitoring deployments.

Configuration#

You can test configuration changes on your Preview Branch by configuring the config.toml file in your Supabase directory. See the Configuration docs for more information.

Supabase applies the settings in your config.toml on top of the configuration copied from your base project, and where the two differ, your repository wins.

The configure step compares the [db], [api], [auth], [storage], and [experimental] sections of config.toml with the branch's current settings and updates the ones that differ. The migrate, seed, and deploy steps read the other sections, such as [functions] and [db.seed]. If your repository has no config.toml, the step only turns on Database Webhooks.

On a persistent branch, including your production branch, the step runs only when a [remotes] block names that branch's project ID. For the [remotes] syntax, see Remote-specific configuration.

A comment is added to your PR with the deployment status of your preview branch.

Migrations#

The migrations in the migrations subdirectory of your Supabase directory are automatically run when the branch is created. Each later commit runs only the migrations that haven't been applied yet.

The migrate step compares the files in supabase/migrations with the branch's migration history and applies every file without a history entry. Before it runs them, it saves the Vault secrets declared under [db.vault] to the branch. Keep two cases in mind:

• A migration file with a timestamp older than the latest applied migration still runs and the step finishes with a warning.
• A version in the branch's migration history with no matching file fails the step.

To stop branching from running migrations, set enabled = false under [db.migrations] in config.toml.

If your project uses declarative schemas, the files in supabase/schemas/ are not applied by branching. Run supabase db schema declarative sync to generate a migration from your schema changes, and commit the generated migration alongside your schema files.

Branching runs each migration file inside a single transaction and does not honor the -- pg-delta: transaction=false directive. A migration that can't run in a transaction (for example, one that uses create index concurrently, or a pg-delta file that carries the directive) applies with supabase db push but fails when branching deploys it.

If you want to rerun existing migrations, reset the branch from the Supabase Dashboard to start from scratch. Note that existing data on your branch will also be dropped by a reset.

Seeding#

Cloning your base project copies its Edge Functions and configuration, but not its data or storage objects. This is meant to protect your sensitive production data. Your branch starts with the tables your migrations create, and the only rows in them are the ones your seed files add.

You can seed your Preview Branch with sample data using the seed.sql file in your Supabase directory. See the Seeding docs for more information.

Data changes in your seed files are not merged to production.

Edge Functions#

Edge Functions reach your branch in the deploy step, the last step of the workflow. The step saves the function secrets declared under [edge_runtime.secrets] then deploys functions:

• If your repository has a supabase/functions directory, the step deploys the functions declared in config.toml under [functions.<slug>]. If the directory has functions but config.toml declares none, the step deploys nothing and finishes with a warning.
• If your repository has no functions directory, the step copies the functions deployed on your base project. config.toml can still disable a copied function or change its JWT verification.

A function is uploaded again only when it changed. For each function, the step compares the checksum of the new bundle and the JWT verification setting against the version already deployed on the branch. If both are the same, the step skips that function.

Deploying changes to production#

Enable the Deploy to production option in your GitHub Integration configuration to automatically deploy changes when you push or merge to production branch.

The following changes are deployed:

• New migrations are applied
• Edge Functions declared in config.toml are deployed
• Storage buckets declared in config.toml are deployed

All other configurations, including API, Auth, and seed files, are ignored by default.

Preventing migration failures#

We highly recommend turning on a 'required check' for the Supabase integration. You can do this from your GitHub repository settings. This prevents PRs from being merged when migration checks fail, and stops invalid migrations from being merged into your production branch.

Email notifications#

To catch failures early, we also recommend subscribing to email notifications on your branch. Common errors include migration conflict, function deployment failure, or invalid configuration file.

You can setup a custom GitHub Action to monitor the status of any Supabase Branch.

1
name: Branch Status
2
3
on:
4
  pull_request:
5
    types:
6
      - opened
7
      - reopened
8
      - synchronize
9
    branches:
10
      - main
11
      - develop
12
    paths:
13
      - 'supabase/**'
14
15
jobs:
16
  failed:
17
    runs-on: ubuntu-latest
18
    steps:
19
      - uses: fountainhead/action-wait-for-check@v1.2.0
20
        id: check
21
        with:
22
          checkName: Supabase Preview
23
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
24
          token: ${{ secrets.GITHUB_TOKEN }}
25
26
      - if: ${{ steps.check.outputs.conclusion == 'failure' }}
27
        run: exit 1