Atlas 数据库 CI 接入指南:PR 自动 lint/plan,合并即推送 Atlas Registry(Stage 3)
Atlas 数据库 CI 接入指南:PR 自动 lint/plan,合并即推送 Atlas Registry(Stage 3)
本篇指南对应 Atlas 托管式数据库接入流程(
atlas-onboardskill)的第三阶段(Stage 3:CI),其完整目录结构可在仓库 skills/atlas-onboard/ 中查看。读完本文,你将掌握如何为已进入 Schema-as-Code 流程的单元(unit)搭建数据库 CI:让每一个触碰该单元的 Pull Request 自动获得 Atlas 的 lint 报告(版本化工作流)或迁移计划(声明式工作流),并在每次合并到默认分支时把迁移目录或 schema 以不可变版本的形式推送到 Atlas Registry,为第四阶段的部署与漂移检测打好基础。文章以 stage-3-ci.md 为核心骨架,辅以仓库内的 cicd.md、versioned.md、lint.md 等参考资料与 CLI 源码展开。
一、阶段目标与适用前提
本阶段的目标一句话概括:每个触碰单元的 PR 获得 Atlas 的 lint 报告(版本化单元)或迁移计划(声明式单元),每次合并到默认分支后向 Atlas Registry 推送一个新版本。本阶段不部署任何环境——部署是 Stage 4 的事情。
开始前需要满足两个前提:
- Stage 2 的项目 PR 已合并:
atlas.hcl、期望状态(schema 或 ORM 模型)以及版本化单元的migrations/atlas.sum已经进入默认分支(对应 stage-2-workflow.md 与 SKILL.md 中 "Finished when" 的判定条件); - 工作流与 CI 系统已经确定:单元走 versioned 还是 declarative、仓库用哪个 CI 平台,都由 Stage 0 的扫描与决策记录在
.atlas-onboarding.json中(见 stage-0-plan.md 的 0.4/0.5 小节)。
本阶段要做三件事:决定添加哪些 workflow、处理手动步骤(创建并存放凭据)、检查最终结果。每个 CI 平台都有对应的分步指南;选择与你所在平台匹配的那一份即可。仓库内 cicd.md 汇总了 GitHub Actions 的完整流水线,以及其他平台的集成方式。
Atlas 支持以下 CI 平台,版本化与声明式工作流各有对应指南:
| CI 系统 | 版本化工作流 | 声明式工作流 |
|---|---|---|
| GitHub Actions | 官方 guides 的 github-versioned 页 | 官方 guides 的 github-declarative 页 |
| GitLab CI | 官方 guides 的 gitlab-versioned 页 | 官方 guides 的 gitlab-declarative 页 |
| Bitbucket Pipelines | 官方 guides 的 bitbucket-versioned 页 | 官方 guides 的 bitbucket-declarative 页 |
| CircleCI | 官方 guides 的 circleci-versioned 页 | 官方 guides 的 circleci-declarative 页 |
| Azure DevOps,代码在 GitHub | 官方指南的 Versioned Migrations Workflow | 官方指南的 Declarative Workflow |
| Azure DevOps,代码在 Azure Repos | 官方指南的 Versioned Migrations Workflow | 官方指南的 Declarative Workflow |
(所有 CI 指南的完整列表见官方 guides 页面;仓库侧的全平台集成对照表见 cicd.md 的 "Other CI Platforms" 小节,其中还包括 Kubernetes Operator、Terraform Provider、ArgoCD/Flux 与 Go SDK atlasexec。)
二、3.1 决策:选择 CI 系统与可选 Job
CI 系统:直接采用 Stage 0 扫描得出的平台,并按上表找到对应指南。如果仓库使用的是表外系统(例如 Jenkins 或 TeamCity),通用做法是:在流水线中安装 Atlas CLI(curl -sSf https://atlasgo.sh | sh,macOS/Linux,其他方式见 README.md),然后执行 atlas login --token "$ATLAS_TOKEN",之后运行与表内平台完全相同的命令,统一带上 --env ci 参数。
可选 Job(试点阶段默认关闭),只有当你观察到多名开发者开始同时修改 schema 时才考虑开启:
- 自动生成迁移(automatic migration generation):开发者改了 schema 源文件却忘了生成迁移文件时,CI 中的
migrate/diff步骤会代为生成并提交到 PR 分支;对 ORM 单元,该 job 还会在模型与迁移目录不一致时让 PR 失败。 - 自动 rebase
atlas.sum冲突(automatic rebase):迁移历史是线性的,两个分支同时新增迁移文件,后合并的一方必然在atlas.sum上冲突。migrate/autorebase会把这些文件移动到目标分支文件之后并重新计算atlas.sum。
哪些平台提供这两个 job、以及它们需要哪种额外 token(使它们的提交能触发 lint),参见 cicd.md 的 "Automatic migration generation (migrate/diff)" 与 "Migration conflicts (migrate/autorebase)" 两节。
源码佐证——lint 如何决定"哪些文件是新的":CLI 的 migrate lint 子命令(定义于 cmd/atlas/internal/cmdapi/migrate.go)提供 --git-base(与基线分支比较)和 --base(示例值为 atlas://myapp,与 Atlas Registry 中已推送的状态比较)两类基准。仓库 lint.md 明确了使用规则:配置了 registry repo 之后,lint 默认只分析"尚未推送到 registry 的新迁移文件",此时不要再添加 git { base } 或 --git-base——registry 比较正是让 lint 独立于分支历史、并被 Stage 4 漂移检测所依赖的机制。
三、3.2 凭据(手动步骤)
CI 使用**机器人 token(bot token)**进行身份认证,它不绑定到任何个人账号。创建权限与注意事项:
- 只有组织管理员能创建,且只能在 Atlas Cloud UI 中进行:☰ > Settings > Bots > Create Bot;
- 必须在
atlas.hcl的atlas块所 pin 的那个组织里创建。来自其他组织的 token 会让每一个读取该文件的命令失败; - token 只显示一次,创建后立即失去再次查看的机会;
- 请让用户自己创建并存放为 CI secret,token 绝不经过对话传递(对应 SKILL.md 的权限规则:"Creating Atlas Cloud repos、bot tokens、CI secrets → Ask first")。
各 CI 平台的 secret 存放位置与命名:
| CI | 存放位置 | Secret 名称 |
|---|---|---|
| GitHub Actions | Settings > Secrets and variables > Actions,或在自己的终端执行 gh secret set ATLAS_CLOUD_TOKEN |
ATLAS_CLOUD_TOKEN |
| GitLab CI | Settings > CI/CD > Variables,勾选 masked,并取消勾选 Protect variable(否则 Merge Request 流水线读不到) | ATLAS_CLOUD_TOKEN |
| CircleCI | Organization Settings > Contexts | ATLAS_TOKEN |
| Bitbucket | Repository settings > Repository variables,勾选 secured | ATLAS_TOKEN |
| Azure DevOps | Pipelines > Library 的 variable group,标记为 secret | ATLAS_TOKEN |
两点补充:
- 复用已有 secret:如果仓库已经存在其他名字的 Atlas token secret,直接复用并把该名字写进 workflow 即可。CLI 本身也读取环境变量
ATLAS_TOKEN。 - protected flows:当 registry repo 启用了受保护流程时,bot 还需要该 repo 上的 Writer 角色(官方 roles-and-permissions 文档有说明)。
此外,Atlas 会把 lint 报告(或声明式工作流的 plan)作为评论发布到 PR 上,各 CI 平台为此需要额外的评论凭据:
| CI | 评论凭据 |
|---|---|
| GitHub Actions | 无需创建:workflow 设置 GITHUB_TOKEN: ${{ github.token }} 与 permissions: pull-requests: write(两种写法都已包含在 cicd.md 的模板中) |
| GitLab CI | GITLAB_TOKEN:一个项目访问令牌,具备 Reporter 角色与 api 权限范围,存为 CI/CD variable |
| Bitbucket | BITBUCKET_ACCESS_TOKEN:一个 app password,具备 pullrequest:write 权限,存为 secured variable |
| CircleCI | GITHUB_TOKEN:一个具备 repo 权限范围的 GitHub 个人访问令牌,以及 GITHUB_REPOSITORY(owner/repo),放在 context 中 |
| Azure DevOps(代码在 GitHub) | 一个 GitHub service connection,使用 OAuth 或个人访问令牌 |
| Azure DevOps(代码在 Azure Repos) | Build Service 账号被允许对仓库执行 Contribute 与 Contribute to pull requests |
四、3.3 首次推送:创建 Registry 仓库(先征求同意)
为什么要先推一次? 第一次推送会创建该单元的 registry repo,让 CI PR 上的 lint 有一个已推送的版本可以与之比较(否则 lint 退化为 git-base 比较,依赖分支历史)。步骤:
先从最新的默认分支推送,并确认 repo 名字没有被占用:
git switch <default> && git pull --ff-only
atlas cloud repo describe --slug <repo>
- 如果
describe显示 repo 已存在且不是本单元的,与用户商定另一个 slug,并将其记录为单元的repo字段(写入.atlas-onboarding.json); - 然后向用户确认:"Create registry repo
<repo>in<org>with this push?",得到同意后执行:
atlas migrate push --env local <repo> # 版本化单元
atlas schema push --env local <repo> # 声明式单元
ORM 单元的特殊处理:--env local 会运行 ORM loader 加载模型;如果当前 shell 里没有安装 loader 的依赖,改用显式参数:--dir file://migrations --dev-url "<dev URL>",跳过 --env local。
全程 CI 化创建:如果团队希望所有 Atlas Cloud 变更都发生在 CI 中,可以用 create-repo action 在一次性手动运行的 workflow 中创建仓库(模板见 cicd.md 的 "The registry repo must exist before the first CI run" 小节)。该 repo 初始为空,第一个版本随第一次合并到达。
源码与文档佐证——Registry 的不可变版本语义:仓库 versioned.md 的 "Registry" 小节说明:
atlas migrate push --env <name> app # 推送目录;不带 tag 时更新 latest
atlas migrate push --env <name> app:v1.2.0 # 显式 tag
atlas migrate apply --url "$URL" --dir "atlas://app?tag=v1.2.0"
atlas migrate apply --url "$URL" --dir "atlas://app?version=20260301120000"
推送使迁移目录成为一个不可变、带版本号的产物,CD 无需源码即可部署它;它同时是 migrate lint 默认的比对基准与漂移检测的数据来源。在 CLI 源码中,schema push 会把 env 的 schema 源(src)映射为 --url 参数(见 cmd/atlas/internal/cmdapi/schema.go),实现"推送的是期望状态本身"。
五、3.4 工作流:一个 PR 完成全部接入
按 SKILL.md 的 Rule 4,先基于最新默认分支创建分支 atlas-onboard/<unit>-3,然后依次完成以下步骤。
步骤 1:为单元添加 env "ci"
该 env 不需要数据库 URL:lint 与 plan 都在 dev 数据库上运行,并与 Atlas Registry 中的状态比较(对应 cicd.md 的 Case 1——绝大多数项目的形态):
env "ci" { # 版本化单元
dev = local.dev
exclude = local.exclude
migration {
dir = "file://migrations"
repo {
name = "<repo>"
}
}
}
env "ci" { # 声明式单元
dev = local.dev
exclude = local.exclude
schema {
src = local.src
repo {
name = "<repo>"
}
}
}
- 管理角色与权限(roles/permissions)的单元,从 Stage 2 复制
mode块与 dev 数据库配置到本 env(详见 stage-2-workflow.md 的 "Roles and Permissions" 小节,以及 stage-1-schema.md 的atlas.hcl写法)。 dev即 dev 数据库:一个临时的、隔离的沙箱数据库,用于在真实的同版本引擎上重放迁移/加载期望状态(stage-1-schema.md 1.1 小节有完整的docker://URL 对照表)。
步骤 2:添加 PR 流水线与合并流水线
从第三节的对照表中选择平台的指南,secret 命名遵循 3.2。GitHub Actions 上直接使用 cicd.md 提供的同名流水线:Versioned Pipeline(atlas-ci.yaml) 或 Declarative Pipeline(atlas-plan.yaml)。两个流水线的阶段划分:
| 阶段 | 触发时机 | 运行内容 | GitHub Action |
|---|---|---|---|
| Lint | pull request | 在 dev 数据库上重放"尚未进入 registry 的文件",把发现评论到 PR,出错即失败 | ariga/atlas-action/migrate/lint@v1 |
| Test(可选) | pull request | migrate test / schema test,结果上 PR |
ariga/atlas-action/migrate/test@v1、schema/test@v1 |
| Push | 合并到默认分支 | 把目录推送到 registry,打上 commit 与 latest 标签 |
ariga/atlas-action/migrate/push@v1 |
(声明式流水线为 Plan → Approve → Push:plan 在 PR 上把"从 registry 最后状态到 schema.src 的转变"计划出来并以 PENDING 状态存储,合并时 approve 批准该计划、push 记录新的期望状态。)
关键约束:移除所有 apply 步骤。例如声明式流水线中的 schema/apply 步骤、版本化流水线中被注释掉的 migrate/apply——Stage 4 才会引入部署。下面的 YAML 是版本化流水线的骨架(节选自 cicd.md,去掉了 apply):
# .github/workflows/atlas-ci.yaml
name: Atlas CI
on:
push:
branches: [master]
pull_request:
paths: ['migrations/*', 'schema.sql', 'atlas.hcl']
permissions:
contents: read
pull-requests: write
jobs:
lint:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # 仅在无 registry(用 --git-base)时需要
- uses: ariga/setup-atlas@v0
with:
cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
- uses: ariga/atlas-action/migrate/lint@v1
with:
env: ci
env:
GITHUB_TOKEN: ${{ github.token }} # 让 action 能把报告评论到 PR
push:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ariga/setup-atlas@v0
with:
cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
- uses: ariga/atlas-action/migrate/push@v1
with:
env: ci
dir-name: app
步骤 3:ORM 单元——先装运行时与 Provider
凡是加载模型的 job(声明式 plan job,以及可选的迁移生成 job),都要在运行 Atlas 之前安装该 ORM 的运行时与 Atlas provider,具体步骤以 ORM 指南为准。Django 示例:actions/setup-python,然后 pip install django atlas-provider-django。ORM 加载器(data "external_schema")与 composite_schema 的组合方式见 stage-1-schema.md 的 1.3 小节。
步骤 4:只保留真实存在的测试
- 单元有 schema 测试 → 保留
schema/test; - 单元有迁移测试 → 保留
migrate/test; - 没有测试就不加对应步骤。
步骤 5:用真实默认分支 + 目录隔离
- 默认分支用
git symbolic-ref --short refs/remotes/origin/HEAD探测,不要硬编码master; - 触发路径用
**glob 限定在单元目录之下,并把working-directory设置为该目录; - 一个仓库含多个单元时,每个单元一个 job,各自独立目录与路径。
步骤 6:触发时机校验
- lint 只运行在 pull request 上,push 只运行在默认分支上。逐个检查生成的 job,包括从模板或组件引入的 job:GitLab 上要给引入的 push job 添加只匹配默认分支的
rules。
步骤 7:保持 latest 推送开启
不要关闭 push job 的 latest 推送(这是 migrate/push 的默认行为)。原因:Stage 4 的漂移检查读取的是无 tag 推送所存储的状态;如果流水线只推 commit tag,漂移检查会静默跳过。CLI 流水线(atlas migrate push --env ci <repo>)会同时推送 <repo> 与 <repo>:<sha> 两种形式(versioned.md Registry 小节)。
CI 中的 dev 数据库:两条路径
- 托管 GitHub runner 自带 Docker,
docker://URL 直接可用(如docker://postgres/17/dev?search_path=public); - 没有 Docker daemon 的 runner(GitLab 的 Docker executor、许多自托管 runner):把
dev指向仅附加到 Atlas job 的 service container(使用目标的引擎版本与 scope),或指向 runner 可以到达的一个空数据库(dev = getenv("DEV_URL"),值来自 CI secret); - 绝不在流水线顶层添加其他 job 会共享的 services、images 或 variables。
全部完成后,打开标题为 Add Atlas CI for <unit> 的 PR。
六、Check:验证接入是否成功
合并前的检查(agent 可自行执行):
-
PR 的 Atlas job 通过。注意:本 PR 没有新增迁移文件,lint 没有可分析的内容,可能不会发布报告——第一份报告要等下一个 schema PR 才会出现。用
gh pr checks <number>、glab ci status,或直接询问用户读取结果。 -
用户合并后,确认默认分支上的 push run 已通过(
gh run list --workflow <file> --branch <default> --limit 1、GitLab 流水线页面,或询问用户),且 registry 中已有合并提交的版本:atlas migrate ls --dir "atlas://<repo>?tag=<merge commit sha>" --latest声明式单元用
atlas cloud repo describe --slug <repo>查看 repo。 -
Atlas check 设为合并的必选项(required):这样失败的 lint 会阻止合并。由用户在仓库托管的 branch protection 中设置;Azure Repos 则是把指南中的分支策略里的 build validation 设为 Required。
-
可选演练:用户开一个带示例变更的草稿 PR(例如 Stage 2.3 演示过的 destructive change——删除某列),在 PR 评论中看到 lint 报告后,不合并直接关闭。
最后,向用户说明 CI 现在在每个 PR 和每次合并时做什么,并附上对应的 setup-cicd 官方文档链接。
源码佐证——lint 报告中的错误码:Stage 2.3 演示的删除列变更会触发 DS103(破坏性变更,删列)与 BC104(向后不兼容,运行中的客户端会失败)两条分析结果并给出修复建议;lint.md 的分析器表格确认 DS101–DS103 属于破坏性变更(Error 级),BC101–BC104 属于向后不兼容变更(Warning 级)。CI 会让这类 PR 在有人批准之前被拦截。
七、阶段完成的判定与后续衔接
按 SKILL.md 的 "Detect the Stage",Stage 3 判定"已完成"的条件是:默认分支上存在为该单元运行 Atlas lint(版本化)或 plan(声明式)的 workflow,且该 workflow 在默认分支上的最后一次 push run 已通过。这与本节 Check 的 1、2 两条完全对应;.atlas-onboarding.json 只记录仓库本身无法体现的决策(workflow、units、repo、deploy 目标),状态一律来自上述检查而不是对话记录。
Stage 3 之后进入 stage-4-deploy.md:届时在 push job 之后添加 migrate/apply(版本化)或 schema/apply(声明式)部署步骤,使 staging 从 atlas://<repo> 拉取版本部署,并在部署 env 中加入 check "migrate_apply" { drift { ... } } 漂移保护——这正是我们在步骤 7 中坚持保留 latest 推送的原因:漂移检查依赖无 tag 推送存储的状态。
延伸阅读(仓库内):
- cicd.md:完整版本化/声明式流水线 YAML、create-repo action、
migrate/diff自动生成、migrate/autorebase冲突解决、其他平台组件对照表; - lint.md:lint 分析器分类、错误码、策略配置与自定义规则;
- versioned.md:Registry 的 tag/version 语义、目录维护命令、多租户 apply;
- stage-4-deploy.md:从 Registry 部署到 staging、漂移检查与 cutover 计划。