CodeQL 代码检查指南

本指南面向使用 GitCode Action 插件配置 CodeQL 代码安全检查功能、并期望使用 openLiBing 实现问题可视化的用户，涵盖工作流配置、参数说明、常用语言示例、结果查看及常见问题。

---

⚠️ 重要说明：CodeQL 在 GitCode 平台受许可限制，无法合规使用

CodeQL 引擎本体（codeql-cli-binaries）由 GitHub, Inc. 以专有条款发布。需要区分的是：查询规则库（github/codeql）采用 MIT 许可开源，但 CLI 二进制受《GitHub CodeQL Terms and Conditions》约束，不属于开源许可软件。根据官方条款：

1. 允许的使用范围仅限于：学术研究、产品演示、测试以 OSI 认可开源许可发布的 CodeQL 查询，以及对符合 OSI 开源许可的代码库进行分析；
2. "为自动化分析、CI 或 CD 生成 CodeQL 数据库"的场景，仅允许用于托管并维护在 GitHub.com 上的开源代码库；
3. 条款明确禁止在其他任何场景下为自动化分析、CI/CD 生成 CodeQL 数据库，也禁止将其用于非开源代码库（持有 GitHub Advanced Security 付费授权的场景除外）。

GitCode 平台的流水线不属于 GitHub 托管的运行环境，在 GitCode Action 中下载并运行 CodeQL 引擎执行自动化扫描，超出上述条款的授权范围。因此，受 codeql-cli-binaries 许可限制，基于本指南配置的 CodeQL 扫描链路无法在 GitCode 平台合规使用，后续章节内容仅作背景参考。

官方条款全文：GitHub CodeQL Terms and Conditions；官方许可摘要：CodeQL CLI 仓库 README · License。

---

1. 功能简介

1.1 什么是 CodeQL 代码检查

CodeQL 是一款静态代码安全分析引擎，能够对源代码进行安全漏洞扫描，识别 SQL 注入、XSS、命令注入、路径遍历等常见安全问题。openLiBing 平台通过 GitCode Action 插件的方式集成了 CodeQL 能力，用户只需在代码仓库中配置一个工作流文件，即可自动完成"代码扫描 → 结果上传 → 可视化展示"的完整链路，无需手动搭建 CodeQL 运行环境。

1.2 整体链路说明

一次完整的 CodeQL 检查流程分为以下环节：

代码仓库
   │
   ▼
① Action 触发工作流
   │
   ▼
② codeql-action 插件：执行安全扫描，生成 SARIF 结果文件
   │
   ▼
③ openlibing-upload-sarif 插件：将结果上传至 OBS 对象存储
   │
   ▼
④ 调用已发布的 openLiBing 接口解析 OBS 文件并写入数据库
   │
   ▼
⑤ openLiBing「开发管理 - 代码检查」模块可视化展示

其中 ①②③ 由代码仓库中配置的工作流文件驱动执行，④⑤ 由 openLiBing 平台后台服务自动完成，用户无需干预。

---

1.3 页面说明

1.3.1 查看问题列表

---

1.3.2 查看问题详情

---

1.4 版本说明

本指南中涉及的插件均由 GitCode 平台或团队持续维护迭代，其参数、默认值、行为可能随插件版本更新而发生变化。本文档配置示例基于以下版本编写：

插件	参考版本	说明
checkout	v1.0.6	GitCode 官方插件
setup-jdk	v2.1.0	GitCode 官方插件
codeql-action	v1.1.0	GitCode 官方插件
openlibing-upload-sarif	v1.0.8	openLiBing团队自研插件

📌 若插件已发布新版本，其参数或用法可能与本文档存在差异，请以插件市场中对应插件的最新官方帮助文档为准（查看方式见 2.4 如何查看插件官方帮助文档）。如在使用中发现本文档与实际行为不一致，欢迎反馈，我们会同步更新。

---

2. 前置准备

2.1 工作流文件路径与命名规范

CodeQL 检查的工作流配置文件需放置在代码仓库以下路径（该目录为 GitCode 官方约定的 Action 工作流目录）：

.gitcode/workflows/codeql.yaml

文件名可自定义，但需放置在 .gitcode/workflows/ 目录下才能被 GitCode 平台识别为工作流配置。

2.2 Secrets 配置清单

工作流中会用到以下几类凭据，均通过 ${{ secrets.XXX }} 的方式在 yaml 中引用，实际值需要提前配置到代码仓库的 secrets 中：

Secret 名称	用途	是否必配
ROBOT_TOKEN	用于 checkout 步骤拉取代码仓库	仅私有仓库需要配置；公开仓库可省略
OPENLIBING_OBS_AK / OPENLIBING_OBS_SK	用于将 CodeQL 扫描结果（SARIF 文件）上传至 OBS 对象存储	必配
OPENLIBING_APIG_KEY / OPENLIBING_APIG_SECRET	用于调用 APIG 接口，将扫描结果解析入库，最终在 openLiBing 平台可视化展示	见下方说明

⚠️ 关于 APIG 凭据的必配性说明

• 如果你希望在 openLiBing「开发管理 - 代码检查」模块中查看扫描结果的可视化报告，OPENLIBING_APIG_KEY / OPENLIBING_APIG_SECRET 为必配项；
• 如果不配置，不影响插件本身的执行结果（工作流仍会正常执行成功），但扫描结果只会上传到 OBS 存储为止，不会进入 openLiBing 平台展示。

2.3 AK/SK 获取方式与配置步骤

1. OPENLIBING_OBS_AK、OPENLIBING_OBS_SK、OPENLIBING_APIG_KEY、OPENLIBING_APIG_SECRET 四个凭据目前需要联系openLiBing持续集成团队获取。

2. 获取凭据后，请使用具备配置权限的账号，按以下步骤配置到代码仓库的 secrets 中（secret 命名需与 yaml 中引用的名称一致，如 ROBOT_TOKEN、OPENLIBING_OBS_AK 等）

💡 该凭据获取方式目前为人工申请流程，后续版本将优化认证方式，届时本节内容会同步更新。

2.3.1 组织（企业）级别配置方式

在组织下配置，则该组织下的所有项目（仓库）均生效。

2.3.2 项目（仓库）级别配置方式

在项目下配置，则仅在该项目下生效。

2.4 如何查看插件官方帮助文档

工作流配置文件中使用的 checkout、setup-jdk、codeql-action 等插件均由 GitCode 官方提供，其详细参数说明可通过以下方式查看：

在编辑 .gitcode/workflows/codeql.yaml 文件时，页面右侧会自动弹出 [插件市场] 侧边栏，在其中搜索对应插件名称（如 checkout），即可查看该插件的完整官方帮助文档。

📌 本指南 3.4～3.6 节仅摘录 CodeQL 检查场景下常用的核心参数，完整参数列表及更多高级用法（如跨仓库拉取、子模块、LFS 等），请以插件市场中的官方文档为准。

---

3. 工作流文件结构说明

3.1 整体结构总览

一个典型的 CodeQL 工作流文件包含以下几个部分：

name: codeql # 工作流名称，自定义
on: # 触发条件
  workflow_dispatch: # 支持手动触发
  push: # 支持 push 触发
    branches:
      - master
jobs:
  codeql: # job 名称，自定义
    name: codeql
    runs-on: [...] # 运行环境（runner）规格
    needs: []
    steps: # 具体执行步骤，按顺序执行
      - name: checkout # 第1步：检出代码
      - name: setup-xxx # 第2步：准备语言环境（可选，视语言而定）
      - name: codeql-analysis # 第3步：执行 CodeQL 扫描
      - name: upload sarif # 第4步：上传结果并触发可视化

四个步骤各自的职责是：拉代码 → 装环境 → 跑扫描 → 传结果。

3.2 触发条件（on）

• workflow_dispatch：允许在 GitCode 页面手动点击触发（前提：需要在主干分支中包含该配置文件）；
• push：代码推送到指定分支（如 master）时自动触发扫描，可按团队分支策略调整 branches 。

3.3 运行环境（runs-on）

runs-on 用于指定任务运行所依赖的机器规格，例如：

runs-on: ["codearts-hosted", "ubuntu-latest", "x64", "large"]

一般沿用示例中的配置即可。如需调整机型规格（如更大内存的机型），可参考 GitCode 官方文档。

3.4 checkout：检出代码

用于将目标代码仓库拉取到工作流运行环境中，GitCode 官方插件。

CodeQL 场景下的典型用法：

- name: checkout
  uses: checkout
  with:
    token: ${{ secrets.ROBOT_TOKEN }}

要点说明：

• 不填写 repository、ref 时，默认检出当前触发流水线的仓库和分支，满足 CodeQL "扫描自身仓库代码"的常规场景，无需额外配置；
• token 参数仅在私有仓库场景下需要配置，用于身份认证以拉取代码；公开仓库可省略该参数；
• 是否需要配置 token，需用户根据自己仓库的可见性（私有/公开）自行判断，插件不会自动探测。

💡 如果你的场景需要跨仓库拉取代码，或指定特定分支/Tag/Commit，checkout 插件本身支持更丰富的参数（repository、ref、fetch-depth、submodules、lfs 等），可查阅插件市场中的官方帮助文档，本指南不做展开。

3.5 语言环境准备（如 setup-jdk）

不同编程语言在执行 CodeQL 扫描前，可能需要先准备好对应的编译/运行环境。例如 Java 项目需要 JDK 及 Maven/Gradle：

- name: setup-jdk
  uses: setup-jdk
  with:
    jdk-version: 21
    maven-version: "3.8.9"

⚠️ 注意：示例中的 jdk-version: 21、maven-version: '3.8.9' 等版本号仅为演示用途，请根据自己代码仓库实际所需的语言/构建工具版本填写，不要直接照抄示例中的数字。版本不匹配可能导致 autobuild / manual 构建失败，进而影响 CodeQL 分析结果的准确性。

这一步是否需要、需要哪个 setup 插件，取决于所选语言以及 build-mode（详见 3.6）。具体各语言的推荐配置，请参考 第4章 常用语言配置示例。

3.6 codeql-action：执行 CodeQL 扫描

整个工作流的核心步骤，负责安装 CodeQL 引擎并对代码进行安全扫描，GitCode 官方插件，示例如下，具体细节可查看该插件官方文档。

- name: codeql-analysis
  identifier: codeql
  uses: codeql-action
  with:
    language: "java"
    query-suite: security-and-quality
    report-path: ./codeql-report.md
    output-path: ./
    build-mode: autobuild
    ram: 4096
    threads: 0
    verbose: "true"

核心参数说明：

参数	必填	说明
language	是	要扫描的编程语言，支持 javascript(或js)、python、java、cpp、csharp、go、ruby、swift、kotlin。支持多语言，用逗号分隔，如 "java,javascript"
output-path	是	扫描结果输出目录。多语言场景下会在此目录下按语言分别生成 codeql-results-{语言}.sarif（如 codeql-results-java.sarif）
report-path	是	Markdown 格式扫描报告的保存路径
build-mode	否，默认 none	数据库构建模式，详见下方"构建模式选择"说明
query-suite	否，默认 security-extended	查询套件，可多选（逗号分隔），详见下方"查询套件说明"
min-severity	否，默认 note	最低告警级别过滤：note（全部显示）/ warning（仅 warning 及以上）/ error（仅 error）
ram	否	分析使用的内存上限（单位 MB），低于 2048MB 时将使用系统默认值
threads	否	分析使用的线程数，默认使用所有可用核心
verbose	否，默认 false	是否输出详细日志（含 autobuild 构建过程详情）
token	—	用于 CodeQL 引擎自身下载安装的凭据，一般无需手动配置，流水线会自动注入

⚠️ 注意区分本步骤的 token 与 checkout 步骤的 token：前者用于下载 CodeQL 分析引擎本体，后者用于拉取你的代码仓库，两者用途完全不同，互不影响。

构建模式（build-mode）选择：

语言类型	说明
JavaScript / Python / Ruby	解释型语言，无需构建，始终使用 none 模式，build-mode 设置对其不生效
Java / Kotlin / C++	支持 none（纯静态分析，速度快）和 autobuild（自动构建，分析更精确，需环境已安装对应构建工具）
C# / Go / Swift	必须使用 autobuild，需要运行环境中已安装对应编译工具链（.NET SDK / Go 编译器 / Swift 编译器），否则将跳过该语言扫描

一般建议：项目有完整构建配置且环境已安装工具时优先使用 autobuild，追求扫描速度或环境不具备构建条件时使用 none。

查询套件（query-suite）选择：

套件	说明
security-and-quality	覆盖常见漏洞及代码质量问题，误报率较低，推荐
security-extended（默认）	在 security-and-quality 基础上增加更多安全查询
security-experimental	包含最新的实验性规则，可能不稳定

三个套件支持逗号分隔多选组合使用，如 security-extended, security-experimental, security-and-quality。

📌 以上查询套件说明摘录自 codeql-action v1.1.0 插件官方文档。套件覆盖的具体规则范围可能随插件版本迭代而调整，如需了解某个漏洞类型当前是否被特定套件覆盖，请以插件市场中的最新官方文档为准（查看方式见 2.4 如何查看插件官方帮助文档）。

3.7 openlibing-upload-sarif：上传扫描结果

这是团队自研插件，负责将 CodeQL 扫描产出的 SARIF 结果文件上传至 OBS 对象存储，并调用发布在华为云 APIG 上的接口，将结果数据解析入库，最终在 openLiBing「开发管理 - 代码检查」模块中可视化展示。

- name: upload sarif to openlibing
  uses: openlibing-upload-sarif
  with:
    sarif_file: ./codeql-results-java.sarif
    obs_ak: ${{ secrets.OPENLIBING_OBS_AK }}
    obs_sk: ${{ secrets.OPENLIBING_OBS_SK }}
    apig_app_key: ${{ secrets.OPENLIBING_APIG_KEY }}
    apig_app_secret: ${{ secrets.OPENLIBING_APIG_SECRET }}
    category: "business"

参数说明：

参数	必填	说明
sarif_file	是	上一步 codeql-action 产出的 SARIF 文件路径。支持单个文件，也支持指定目录（自动扫描目录下所有 .sarif 文件，适用于多语言场景）
obs_ak / obs_sk	是	用于将 SARIF 文件上传至 OBS 对象存储的访问凭据
apig_app_key / apig_app_secret	见 2.2 节说明	用于调用 APIG 解析接口的签名凭据
category	否	扫描范围标识，详见下方说明

关于 category 参数：

用于区分同一仓库、同一分支下的多次独立扫描（例如按业务代码/测试代码拆分扫描，或对代码库的不同部分分别扫描）。

• 不填时，系统默认视为 default（代表未做范围区分的扫描）；
• 建议使用简洁、稳定的英文标识，如 business、test、full，且一旦确定后不建议随意更改——如需调整扫描范围的划分方式，需先清理历史数据再切换，否则可能导致同一问题在系统中重复出现；
• 如果预判这个仓库未来可能会拆分为多次独立扫描（比如后续要分别扫业务代码和测试代码），强烈建议现在就显式传入一个有意义的值，而不是依赖默认值 default——一旦开始拆分，所有历史使用默认值兜底的数据将需要人工迁移才能与新的划分方式对齐。

💡 补充说明：category 是在语言范围内生效的标识——也就是说，即使多语言场景下多个语言共用同一个 category，不同语言的扫描结果也是分开存储和更新的，不会互相覆盖或冲突。因此多语言配置时通常无需为每种语言单独设置不同的 category，一个统一的值即可。

多文件（目录模式）用法：

当上一步 codeql-action 配置了多语言扫描（如 language: "java,javascript"）时，会在 output-path 目录下生成多个 SARIF 文件。此时 sarif_file 可直接指定该目录，插件会自动扫描并逐一上传目录下所有 .sarif 文件：

- name: upload sarif to openlibing
  uses: openlibing-upload-sarif
  with:
    sarif_file: ./codeql-results/
    obs_ak: ${{ secrets.OPENLIBING_OBS_AK }}
    obs_sk: ${{ secrets.OPENLIBING_OBS_SK }}
    apig_app_key: ${{ secrets.OPENLIBING_APIG_KEY }}
    apig_app_secret: ${{ secrets.OPENLIBING_APIG_SECRET }}
    category: "full"

---

4. 常用语言配置示例

⚠️ 以下示例中的语言/构建工具版本号（如 JDK 版本、Go 版本等）仅供参考，请根据你项目实际使用的版本进行替换，不要直接照抄。

4.1 Java

完整示例见：demos/codeql-java.yml

4.2 C++

C++项目请根据实际项目配置构建命令。

完整示例见：demos/codeql-cpp.yml

4.3 Go

完整示例见：demos/codeql-go.yml

4.4 Python

完整示例见：demos/codeql-python.yml

4.5 JavaScript

完整示例见：demos/codeql-javascript.yml

---

5. 常见问题 FAQ

Q：工作流执行成功，但 openLiBing 平台看不到扫描结果，如何排查？

请按以下顺序排查：

1. 确认 openlibing-upload-sarif 步骤是否配置了 apig_app_key / apig_app_secret。若未配置，扫描结果只会上传至 OBS，不会进入 openLiBing 平台展示，这是预期行为，并非故障；
2. 若已配置，请查看 gitcode action 的openlibing-upload-sarif 回调日志是否有 WARN/失败信息，请带上日志信息联系openLiBing团队进行定位。

Q：当前版本是否支持多语言、多 category 配置？

支持。

1. codeql-action 支持通过 language: "java,javascript" 一次配置多语言扫描；
2. openlibing-upload-sarif 支持通过 category 参数区分同一仓库同一分支下的多次独立扫描。详见 3.6 与 3.7 节说明。

Q：日志报错："The VPC backend does not exist"

请优先检查配置的APIG的AK/SK是否正确。