调用GitHub Commit Status API返回空列表问题求助

数据老陈

2026-8-26

GitHub Commit Statuses接口返回空列表排查方案

返回空列表[]基本集中在以下几个原因，按出现概率从高到低排查：

接口返回数据范围不匹配
目前绝大多数CI服务（包括GitHub Actions原生流水线）默认提交的是Check Run类型的检查记录，不会写入老版Commit Status存储。你调用的/commits/{sha}/statuses（复数形式）接口仅能查询到通过旧版Commit Status API写入的状态数据，无法读取Check Run记录，这是该问题最高发的诱因。
验证方式：直接调用单数形式的综合状态接口/commits/{sha}/status，该接口会聚合旧版Status和新版Check Run的结果，返回整体状态。如果该接口返回的total_count字段大于0、state字段有有效值（pending/success/failure/error），就说明你需要的检查数据走的是Checks通道，不是旧Status通道。
如果需要拉取全量检查项明细，替换为Check Run查询接口即可，示例代码：
```
response = requests.get(
    f"https://api.github.com/repos/{owner}/{repo}/commits/{sha}/check-runs",
    headers=headers,
    proxies=proxy
)
```
请求Token权限不足
PR查询接口可以读取公开级别的仓库数据，哪怕Token权限不全甚至不带Token都可能正常返回，但Commit Status/Check Run相关接口对权限要求更高：
- 公共仓库：匿名请求可能被限流截断，返回空结果，需要携带至少拥有repo:status、checks:read权限范围的Token
- 私有仓库：Token必须勾选repo完整权限域，否则无法读取状态类数据
目标提交本身无关联状态记录
先确认你提取到的head.sha是完整40位的提交SHA（短SHA在部分场景下会匹配异常），如果PR刚创建还未触发任何CI任务、也没有人工/系统给该提交打过状态标记，接口返回空列表是符合预期的，可以先到仓库网页端打开对应提交的详情页，确认页面上确实存在状态/检查记录再调试接口。
分页参数遗漏（低概率）
Statuses接口默认单页最多返回30条记录，若对应提交的历史状态记录超过30条，需要携带per_page、page参数翻页，但该场景不会返回完全空的列表，仅会出现记录不全的问题，优先级放在最后排查即可。

快速排查步骤：

打印提取到的SHA值，到仓库网页端手动访问提交详情页，确认页面存在检查记录
校验请求头中Authorization字段格式为token 你的有效Token值，且Token拥有对应权限
替换为Check Run接口或单数status接口发起请求，验证返回结果

内容的提问来源于stack exchange，提问作者pt_dev