# 将 CodeQL 分析结果上传到GitHub

可以使用  CodeQL CLI 将分析结果CodeQL上传到 GitHub 。

使用 CodeQL 分析 CodeQL CLI 数据库后，您将获得包含结果的 SARIF 文件。 然后，可以使用CodeQL CLI将结果上传到GitHub。

如果使用了其他 CodeQL CLI 方法来生成结果，则可以使用其他上传方法。 有关详细信息，请参阅“[将 SARIF 文件上传到 GitHub](/zh/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file)”。

## 使用GitHub生成用于身份验证的令牌

在将您的结果上传到 GitHub 之前，您首先需要生成 personal access token。 请参阅“[管理个人访问令牌](/zh/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)”。

* **Personal access token (classic)** 需要所需存储库的“Code scanning 警报”**读取和写入**访问权限。
* **Fine-grained personal access token** 需要“存储库”**security\_events** 访问权限。

如果已在第三方 CI 系统中安装CodeQL CLI，那么您也可以使用GitHub App将结果上传到GitHub。 请参阅“[在现有 CI 系统上使用代码扫描](/zh/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/use-with-existing-ci-system#generating-a-token-for-authentication-with-github)”。

## 将结果上传到 GitHub

1. 检查 SARIF 属性是否具有上传支持的大小，以及该文件是否与代码扫描兼容。 有关详细信息，请参阅“[对代码扫描的 SARIF 支持](/zh/enterprise-server@3.22/code-security/reference/code-scanning/sarif-files/sarif-support#file-compatibility)”。

2. 确定将上一节中创建的 GitHub App 或 personal access token 最佳方式传递给 CodeQL CLI。 建议查看 CI 系统有关安全使用机密存储的指南。
   CodeQL CLI 支持：

   * 使用 `--github-auth-stdin` 选项（建议）与机密存储库进行交互。
   * 将机密保存在环境变量 `GITHUB_TOKEN` 中，并在不包含 `--github-auth-stdin` 选项的情况下运行 CLI。
   * 出于测试目的，可以传递 `--github-auth-stdin` 命令行选项，并通过标准输入提供临时令牌。

3. 为配置确定最安全可靠的方法后，请在每个 SARIF 结果文件上运行 `codeql github upload-results` 并包含 `--github-auth-stdin`，除非该令牌在环境变量 `GITHUB_TOKEN` 中可用。

   ```shell
   # GitHub App or personal access token available from a secret store
   <call-to-retrieve-secret> | codeql github upload-results \
       --repository=<repository-name> \
       --ref=<ref> --commit=<commit> \
       --sarif=<file> --github-url=<URL> \
       --github-auth-stdin

   # GitHub App or personal access token available in GITHUB_TOKEN
   codeql github upload-results \
       --repository=<repository-name> \
       --ref=<ref> --commit=<commit> \
       --sarif=<file> --github-url=<URL> \
       
   ```

| 选项                                                                         |                                                                                                                                                                                                               必需                                                                                                                                                                                                               | Usage                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <code><span style="white-space: nowrap;">--repository</span></code>        |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | 指定要将数据上传到的存储库的所有者/名称。 所有者必须为组织，并且为仓库启用了 GitHub Code Security。 有关详细信息，请参阅“[管理存储库的安全和分析设置](/zh/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)”。 |
| <code><span style="white-space: nowrap;">--ref</span></code>               |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | 指定你签出和分析的 `ref` 的名称，以便使结果与正确的代码匹配。 对于分支，使用 `refs/heads/BRANCH-NAME`；对于拉取请求的头提交，使用 `refs/pull/NUMBER/head`；对于 GitHub 生成的拉取请求合并提交，使用 `refs/pull/NUMBER/merge`。                                                                                                                          |
| <code><span style="white-space: nowrap;">--commit</span></code>            |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | 指定分析的提交的完整 SHA。                                                                                                                                                                                                                                                                       |
| <code><span style="white-space: nowrap;">--sarif</span></code>             |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | 指定要加载的 SARIF 文件。                                                                                                                                                                                                                                                                      |
|                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                       |
| <code><span style="white-space: nowrap;">--github-url</span></code>        |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | 指定 你的 GitHub Enterprise Server 实例 的 URL。                                                                                                                                                                                                                                              |
|                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                       |
| <code><span style="white-space: nowrap;">--github-auth-stdin</span></code> | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-x" aria-label="Optional" role="img"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"></path></svg> | 将 CLI 传递给你从机密存储通过标准输入创建的、用于通过 GitHub App 的 REST API 进行身份验证的 personal access token 或 GitHub。 如果命令有权访问使用此令牌设置的 `GITHUB_TOKEN` 环境变量，则不需要执行此操作。                                                                                                                                           |

有关详细信息，请参阅“[GitHub上传结果](/zh/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/github-upload-results)”。

> \[!NOTE]
> 如果为单个提交分析多个 CodeQL 数据库，则必须为由此命令生成的每个结果集指定一个 SARIF 类别。 将结果 GitHub上传到后， code scanning 使用此类别单独存储每种语言的结果。 如果忘记执行此操作，则每次上传都会覆盖之前的结果。 有关详细信息，请参阅“[使用 CodeQL 查询分析代码](/zh/enterprise-server@3.22/code-security/tutorials/customize-code-scanning/analyze-code#running-codeql-database-analyze)”。

### 将结果上传到GitHub的基本示例

下面的示例将结果从 SARIF 文件 `temp/example-repo-js.sarif` 上传到存储库 `my-org/example-repo`。 它告知 code scanning API，结果对应 `deb275d2d5fe9a522a0b7bd8b6b6a1c939552718` 分支上的提交 `main`。 该示例假定GitHub App或personal access token是为使用GitHub的REST API身份验证而创建，并使用`GITHUB_TOKEN`环境变量。

```shell
codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-url=https://HOSTNAME \
    
```

除非上传未成功，否则此命令不会输出。 上传完成并开始数据处理时，命令提示返回。 在较小的代码库中，稍后应该能够在 code scanning 中浏览 GitHub 警报。 可以直接在拉取请求中或分支的 **<svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-shield" aria-label="shield" role="img"><path d="M7.467.133a1.748 1.748 0 0 1 1.066 0l5.25 1.68A1.75 1.75 0 0 1 15 3.48V7c0 1.566-.32 3.182-1.303 4.682-.983 1.498-2.585 2.813-5.032 3.855a1.697 1.697 0 0 1-1.33 0c-2.447-1.042-4.049-2.357-5.032-3.855C1.32 10.182 1 8.566 1 7V3.48a1.75 1.75 0 0 1 1.217-1.667Zm.61 1.429a.25.25 0 0 0-.153 0l-5.25 1.68a.25.25 0 0 0-.174.238V7c0 1.358.275 2.666 1.057 3.86.784 1.194 2.121 2.34 4.366 3.297a.196.196 0 0 0 .154 0c2.245-.956 3.582-2.104 4.366-3.298C13.225 9.666 13.5 8.36 13.5 7V3.48a.251.251 0 0 0-.174-.237l-5.25-1.68ZM8.75 4.75v3a.75.75 0 0 1-1.5 0v-3a.75.75 0 0 1 1.5 0ZM9 10.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg> Security** 选项卡上查看警报，具体取决于已签出的代码。

## 在分析失败时，将诊断信息上传到GitHub

当CodeQL CLI成功分析一个数据库后，它会收集诊断信息，例如文件覆盖、警告和错误，并将其包含在带有结果的SARIF文件中。 将 SARIF 文件上传到 GitHub 后，诊断信息会显示在存储库的 code scanning工具状态页 上，以便轻松查看 CodeQL 的运行情况并调试任何问题。 有关详细信息，请参阅“[使用工具状态页进行代码扫描](/zh/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning)”。

如果 `codeql database analyze` 因任何原因失败，则没有 SARIF 文件可以上传到 GitHub，也没有诊断信息可以显示在存储库的 code scanning工具状态页 上。 这使得用户难以对分析进行故障排除，除非他们有权访问你的 CI 系统中的日志文件。

建议将 CI 工作流配置为在分析失败时导出诊断信息 GitHub 并将其上传到该工作流。 可以使用下面的简单命令执行此操作，以导出诊断信息并将其上传到 GitHub。

### 如果分析失败，则导出诊断信息

可以使用 [database export-diagnostics](/zh/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-export-diagnostics) 为失败的分析创建 SARIF 文件，例如：

```shell
$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript-typescript --format=sarifv2.1.0 \
    --output=/temp/example-repo-js.sarif
```

此 SARIF 文件将包含失败分析的诊断信息，其中包括分析期间生成的任何文件覆盖率信息、警告和错误。

### 如果分析失败，则上传诊断信息

可以通过使用工具状态页将GitHub上传到[](/zh/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/github-upload-results)，来提供此诊断信息，例如：

```shell
codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-url=https://HOSTNAME \
    
```

这与从成功分析上传 SARIF 文件的过程相同。