Atlas 数据库 CI 接入指南:PR 自动 lint/plan,合并即推送 Atlas Registry(Stage 3)

原创2026-10-10 20:30:331,382 阅读
文章标签:数据库开发工具数据工程

Atlas 数据库 CI 接入指南:PR 自动 lint/plan,合并即推送 Atlas Registry(Stage 3)

本篇指南对应 Atlas 托管式数据库接入流程(atlas-onboard skill)的第三阶段(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 的事情。

开始前需要满足两个前提:

  1. Stage 2 的项目 PR 已合并:atlas.hcl、期望状态(schema 或 ORM 模型)以及版本化单元的 migrations/atlas.sum 已经进入默认分支(对应 stage-2-workflow.md 与 SKILL.md 中 "Finished when" 的判定条件);
  2. 工作流与 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

两点补充:

  1. 复用已有 secret:如果仓库已经存在其他名字的 Atlas token secret,直接复用并把该名字写进 workflow 即可。CLI 本身也读取环境变量 ATLAS_TOKEN。
  2. 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 可自行执行):

  1. PR 的 Atlas job 通过。注意:本 PR 没有新增迁移文件,lint 没有可分析的内容,可能不会发布报告——第一份报告要等下一个 schema PR 才会出现。用 gh pr checks <number>、glab ci status,或直接询问用户读取结果。

  2. 用户合并后,确认默认分支上的 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。

  3. Atlas check 设为合并的必选项(required):这样失败的 lint 会阻止合并。由用户在仓库托管的 branch protection 中设置;Azure Repos 则是把指南中的分支策略里的 build validation 设为 Required。

  4. 可选演练:用户开一个带示例变更的草稿 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 计划。
登录后查看全文
atlas