GitHub CodeQL 2.26.3 更新了什么：Actions 查询识别与升级注意事项

GitHub CodeQL 2.26.3 的更新重点不在版本号迭代，核心优化是静态分析对 JavaScript、TypeScript、Vue 代码的建模覆盖更完整，同时补强了 GitHub Actions 工作流查询的识别能力。负责维护代码扫描流水线的团队升级后，最优先要做的是复核查询结果和工作流扫描边界，不能只看扫描任务执行通过就直接全量上线。

建议先挑一个有代表性的仓库固定 CodeQL 版本，对比升级前后的告警内容、扫描日志和 Actions 查询结果，确认没问题之后再推广到整个组织；2.26.3 提供的是识别能力的增强，不会自动替你修复项目里的代码风险。

这次更新真正改变了哪些检查结果

GitHub 官方变更说明把 2.26.3 的内容分成语言建模和查询调整两部分。前者覆盖 JavaScript、TypeScript、Vue 源码，意味着分析器能理解更多项目结构；后者针对 GitHub Actions 查询，改进了对 merge_group 事件中不可信数据的识别。

这类能力更新通常只会改变“能不能扫描到风险路径”，不会自动调整业务代码本身的风险等级。升级后告警变多，大概率是扫描覆盖面扩大了；告警变少，也可能是查询规则、配置项或者构建环境出现了变动，不能单凭告警数量多少判断扫描质量。

升级前先记录一份可比较的基线

先用当前正在用的旧版本跑一次完整扫描，把以下信息存到构建记录或者制品说明里：

codeql version
codeql database analyze --format=sarif-latest --output=before.sarif db
git rev-parse HEAD
gh run list --limit 10

这里不需要完全照搬示例命令，核心是保证前后两次运行使用同一份代码、相同的查询套件，构建环境尽可能保持一致。如果仓库用了自定义查询，还要记录查询包版本、存储路径和构建参数，避免把环境差异误判成 CodeQL 版本变动带来的结果。

自定义 Actions 查询要重点复核什么

如果仓库维护了针对工作流的自定义查询，先搜索是否引用了被移除的 codeql.actions.security.SelfHostedQuery 模块：

rg -n "SelfHostedQuery|merge_group|schedule" .github codeql
codeql query compile --threads=0 codeql/custom-actions.ql

发现模块引用时，不要直接把查询文件改成“能编译”就算完成。应先确认原查询想保护的资产、输入来源和结果字段，再按 2.26.3 的可用库重新表达规则。对于 merge_group 和 schedule 这类事件，还要分别检查触发条件与外部输入是否可能进入命令、路径或权限配置。

用同一套仓库做升级后的验收

推荐把验收拆成三层执行：先确认分析器能正常构建数据库，再确认默认查询套件可以完成全量扫描，最后单独运行自定义的 Actions 查询。每层都要保存退出码、日志和结果文件，不要只留一个“检查通过”的状态记录。

1. 构建层：检查 JavaScript、TypeScript、Vue 项目能不能完成和之前一致的依赖安装、数据库创建流程。
2. 查询层：对比升级前后的 SARIF 结果，按规则、文件和严重级别逐一核对变动。
3. 工作流层：用测试分支验证普通提交、合并队列和定时触发的场景，确认事件类数据没有被错误判定成可信输入。
4. 回退层：保留上一版本的分析器、查询包和运行参数，遇到无法解释的异常结果时先恢复到基线版本。

哪些变化不能直接当成漏洞或修复

静态分析的结果依赖源码、依赖解析、构建过程、查询套件和多份配置共同作用。一次升级后出现新的告警，首先要确认它对应的是新增的建模能力、查询逻辑调整，还是项目本身的代码变动；反过来，告警消失也不能直接证明对应的风险已经被修复。

针对生产线上的扫描流水线，更稳妥的做法是先把 2.26.3 放到可观察的扫描矩阵里灰度运行，关注分析失败率、扫描耗时、告警去重后的变动和开发者复核结论。等所有结果的变动都有合理解释之后，再推广到更多仓库。

常见问题

升级到 CodeQL 2.26.3 会自动修复漏洞吗？

不会。它主要优化分析器建模和查询识别逻辑，风险修复仍然需要开发者根据告警定位代码、依赖或者工作流配置后自行完成验证。

为什么告警数量可能变多？

新增语言或框架建模能力后，分析器可能覆盖之前没有纳入统计的路径。要结合对应规则、关联文件和日志逐一核对，不要只看告警总数的增减。

自定义查询引用 SelfHostedQuery 怎么办？

先确认模块移除对查询语义的影响，再基于当前可用的库重写规则并完成编译验证；不要用改名或者注释规则的方式掩盖模块缺失的问题。

需要立刻全组织升级吗？

不需要全量同步升级。先选一个语言和工作流类型都有代表性的仓库做对照验收，备好回退材料之后再分批扩大范围即可。

把版本更新变成一次可解释的验收

CodeQL 2.26.3 的实际价值，要通过真实仓库里的建模覆盖情况、查询结果准确度和工作流扫描边界校验才能验证。把版本固定、结果对照、自定义查询编译和回退路径一起纳入流水线流程，团队才能明确这次升级实际改变了什么，也能在结果异常的时候快速恢复服务。

资料核对：GitHub 官方变更说明 与 CodeQL 官方变更记录。