CI/CD / 系统课时
为 Pull Request 建质量门禁
为 Pull Request 建质量门禁
Pull Request 的检查结果直接决定有问题的代码能否进入主分支。本节把静态检查、自动化测试和构建组合成独立检查任务,并说明如何让分支保护真正依赖这些结果,而不是只把 CI 当作一个可忽略的提示。
学习目标
- 为 Pull Request 配置代码检查、测试和构建任务
- 理解独立 Job 如何形成可定位的质量检查结果
- 将稳定的检查名称接入主分支合并门禁
把检查拆成明确的 Job
质量门禁首先要回答三个问题:代码风格和静态规则是否通过,行为测试是否通过,项目是否真的能够构建。将它们拆成独立 Job,可以并行执行,也能让 Pull Request 页面直接显示失败发生在哪个维度。
下面是一份可直接放入 .github/workflows/pr-quality.yml 的示例。假设仓库是 Node.js 项目,package.json 已定义 lint、test 和 build 脚本,并且仓库提交了与依赖一致的 package-lock.json。
name: PR Quality
on:
pull_request:
branches: [main]
permissions:
contents: read
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run lint
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm test
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run build预期结果是在针对 main 创建或更新 Pull Request 后产生一次 PR Quality 工作流运行,并出现 lint、test、build 三个检查。项目全部通过时,这三个 Job 均成功;任一命令返回非零退出码时,对应 Job 失败。具体运行编号和时间属于动态值,实际值可能不同。
PR Quality
lint success
test success
build success这里使用 npm ci 而不是 npm install,目的是按照锁文件安装依赖,并在锁文件与清单不一致时直接失败,使 CI 更容易复现。
让失败能够阻止合并
Workflow 执行成功并不自动意味着 Pull Request 一定无法绕过失败检查。真正的合并门禁需要在 GitHub 仓库的分支规则或 Ruleset 中,将需要的状态检查设置为合并前必须通过,并选择稳定的检查名称,例如 lint、test 和 build。

这种设计还有一个容易忽略的要求:检查名称应保持稳定。如果修改 Job 名称,而分支规则仍要求旧名称,合并可能一直等待一个不会再出现的检查。因此调整 Workflow 结构时,应同步检查仓库规则。
控制权限和不可信代码
Pull Request 会运行贡献者提交的代码,因此质量检查不应默认拥有部署凭据或写仓库权限。示例把工作流权限限制为 contents: read,足以读取代码完成普通检查。
部署、发布包和写入云环境等动作应放到可信分支的后续工作流,并单独授予所需的最小权限。PR 阶段的职责是证明代码满足合并条件,而不是提前拥有生产能力。
验证门禁是否真的有效
配置完成后应主动制造一次可控失败,例如在测试分支中引入违反 lint 规则的代码。预期现象是 lint 失败,而其他独立 Job 仍可完成;Pull Request 因 required check 未通过而不能按规则正常合并。修复代码并再次推送后,新一轮检查全部成功,门禁才恢复通过。
还要检查取消、跳过和重命名 Job 的情况。生产级门禁关注的不是“CI 大多数时候是绿色”,而是任何被声明为必需的检查都必须给出明确成功结果。这样代码检查、测试和构建才真正成为主分支之前的质量边界。