原文地址 https://www.bytebase.com/docs/tutorials/github-ci/
教程库：https://github.com/bytebase/github-action-example
开发者们喜欢将 Schema 变更脚本与应用程序代码一起保存在 Git 中，这样变更脚本就能像应用程序代码一样接受审核和版本控制，但仍需将变更脚本手动粘贴到 SQL 客户端，或要求 DBA 针对目标数据库运行该脚本。这样做既效率低下，又容易出错：
- 如果错贴 / 漏贴脚本怎么办？
- 如果对错误的数据库运行了脚本怎么办？
本教程教你使用 GitHub Actions 和 Bytebase API 实现数据库 Schema 变更的自动化。
以上是一个典型的工作流：
- 开发者创建包含变更脚本的 PR 后，触发 GitHub 调用 Bytebase SQL Review API。
- TL 批准 PR。
- GitHub 创建 Bytebase 的发布实例，该实例包含迁移脚本的变化。
- 根据所配置的策略，可能需要 DBA 手动批准和发布。GitHub 先阻止 PR 合并，直到 Bytebase 发布 Schema 变更。这种设置可确保 PR 同时包含代码和 Schema 变更时，在代码部署之前应用 Schema 变更。
- Bytebase 部署 Schema 变更，并将问题标记为「完成」。
- PR 重新运行变更状态检查。
- 检查后出现绿色标记，表示 PR 可以合并。
（一）准备 Bytebase
假设 Bytebase 运行于 https://bytebase.example.com/。首先，我们将设置必要的数据，以支持我们的 API 交互。
服务账户： 作为管理员，添加一个具有 Workspace DBA 角色的服务账户 ci@service.bytebase.com，用于验证 API 调用。
为限制服务账户的权限，可以选择授予工作区成员而非工作区 DBA，再在特定项目中，授予该账户创建实例的权限。
项目中的数据库：我们有一个项目 Example 和一个数据库 example。
（二）准备 GitHub 操作
可在 https://github.com/bytebase/ci-example 查看示例。该库包含多个 GitHub Action 工作流，可前往 .github/workflows 查看。
我们将使用以下工作流：
- bytebase-sql-review.yml：在 PR 更改时触发。因此任何违反 SQL 审查的行为都会阻止 PR。
- bytebase-upsert-migration.yml：在 PR 批准时触发。批准后创建 Bytebase 变更实例。只要变更脚本变化，变更实例也会相应更新。
- bytebase-check-migration-status.yml：在 PR 变化时触发。PR 将被阻止，直到变更完成。
（三）工作流样例 - 四个阶段
阶段一：未在 GitHub 上通过 SQL 审核
先在 Bytebase 中设置 SQL 审核策略。在示例数据库所在的 Prod 环境中配置。审核策略中有一个是检查 NOT NULL 约束，而我们将在 PR 中违反该约束。
PR 变更时会触发 bytebase-sql-review.yml 工作流。它会扫描 PR 中以 **.up.sql 模式命名的 SQL 文件，并报告任何违反 SQL 审核策略的情况。
配置环境。
bytebase-sql-review:
runs-on: ubuntu-latest
env:
BYTEBASE_URL: "https://bytebase-ci.zeabur.app"
BYTEBASE_SERVICE_ACCOUNT: "ci@service.bytebase.com"
DATABASE: "instances/prod-instance/databases/example"
...
通过身份验证后，我们会调用 Bytebase API / sql / check 来检查变更文件。我们会解析响应，并为每条建议生成 GitHub 内嵌注释。如果发现任何 ERROR 或 WARNING，则将检查标记为失败。
name: SQL Review
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Login to Bytebase
...
- name: Review
id: review
uses: ./.github/actions/sql-review
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
pattern: "**/*.up.sql"
url: ${{ env.BYTEBASE_URL }}
token: ${{ steps.login.outputs.token }}
headers: '{"Accept-Encoding": "deflate, gzip"}'
database: ${{ env.DATABASE }}
...
我们创建了一个包含多个 SQL 文件的 PR，同时触发了 bytebase-sql-review.yml 和 bytebase-check-migration-status.yml。这些检查完成后，PR 会因故障而被阻止。
单击「详情」查看 SQL 审核。
也可以访问「文件更改」页面来查看注释。
阶段二：通过 SQL 审核，等待 TL 在 GitHub 上批准
修复 SQL 文件并推送。完成这些检查后，PR 仍会因故障而受阻，但这次 SQL 审核已经通过。
实际应用中，PR 还包括应用程序代码。由于 SQL 变更已经通过了基本的 SQL 审核检查，现在就需要技术负责人批准此 PR 了。
创建 PR 的开发者会指派技术负责人在 GitHub 上进行审核。
阶段三：TL 在 GitHub 上批准，在 Bytebase 中创建变更实例
指定的技术负责人批准 PR，并触发另一个工作流 bytebase-upsert-migration.yml。
它会检查 PR 中命名为 **.up.sql 的 SQL 文件，并在 Bytebase 中创建一个发布实例。
bytebase-upsert-migration:
runs-on: ubuntu-latest
# Runs only if PR is approved and target branch is main
if: github.event.review.state == 'approved' && github.event.pull_request.base.ref == 'main'
env:
BYTEBASE_URL: "https://bytebase-ci.zeabur.app"
BYTEBASE_SERVICE_ACCOUNT: "ci@service.bytebase.com"
PROJECT: "example"
DATABASE: "instances/prod-instance/databases/example"
ISSUE_TITLE: "[${{ github.repository }}#${{ github.event.pull_request.number }}] ${{ github.event.pull_request.title }}"
DESCRIPTION: "Triggered by ${{ github.event.repository.html_url }}/pull/${{ github.event.pull_request.number }} ${{ github.event.pull_request.title }}"
name: Upsert Migration
steps:
...
转到 Bytebase 并查看创建的实例，该实例由两个任务组成，与 PR 中存在的两个 **.up.sql 文件相对应。
注意到创建的实例上附有审批流程，这是因为我们为 DDL 设置了默认的自定义审批流程。
阶段四：变更成功，PR 在 GitHub 上合并
在 DBA 批准并启动变更后，实例状态将变为「完成」。
返回 GitHub，点击失败的 bytebase-check-migration-status.yml 工作流的详细信息，然后点击「重新运行所有作业」。
它会检查 Bytebase 中的变更状态，如果是「完成」，则返回「通过」，表示数据库变更已经完成。现在，PR 可以合并了，即应用程序代码可以部署了。
（四）总结
请注意，工作流可以根据企业的需求调整：
- 可以根据分支策略（如是否基于主干）将工作流附加到不同的分支。
- 可以使用不同的变更文件格式和结构。
- 可以决定何时创建变更实例，是在 PR 批准时还是创建时。
无论选择哪种工作流，在 GitHub Actions 和 Bytebase API 的帮助下，你都可以将变更脚本保存在库中，让它们通过相同的代码审查流程，并自动进行 Schema 变更部署。
💡 更多资讯，请关注 Bytebase 公号：Bytebase