# GitHub integration

Connect with GitHub to sync branches with your repository

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**](/dashboard/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](/docs/guides/local-development) to initialize your local `./supabase` directory:

1. **Initialize Supabase locally**

If you don't have a `./supabase` directory, you can create one:

```markdown
supabase init
```

2. **Pull your database migration**

Pull your database changes using `supabase db pull`. To get your database connection string, open the Supabase Dashboard, click [Connect](/dashboard/project/_?showConnect=true\&method=session) and look for the Session pooler connection string.

```markdown
supabase db pull --db-url <db_connection_string>

# Your Database connection string will look like this:
# postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:5432/postgres
```

Note: If you're in an [IPv6 environment](https://github.com/orgs/supabase/discussions/27034) or have the IPv4 Add-On, you can use the direct connection string instead of Supavisor in Session mode.

3. **Commit the `supabase` directory to Git**

Commit the `supabase` directory to Git, and push your changes to your remote repository.

```bash
git add supabase
git commit -m "Initial migration"
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](/docs/guides/deployment/branching#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](#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](/docs/guides/deployment/branching#deploying-to-production). To check a step's status and read its logs, see [Monitoring deployments](/docs/guides/deployment/branching/troubleshooting#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](/docs/guides/deployment/branching/configuration) 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](/docs/guides/deployment/branching/configuration#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](/docs/guides/local-development/declarative-database-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`](/docs/guides/local-development/diff-engines) 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](/docs/guides/local-development/seeding-your-database) 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.

![Check the "Require status checks to pass before merging" option.](/docs/img/guides/platform/branching/github-required-check.jpg?v=1)

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

```yaml name=.github/workflows/notify-failure.yaml
name: Branch Status

on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
    branches:
      - main
      - develop
    paths:
      - 'supabase/**'

jobs:
  failed:
    runs-on: ubuntu-latest
    steps:
      - uses: fountainhead/action-wait-for-check@v1.2.0
        id: check
        with:
          checkName: Supabase Preview
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          token: ${{ secrets.GITHUB_TOKEN }}

      - if: ${{ steps.check.outputs.conclusion == 'failure' }}
        run: exit 1
```