# PR #22400 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[CI] Fast-fail on lint check failure in check-stage-health
- 合并时间：2026-04-09 08:17
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22400

---

# 执行摘要

该 PR 为 `check-stage-health` GitHub Action 添加了 lint 检查失败快速失败机制，当独立的 `lint.yml` 工作流失败时，立即终止后续 CI 测试任务，避免资源浪费。通过使用 `checks.listForRef` API 跨工作流查询 lint 状态，解决了原有 `listJobsForWorkflowRun` 只能查看同一工作流内任务的限制。这是一个典型的 CI 基础设施优化，旨在提升 CI 执行效率和开发者反馈速度。

# 功能与动机

**为什么做这个变更？**根据 PR body 描述，主要目标是让 PR 测试任务在 lint 检查失败时快速失败（fast-fail）。当前 `check-stage-health` 动作只能检测同一工作流内的任务失败，而 lint 检查运行在独立的 `lint.yml` 工作流中，因此无法及时检测 lint 失败，导致后续测试任务继续执行，浪费 CI 资源。

**关键表述引用：**

> "Add lint failure detection to the `check-stage-health` action so that PR test jobs fast-fail when the lint check (from the separate `lint.yml` workflow) has failed."

# 实现拆解

**核心改动文件：**`.github/actions/check-stage-health/action.yml`

**主要修改点：**

1. **描述更新**：将 description 从 "Fail fast if any job in the current workflow run has already failed. Auto-skips for scheduled runs." 更新为 "Fail fast if any job in the current workflow run has already failed, or if the lint check (from lint.yml) has failed. Auto-skips for scheduled runs."，明确新增功能。

2. **lint 状态检查逻辑**：在 JavaScript 代码中添加了跨工作流查询 lint 状态的逻辑：
```javascript
// Check lint status from the separate Lint workflow (lint.yml).
// listJobsForWorkflowRun only sees jobs within the SAME run, so we use
// checks.listForRef which queries by commit SHA across ALL workflows.
const ref = context.payload.pull_request?.head?.sha || context.sha;
const { data } = await github.rest.checks.listForRef({
  owner: context.repo.owner,
  repo: context.repo.repo,
  ref: ref,
  check_name: 'lint',
});
const lintRun = data.check_runs.find(
  cr => cr.app?.slug === 'github-actions'
);
if (lintRun?.status === 'completed' && lintRun?.conclusion === 'failure') {
  core.setFailed('Fast-fail: lint check failed');
  return;
}
```

**设计要点：**

- 使用 `checks.listForRef` API 按 commit SHA 查询所有工作流中的检查状态，而非局限于同一工作流。
- 通过 `check_name: 'lint'` 过滤出 lint 检查，并通过 `app?.slug === 'github-actions'` 确认是 GitHub Actions 运行。
- 当 lint 检查状态为 `completed` 且结论为 `failure` 时，调用 `core.setFailed` 终止执行。
- 保留了原有的跳过保护逻辑（定时运行、`SKIP_STAGE_HEALTH_CHECK` 环境变量），确保向后兼容。

# 评论区精华

**讨论概况：**该 PR 没有 review 评论（`review_comments_count: 0`），表明变更被直接接受或通过其他渠道验证。

**测试验证：**从提交历史可以看出作者进行了自我测试：
1. 提交 `4040b742`："test: intentional lint failure for fast-fail testing" - 故意引入 lint 错误以验证快速失败机制。
2. 提交 `5cd4cd31`："revert test lint failure" - 回滚测试更改，恢复干净状态。

这展示了作者通过实际测试验证功能有效性的务实做法。

# 风险与影响

**技术风险：**

1. **API 依赖风险**：实现依赖于 GitHub API 的 `checks.listForRef`，如果 API 调用失败、超时或速率受限，可能影响 `check-stage-health` 的正常执行。
2. **配置敏感性**：逻辑假设 lint 检查的名称为 `'lint'` 且由 GitHub Actions 运行，如果 lint 工作流配置变更（如重命名、使用其他 CI 工具），可能导致查询失败或误判。
3. **边缘情况处理**：虽然保留了跳过保护逻辑，但新增的 lint 检查可能在特定场景下（如并发运行、状态同步延迟）产生意外行为。

**影响评估：**

- **正面影响**：减少因 lint 错误导致的 CI 资源浪费，特别是对于资源密集型测试任务；开发者更快获得 lint 失败反馈，缩短修复周期。
- **影响范围**：仅限于 CI 流程，不涉及核心业务逻辑；对现有 CI 流程的修改是增量式的，保留了原有跳过机制。

# 关联脉络

**与历史 PR 的关系：**

- **PR 22395、22388、22308**：同属 CI 基础设施优化类别，都关注提升 CI 效率和稳定性。本 PR 延续了这一趋势，通过快速失败机制减少不必要的测试执行。
- **PR 22308**：特别相关，因为它也涉及 CI 验证和预防性措施（通过 pre-commit 钩子防止 CI 中断），与本 PR 的 " 快速失败以减少浪费 " 理念一致。

**演进方向：**从近期历史 PR 看，sglang 仓库持续投入 CI 基础设施改进，包括测试分区调整、权限管理、工作流优化等。本 PR 是这一方向的延续，体现了团队对 CI 效率和资源利用率的关注。这种 " 快速失败 " 模式未来可能扩展到其他类型的检查（如单元测试、构建检查），形成更全面的 CI 健康检查体系。