GitHub 集成

Supabase 分支使用 Supabase 的 GitHub 集成来读取你 GitHub 仓库中的文件。通过这个集成，Supabase 会监控你 GitHub 仓库的所有提交、分支和拉取请求。

🌐 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

在 Supabase 控制台中：

🌐 In the Supabase Dashboard:

1. 前往 项目设置 > 集成。
2. 在 GitHub 集成 下，点击 授权 GitHub。
3. 你会被重定向到 GitHub 授权页面。点击 授权 Supabase。
4. 你会被重定向回集成页面。选择一个 GitHub 仓库来连接你的项目。
5. 设置 工作目录 字段。
6. 根据需要配置其他选项，以自动化你的 GitHub 连接。
7. 点击 启用集成。

设置工作目录 #

🌐 Set the working directory

工作目录是从你的仓库根目录到包含 supabase/ 文件夹的目录的路径。当 supabase/ 位于仓库根目录时，输入 .。

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

如果 supabase/ 在你的仓库里更深层次的目录中，输入它的上级目录就行。比如说，如果你的布局是 apps/web/supabase/，就输入 apps/web。

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

准备你的 Git 仓库 #

🌐 Preparing your Git repository

你将使用 Supabase CLI 来初始化你本地的 ./supabase 目录：

🌐 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

同步 GitHub 分支 #

🌐 Syncing GitHub branches

在你的 GitHub 集成配置中启用 自动分支 选项，以便自动将 GitHub 分支与 Supabase 分支同步。

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

当在 GitHub 创建新分支时，Supabase 会创建对应的分支。（你可以启用 仅限 Supabase 更改 选项，这样只有在 Supabase 文件更改时才会创建 Supabase 分支。）

🌐 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.)

每个 Supabase 分支，无论是预览分支还是持久分支，都是作为你基础项目的克隆创建的。新分支会从那个项目继承 Edge 函数和配置。它的数据库模式不会被克隆，而是根据你提交到仓库的迁移来构建。

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

配置 #

🌐 Configuration

你可以通过在 Supabase 目录中配置 config.toml 文件，在你的预览分支上测试配置更改。更多信息请参见 配置文档。

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

你的分支从基础项目的配置开始。config.toml 文件中的设置会在那个克隆的基础上应用。

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

你的 PR 上会添加一条评论，显示你的预览分支的部署状态。

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

迁移 #

🌐 Migrations

在你的 Supabase 目录的 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.

如果你的项目使用声明式模式，supabase/schemas/中的文件不会通过分支应用。运行supabase db schema declarative sync根据你的模式更改生成迁移，并将生成的迁移与模式文件一起提交。

🌐 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 会在单个事务中运行每个迁移文件，并且不遵守 -- pg-delta: transaction=false 指令。不能在事务中运行的迁移（例如，使用 create index concurrently 的迁移，或者带有该指令的 pg-delta 文件）会在 supabase db push 下应用，但在 branching 部署时会失败。

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

如果你想重新运行已有的迁移，可以从 Supabase 控制台重置分支，从头开始。注意，重置分支也会删除你分支上的现有数据。

🌐 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

克隆你的基础项目会复制它的 Edge 函数和配置，但不会复制它的数据或存储对象。这是为了保护你敏感的生产数据。你的分支会从迁移创建的表开始，表里唯一的数据就是你的 seed 文件添加的那部分。

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

你可以使用 Supabase 目录中的 seed.sql 文件为你的预览分支填充示例数据。更多信息请查看 Seeding 文档。

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

将更改部署到生产环境 #

🌐 Deploying changes to production

在你的 GitHub 集成配置中启用 部署到生产环境 选项，这样当你推送或合并到生产分支时，变更会自动部署。

🌐 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:

• 新的迁移已应用
• 在 config.toml 中声明的边缘函数已部署
• config.toml 中声明的存储桶已部署

所有其他配置，包括 API、认证和种子文件，默认都会被忽略。

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

防止迁移失败 #

🌐 Preventing migration failures

我们强烈建议为 Supabase 集成开启“必需检查”。你可以在 GitHub 仓库的设置中进行操作。这可以防止在迁移检查失败时合并 PR，并阻止无效的迁移被合并到你的生产分支。

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

你可以设置一个自定义的 GitHub Action 来监控任何 Supabase 分支的状态。

🌐 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