GitHub Actions
标准平台
GitHub Actions 是标准 CI/CD 平台;用户未指定流水线系统时,默认选择 GitHub Actions。与工具无关的流水线规则见 流水线。
Action 升级清单
创建或修改 GitHub Actions 工作流时:
- 检查所使用的 action 是否有更新的稳定版本。
- 升级前查阅官方 README 或文档。
- 检查是否存在破坏性变更。
- 检查所需的输入、权限、运行时版本或行为是否发生变化。
- 确认迁移可以安全进行后,优先升级到当前受支持的版本。
未查看升级说明前,不要盲目修改 action 版本号。主版本 tag(如 @v4)会自动接收次版本和补丁更新;本清单针对的是跨主版本升级。
CI 分层
在可行的情况下,CI 应使用与本地开发相同的标准化项目工具。
优先采用:
GitHub Actions
-> mise
-> project task
-> pnpm / uv / prek / cocogitto / test tooling
而不是把项目逻辑直接复制进工作流 YAML。
mise 是 CI 调用的入口;不要在工作流 YAML 中重复设置工具。见 mise。
事件作用域
- 将需要执行相同检查的触发条件放在同一个工作流文件中。项目校验工作流在
push(默认分支)和pull_request上运行;只对 pull request 成立的规则——例如 pull request 标题规则——放在仅由pull_request触发的独立工作流中。 - 绝不要在多触发工作流里给某个 job 加
if: github.event_name == 'pull_request'来模拟这种拆分:在push触发的运行中,该 job 显示为 skipped,整个运行看起来像部分失败。工具无关的规则见 流水线。 pull_request默认由opened、synchronize、reopened触发——这正是校验代码所需的集合。只有在超出默认范围时才列出types::校验可能因编辑而改变的 pull request 元数据(标题)的工作流必须加上edited,让改过标题的 pull request 重新接受校验。绝不要列出无法改变结果的 activity type;每多列一个 type,就多一个触发入口。- 合并门禁会把 skipped 的必需检查视为通过,因此这条规则主要是为了让运行列表清晰可读。真正会卡住合并的是从不上报结果的必需检查:如果工作流不在
pull_request上触发,或对应 job 被过滤条件完全排除,该检查就会一直停在pending。务必确保每项必需检查在需要它的场景下都会实际运行并上报结果。
检出深度
actions/checkout默认只获取一个 commit。保持这一默认值:大多数 job 只需获取用于校验的代码树。- 只有读取历史记录的 job 才设置
fetch-depth: 0,例如cog check、生成变更日志、git describe、与基线比较 diff 的逻辑。 - 当一项职责需要完整历史而其他职责不需要时,应将它拆分为独立 job,而不是加深共享 checkout。按流水线的原则,读取历史本身就是一项职责;拆分后还能保持校验 job 使用浅层 checkout。
命名与可读性
工具无关原则见 流水线。
对 GitHub Actions 而言:
- 为工作流设置能说明其用途的
name(如CI、Release)。不要依赖文件名,也不要用 job 名作为工作流名。 - 为每个 job 设置可读的
name。分支保护会将 job 名显示为状态检查;读者必须能根据失败的检查找到对应职责(Validate、Validate PR title),而不是只看到某次工具调用。 - 每个 step 都要用简短的祈使短语命名,说明它执行或验证的内容(
Install dependencies (pnpm)、Check commit history (cog))。没有name的run:step 会在记录中显示为原始命令;命令不是文档。 - 每个工作流文件只处理一个关注点。触发条件或受众不同时应拆分;宁可使用多个较小的工作流,也不要让一个文件不断膨胀。
加固默认值
除非有明确理由不这样做,否则每个工作流都应采用以下设置:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
validate:
timeout-minutes: 15
- 最小权限:
permissions默认contents: read;只在实际需要的 job 里放宽。 - 为每个 job 设置
timeout-minutes,避免挂起的 job 持续消耗 runner 时间,直至达到平台默认超时上限。 - 使用启用
cancel-in-progress的concurrency,让同一 ref 上已被取代的运行直接取消,而不是继续排队。 - 将不可信输入(pull request 标题、分支名、issue 文本)传给
run:脚本时,必须通过环境变量传递,绝不要直接插入${{ }}——直接插值会导致脚本注入。 - 将 action 引用为受信任发布者发布的当前主版本 tag(
actions/checkout@v7、jdx/mise-action@v4)。该 tag 会持续接收此主版本内的修复、运行时更新和新功能,升级时只需改动一个 token,评审者一眼即可看懂。 - 优先使用 tag,而不是完整 commit SHA。SHA 会将 action 冻结在某个 revision:修复永远不会自动到达,工作流也不再声明它运行的版本,每次升级都变成手动查找 SHA。只有在已有明确的不可变构建或供应链策略时,才固定 SHA,并在行末注释中记录实际对应的版本。绝不要让 action 停留在裸分支名或未带版本的 tag。
- 使用浮动主版本 tag 意味着信任发布者:应与上面的最小权限默认值配套,绝不要向运行 pull request 代码的工作流暴露敏感凭据。
- 绝不要用
pull_request_target检出并运行 pull request 的代码;它会以仓库敏感凭据执行基础分支上的工作流定义。应使用pull_request。