GitHub Actions 的 GitHub Code Quality 独立路径怎么评估：权限边界、迁移步骤与失败回退

如果团队的 GitHub Actions 报表、成本看板或审计脚本仍只认 dynamic/github-code-scanning/codeql，最近可能会漏掉 GitHub Code Quality 的运行记录。GitHub 在 2026 年 8 月 20 日把 Code Quality 的工作流路径和执行身份独立出来，已启用的仓库不需要重新配置扫描，但依赖旧路径或旧 actor 的统计逻辑需要迁移。

真正需要改的通常不是仓库里的分析配置，而是围绕 Actions 运行记录、用量报表和审计筛选建立的识别条件。

这次变更到底影响哪一层

GitHub 官方说明把变化限定在运行识别上：Code Quality 分析本身不需要重新配置，已经启用的仓库继续按原状态运行。变化体现在 Actions 运行历史和用量报告里，Code Quality 不再与 code scanning 共用同一条动态路径和执行身份。

具体来说，Code Quality 现在使用 dynamic/github-code-quality/codeql，并显示 github-code-quality 作为 actor；此前使用的是 dynamic/github-code-scanning/codeql 与 github-advanced-security。这两个字段很容易被写死在看板查询、导出脚本和审计规则中。

官方变更说明：Separate GitHub Actions path for GitHub Code Quality。

先按负载和约束分辨迁移范围

只有仓库扫描，没有自建统计

这种情况通常不需要改仓库。打开最近一次 Code Quality 运行，确认它在 Actions 历史中能单独识别即可。不要为了追赶路径名称去重建工作流，重建反而可能引入重复运行。

有用量报表、成本归因或团队看板

这是最容易受影响的一类。凡是以路径或 actor 作为过滤条件的查询，都要把 Code Quality 的新值加入。过渡期间建议保留旧值，用双口径核对一轮数据，避免历史月份突然归零。

有审计脚本或自动化告警

脚本不仅要改过滤值，还要检查输出字段是否被当成唯一身份。比如只判断 actor 是否为 github-advanced-security，可能会把真实的 Code Quality 运行标成“未知”。这类逻辑应改成明确的类型映射，并为未知值保留告警。

最小迁移方案：先补识别，再补验收

可以把迁移拆成三步。第一步，搜索仓库、数据仓库和报表定义中出现的旧路径与旧 actor；第二步，为 Code Quality 增加新路径和新 actor；第三步，把一条真实运行记录同时放进旧报表和新报表核对。

# 需要在配置仓库和报表定义中搜索的旧值
dynamic/github-code-scanning/codeql
github-advanced-security

# 新值
dynamic/github-code-quality/codeql
github-code-quality

这里的重点不是机械替换。代码扫描与 Code Quality 可能需要不同的成本归因、负责人或保留周期，建议先将路径映射为业务字段，再由报表按业务字段聚合。例如把两类运行分别标为 code-scanning 和 code-quality，保留原始 path 与 actor 供审计追溯。

推荐架构：兼容层加验证窗口

对已经运行多月的团队，最稳妥的结构是“原始事件层—标准化映射层—消费报表层”。原始层不改写 GitHub 返回的 path、actor 和时间；映射层同时认识新旧值；报表层只消费标准化的分析类型。这样将来再出现工作流身份调整时，不必逐个改看板。

兼容层至少保留一次完整结算周期。期间观察三项数据：Code Quality 运行数量是否出现断崖、按团队归因的总量是否与 Actions 用量报告接近、未知 path/actor 是否持续增长。三项都稳定后，再把旧值降级为历史兼容，而不是直接删除。

失败回退和常见误区

报表数量突然变少

先查过滤条件，不要先重跑工作流。对比运行历史中的 path 和 actor，通常可以迅速判断是新身份未纳入，还是仓库确实没有产生新的分析。

把识别迁移误做成仓库重配置

官方说明明确表示 Code Quality 本身不需要重新配置。若只是看板漏数，回滚应发生在报表映射层；仓库工作流保持不动，能减少重复分析和额外用量。

只改 actor，不改 path

两个字段都可能被用作筛选条件。只补 github-code-quality 而遗漏 dynamic/github-code-quality/codeql，会让一部分按路径统计的报表继续漏数。

相关问题

已启用的仓库需要重新打开 Code Quality 吗？

不需要。变更说明指出，已启用的仓库继续按原配置运行，重点是更新依赖旧路径或旧 actor 的外部统计和筛选逻辑。

旧路径要立即删除吗？

不建议立即删除。保留旧值用于历史数据兼容和迁移期对账，等完整结算周期验证通过后再收紧查询范围。

哪里核对官方规则？

可查看 GitHub Code Quality 文档，并以 GitHub Changelog 的变更说明核对路径和 actor 的最新定义。

落地清单

• 记录旧 path、旧 actor、新 path、新 actor 四个值。
• 搜索报表、脚本、告警和成本归因配置。
• 增加双口径映射，保留原始字段。
• 用真实运行记录核对 Actions 历史与用量报告。
• 观察完整结算周期，再决定是否收紧兼容逻辑。