---

name: repo-ci-pipeline description: 从 Terra-Wiki 蒸馏的通用 CI 规范：CI 与"完成的定义"严格相等、服务容器跑测试库、并发取消与分支保护联动

项目开发规范蒸馏：CI 流水线设计

适用时机

• 给项目设计或收敛 CI：跑什么、不跑什么、怎么和分支保护配合。
• CI 又慢又爱挂、或 PR 永远卡在"等待检查"时，用这份清单对照排查。

规范条目

1. CI 校验的内容严格等于"完成的定义"（本项目即 typecheck + test），不多不少——CI 里多出来的每一步都是维护负担和挂掉的新姿势。
2. 仓库没有 linter 就不加 lint（必挂）；有 linter 则 lint 必须进 CI。
3. 测试需要数据库时用 CI 的 services 起服务容器（如 postgres），显式写 TEST_DATABASE_URL，且与本地测试配置同默认值——连接串一眼可见，避免"本地过 CI 挂"。
4. 服务容器加健康检查（如 pg_isready + 重试参数），不等满超时再跑。
5. 依赖安装用 --frozen-lockfile；包管理器版本不写死在 CI，从 package.json 的 packageManager 字段读——版本真相只存一处。
6. 语言运行时版本在 CI 显式声明，并开依赖缓存。
7. 同一分支推送用 concurrency 分组 + cancel-in-progress，旧检查直接取消，省时也避免检查列表越积越长。
8. 触发条件：push 到 main/develop + 面向这两个分支的 PR，与分支保护要求的 check 对齐。
9. 分支保护 required check 的 contexts 必须与 CI job 名一致；改 job 名时 contexts 同步改，否则 PR 永远卡在"等待检查"。
10. workflow 里用注释说明"这一步为什么存在/为什么不加"，让下一个人不必重新踩决策。

陷阱与例外

• CI 挂了先分清环境差异（连接串、运行时版本、锁文件）还是代码问题；环境类挂法通常本地复现不出来。
• 迁移/部署不在 CI 里做：发布产物走单独的 release workflow，迁移在容器启动时自动跑，CI 只管验证。

项目特有约定（不可迁移）

• Postgres 17 + 55432 测试端口、本地测试配置的默认连接串、pnpm 与 Node 的具体版本组合。

验证方式

• 提一个只改注释的 PR，CI 应几分钟内绿。
• 故意提交类型错误，确认 verify job 红、PR 被分支保护挡住。