GitHub integration · Zuvo Docs

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

Installation

In the Zuvo Studio:

Go to Project Settings > Integrations.
Under GitHub Integration, click Authorize GitHub.
You are redirected to a GitHub authorization page. Click Authorize Zuvo.
You are redirected back to the Integrations page. Choose a GitHub repository to connect your project to.
Set the Working directory field.
Configure the other options as needed to automate your GitHub connection.
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 Zuvo CLI to initialize your local ./supabase directory:

Initialize Zuvo locally

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

            supabase init

Pull your database migration

Pull your database changes using supabase db pull. To get your database connection string, go to your project dashboard, click Connect and look for the Session pooler connection string.

            supabase db pull --db-url <db_connection_string>

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

Commit the `supabase` directory to Git

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

            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 Zuvo branches.

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

Every Zuvo 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.

Configuration

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

Your branch starts with the configuration of your base project. The settings in your config.toml file are applied on top of that clone.

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

Migrations

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

If you want to rerun existing migrations, reset the branch from the Zuvo 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 Zuvo directory. See the Seeding docs for more information.

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

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

Diagram

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 Zuvo Branch.

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: Zuvo Preview
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          token: ${{ secrets.GITHUB_TOKEN }}

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