GitHub Code Scanning 默认设置与自定义规则的分工

第一次给仓库启用 GitHub Code Scanning 时，最容易混淆的不是“要不要扫描”，而是默认设置和自定义规则到底谁负责什么。简单记：默认设置负责低维护地把扫描跑起来；配置文件负责在这个基础上补充查询或排除路径；只有需要自定义构建、矩阵运行或调度时，才需要 advanced setup。

官方文档：https://docs.github.com/en/code-security/concepts/code-scanning/setup-types

默认设置先解决什么问题

默认设置会根据仓库代码自动生成 CodeQL 配置，并选择要分析的语言、查询套件和触发事件。它适合刚开始建立安全扫描基线的仓库：启用后先有一次初始分析，后续由推送、拉取请求和符合条件的计划任务触发扫描，团队不必先维护一份工作流文件。

默认设置并不等于“所有规则都打开”。界面里可以调整分析语言和查询套件；默认查询套件更偏向相关性与误报之间的平衡，想扩大覆盖面时可以选择 security-extended，但这通常意味着更多告警需要人工判断。

自定义规则适合补充什么

如果现有默认设置已经能满足触发方式和运行环境，只是想补充查询、排除目录或修正仓库的 CodeQL 识别范围，可以继续保留默认设置。GitHub 支持通过 github-codeql-config-file 属性指定自定义 CodeQL 配置文件，这份配置会和默认设置自动生成的配置合并。

这一区别很重要：自定义配置文件是“在默认能力上加细节”，不是把默认设置改造成另一套完全自管的工作流。组织级场景可以给多个仓库设置统一的配置文件默认值；单仓库试用时，也可以先在一个仓库上设置属性，观察结果后再扩大范围。

# 这个配置示例只表达扩展意图，具体查询包名称要按仓库实际情况选择
name: code-scanning-extension
queries:
  # 这里放需要额外纳入分析的查询或查询包
  - uses: ./security-queries
paths-ignore:
  # 排除不属于业务源码的生成目录，避免扫描范围失焦
  - vendor
  - generated

上面的重点不是复制一份“万能配置”，而是明确边界：查询扩展和路径收窄仍属于配置层；如果你还要自己决定构建命令、运行矩阵或扫描时间表，就已经超出这层的舒适范围。

什么时候该转向 advanced setup

当仓库需要编译型语言的专用构建步骤、不同操作系统或语言矩阵、特殊权限、完全自定义的触发条件，或者要把结果接入现有 CI/CD 流程时，advanced setup 才更合适。它会生成一个可编辑的工作流，换来的是更强的控制力，同时也把维护责任交回团队。

不要因为“想加一条自定义规则”就立刻切换。先问三个问题：默认设置是否已经覆盖要分析的语言？配置文件能否表达需要的查询和路径范围？是否真的需要自己控制构建和调度？前两个答案为“能”时，留在默认设置通常更省维护。

最小核对：确认改动真的落在预期层级

完成设置后，先回到仓库的 Settings → Advanced Security → CodeQL analysis，确认当前显示的是 Default 还是 Advanced。再查看工具状态页，核对最近扫描的时间、实际分析的语言、规则覆盖情况和错误信息。

如果结果突然重复或与预期不一致，优先排查是否同时保留了默认设置和旧的 CodeQL 工作流。两套配置可能产生多个分析来源；切换前应明确停用旧路径，避免把“规则变多”误判成“扫描更完整”。

最后，把选择写进仓库维护说明：默认设置解决基础覆盖，配置文件解决局部扩展，advanced setup 解决工作流控制。这样后续新增语言或规则时，团队能先找到正确的改动位置。

相关问题

只想增加查询，必须维护工作流吗？

不一定。先评估默认设置上的配置文件扩展；只有配置层无法表达所需构建或运行控制时，再考虑 advanced setup。

启用默认设置后为什么没有按周扫描？

官方说明中，按周计划通常要先由一次推送或拉取请求触发扫描；仅有初始配置或语言变化不一定会启动该计划。