# PR #21345 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[CI] Use ETag conditional requests in `wait-for-jobs` and add CI infra to check-changes
- 合并时间：2026-03-26 05:40
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/21345

---

# 执行摘要
本 PR 优化了 SGLang 仓库的 CI 工作流，通过在 `wait-for-jobs` 中使用 ETag 条件请求减少 GitHub API 速率限制消耗，并将默认轮询间隔从 120 秒降低到 60 秒以加速检测。同时扩展变更检测覆盖 CI 基础设施文件，确保修改正确触发测试，提升 CI 效率和可靠性。

# 功能与动机
动机是解决 GitHub API 速率限制问题，避免不必要的配额消耗，并确保 CI 基础设施变更被正确检测。根据 PR body，关键表述包括：
- "Without ETag, every poll consumes 1 rate-limited call regardless of whether job statuses changed"，强调无 ETag 时每次轮询都消耗配额。
- "CI infra files were not covered by change detection — modifications to them would not trigger any test jobs"，指出之前 CI 基础设施文件未被检测，导致修改后不触发测试。

# 实现拆解
实现主要集中在两个文件：
1. **`.github/actions/wait-for-jobs/action.yml`**：
 - 新增 `fetchJobs()` 函数，使用 ETag 条件请求（`If-None-Match` / `ETag`）处理轮询。
 - 关键代码逻辑：
     ```javascript
     async function fetchJobs() {
       // 设置 ETag 头部
       if (lastEtag) {
         params.headers['if-none-match'] = lastEtag;
       }
       // 处理 304 响应
       if (err.status === 304 && lastJobs) {
         cachedCalls++;
         return { jobs: lastJobs, cached: true };
       }
       // 分页处理：当作业数 >100 时清除 ETag
       if (response.data.total_count > 100) {
         lastEtag = '';
       }
     }
     ```
 - 默认轮询间隔从 120 秒改为 60 秒，并在缓存轮询时跳过日志输出。
 - 添加速率限制日志，记录 `x-ratelimit-remaining` 和调用统计。
2. **`.github/workflows/pr-test.yml`**：
 - 扩展变更检测路径，新增 `.github/workflows/pr-gate.yml` 和 `.github/actions/**` 到 `main_package` 检测，使用 `dorny/paths-filter` 和 API-based 方法。
 - 更新 shell 脚本中的正则表达式以包含这些路径。

# 评论区精华
本 PR 未经过 review 讨论，所有修改由作者 hnyls2002 独自完成并合并，没有争议或设计权衡的公开讨论。

# 风险与影响
- **风险**：
 - ETag 缓存可能导致不一致，特别是在分页超过 100 个作业时，ETag 被清除以避免旧缓存，但可能增加额外 API 调用。
 - 降低轮询间隔到 60 秒可能提高 API 调用频率，但通过 ETag 缓解；如果 ETag 失效，可能增加配额消耗。
 - 跳过缓存轮询的日志输出减少了噪音，但可能隐藏调试信息。
- **影响**：
 - 减少 API 配额消耗：预计典型情况下每 PR 付费调用从 100 减少到 70，并发 PR 容量从 150 提升到 214。
 - 检测延迟改进：从最多 120 秒减少到 60 秒，加速 CI 阶段转换。
 - 确保 CI 基础设施变更正确触发测试，提高维护效率和团队协作。

# 关联脉络
与近期历史 PR 相关，揭示 CI 基础设施的持续优化趋势：
- PR #21420 和 #21410：涉及 CI 工作流修改，优化变更检测和触发条件。
- PR #21393 和 #21331：CI 改进和重构，如添加重试机制和脚本重写，与本 PR 同属基础设施类别。
这些 PR 显示团队在集中精力提升 CI 可靠性和效率，本 PR 是这一方向的具体实践。