用途
CodeQL 代码扫描技能提供配置和运行 CodeQL 代码扫描的过程性指导，既可通过 GitHub Actions 工作流实现，也可使用独立的 CodeQL CLI。适用于以下请求：创建或自定义 codeql.yml 工作流；在默认设置与高级设置之间选择；配置 CodeQL 语言矩阵、构建模式或查询套件；本地运行 CodeQL CLI（database create、database analyze、github upload-results）；理解或解读 CodeQL 的 SARIF 输出；排查分析失败（构建模式、编译型语言、运行器要求）；为单体仓库设置按组件扫描；配置依赖缓存、自定义查询包或模型包。
支持的语言
CodeQL 支持以下语言标识符：C/C++（c-cpp，别名 c、cpp）、C#（csharp）、Go（go）、Java/Kotlin（java-kotlin，别名 java、kotlin）、JavaScript/TypeScript（javascript-typescript，别名 javascript、typescript）、Python（python）、Ruby（ruby）、Rust（rust）、Swift（swift）、GitHub Actions（actions）。别名标识符与标准标识符等价，例如 javascript 不会排除 TypeScript 分析。
主要能力：GitHub Actions 工作流
第一步选择设置类型。默认设置可从仓库 Settings → Advanced Security → CodeQL analysis 启用，适合快速上手，对多数语言使用 none 构建模式。高级设置需创建 .github/workflows/codeql.yml 文件，可完全控制触发器、构建模式、查询套件和矩阵策略。从默认切换到高级时，需先禁用默认设置，再提交工作流文件。
第二步配置工作流触发器，定义扫描运行时机：push 在推送到指定分支时扫描，结果出现在 Security 标签页；pull_request 扫描 PR 合并提交，结果以 PR 检查注解形式出现；schedule 对默认分支进行周期性扫描（cron 必须存在于默认分支）；若仓库使用合并队列，可添加 merge_group。可通过 paths-ignore 跳过仅文档类 PR 的扫描，该配置控制工作流是否运行，而非分析哪些文件。
第三步配置权限，遵循最小权限原则：security-events: write（上传 SARIF 结果所必需）、contents: read（检出代码所必需）、actions: read（私有仓库使用 codeql-action 时必需）。
第四步配置语言矩阵，使用矩阵策略并行分析每种语言。对编译型语言设置相应构建模式：none 表示无需构建（支持 C/C++、C#、Java、Rust）；autobuild 为自动构建检测；manual 为自定义构建命令（仅高级设置）。
第五步配置 CodeQL 初始化与分析，使用 github/codeql-action/init@v4 和 github/codeql-action/analyze@v4。查询套件选项包括 security-extended（默认安全查询加额外覆盖）和 security-and-quality（安全加代码质量查询），也可通过 packs 输入使用自定义查询包。可在 init 动作上设置 dependency-caching: true 以跨运行缓存已恢复的依赖。使用 category 区分单体仓库中的 SARIF 结果。
第六步单体仓库配置，使用 category 参数分离 SARIF 结果，并通过 CodeQL 配置文件（.github/codeql/codeql-config.yml）限制分析目录，配置 paths 与 paths-ignore，再在工作流中通过 config-file 引用。
第七步手动构建步骤，当 autobuild 失败或需要自定义构建命令时，将 build-mode 设为 manual，并在 init 与 analyze 之间添加显式构建步骤。
主要能力：CodeQL CLI
第一步安装 CodeQL CLI：从 https://github.com/github/codeql-action/releases 下载 CodeQL bundle（包含 CLI 与预编译查询），解压并加入 PATH，然后通过 codeql resolve packs 和 codeql resolve languages 验证安装。应始终使用 CodeQL bundle，而非独立 CLI 下载，以确保查询兼容性并获得预编译查询带来的性能优势。
第二步创建 CodeQL 数据库：单语言使用 codeql database create codeql-db --language=javascript-typescript --source-root=src；多语言使用 --db-cluster 集群模式。对编译型语言通过 --command 提供构建命令。
第三步分析数据库：codeql database analyze codeql-db javascript-code-scanning.qls --format=sarif-latest --sarif-category=javascript --output=results.sarif。常用查询套件包括 <language>-code-scanning.qls、<language>-security-extended.qls、<language>-security-and-quality.qls。
第四步上传结果到 GitHub：codeql github upload-results --repository=owner/repo --ref=refs/heads/main --commit=<commit-sha> --sarif=results.sarif，需要具有 security-events: write 权限的 GITHUB_TOKEN 环境变量。
CLI 服务器模式：运行多个命令时，可通过 codeql execute cli-server 避免重复的 JVM 初始化。
告警管理
告警有两个严重级别维度：标准严重级别（Error、Warning、Note）和安全严重级别（Critical、High、Medium、Low，源自 CVSS 分数，显示优先级更高）。GitHub Copilot Autofix 会为 PR 中的 CodeQL 告警自动生成修复建议，无需 Copilot 订阅，提交前应仔细审查建议。PR 中的告警以检查注解形式出现在变更行上，默认对 error/critical/high 级别告警使检查失败，可通过合并保护规则集自定义阈值，对误报应记录原因后驳回以保留审计线索。
自定义查询与包
可在 init 动作的 packs 输入中引用自定义查询包，例如 my-org/my-security-queries@1.0.0 或 codeql/javascript-queries:AlertSuppression.ql。使用 CodeQL CLI 创建和发布包：codeql pack init my-org/my-queries 初始化，codeql pack install 安装依赖，codeql pack publish 发布到 GitHub Container Registry。CodeQL 配置文件支持 paths、paths-ignore、queries 和 packs 等高级配置。
日志与调试
工作流日志包含关键指标：代码库代码行数（提取前基线）、提取行数（含外部库和自动生成文件）、提取错误/警告。启用详细诊断：GitHub Actions 可勾选“Enable debug logging”重新运行工作流；CodeQL CLI 可使用 --verbosity=progress++ 和 --logdir=codeql-logs。
故障排查
常见问题及解决方向包括：工作流未触发（检查 on 触发器、paths/branches 过滤、目标分支上是否存在工作流）；资源不可访问错误（添加 security-events: write 和 contents: read 权限）；autobuild 失败（改用 build-mode: manual 并添加显式构建命令）；未看到源代码（检查 --source-root、构建命令和语言标识符）；C# 编译器失败（检查 /p:EmitCompilerGeneratedFiles=true 与 .sqlproj 或旧项目的冲突）；扫描行数少于预期（从 none 切换到 autobuild/manual）；无构建模式下的 Kotlin（禁用再重新启用默认设置以切换到 autobuild）；每次运行缓存未命中（确认 init 动作上的 dependency-caching: true）；磁盘/内存不足（使用更大的运行器、通过 paths 配置缩小分析范围、使用 build-mode: none）；SARIF 上传失败（确保令牌具有 security-events: write，检查 10 MB 文件大小限制）；SARIF 结果超限（使用不同 --sarif-category 拆分多次上传、缩小查询范围）；存在两个 CodeQL 工作流（使用高级设置时禁用默认设置，或删除旧工作流文件）；分析缓慢（启用依赖缓存、使用 --threads=0、缩小查询套件范围）。
自托管运行器硬件要求
小型代码库（<100K LOC）：8 GB+ 内存，2 核 CPU。中型（100K–1M LOC）：16 GB+ 内存，4–8 核。大型（>1M LOC）：64 GB+ 内存，8 核。所有规模均需 SSD 且至少 14 GB 可用磁盘空间。
动作版本固定
建议将 CodeQL 动作固定到特定主版本，如 github/codeql-action/init@v4、autobuild@v4、analyze@v4。为获得最高安全性，可固定到完整提交 SHA 而非版本标签。
参考文件
技能包含以下参考文件，可按需加载：references/workflow-configuration.md（完整工作流触发器、运行器和配置选项）、references/cli-commands.md（完整 CodeQL CLI 命令参考）、references/sarif-output.md（SARIF v2.1.0 对象模型、上传限制和第三方支持）、references/compiled-languages.md（各语言构建模式和 autobuild 行为）、references/troubleshooting.md（全面的错误诊断与解决）、references/alert-management.md（告警严重级别、分类处理、Copilot Autofix 和驳回）。
适用场景与限制
适用于为代码仓库建立静态安全分析、在 PR 中拦截安全问题、本地运行 CodeQL 分析、单体仓库按组件扫描以及排查 CodeQL 分析问题。限制方面：部分构建模式仅高级设置支持（如 manual）；默认设置与高级设置不能同时启用；SARIF 上传有 10 MB 文件大小限制；自托管运行器需满足相应硬件要求；具体收费、价格和平台支持范围资料中暂未提供。