# 将 CodeQL 分析结果上传到GitHub

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

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

如果使用了其他 CodeQL CLI 方法来生成结果，则可以使用其他上传方法。 有关详细信息，请参阅“[将 SARIF 文件上传到 GitHub](/zh/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)”。

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

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

***

```
          Personal access token (classic)
          **需要对所需存储库具有“警报”Code scanning**读取和写入**访问权限。
```

***

```
          Fine-grained personal access token
          ** 需要“存储库” **security_events** 访问。
```

如果已在第三方 CI 系统中安装CodeQL CLI，那么您也可以使用GitHub App将结果上传到GitHub。 请参阅“[在现有 CI 系统上使用代码扫描](/zh/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system#generating-a-token-for-authentication-with-github)”。

## 将结果上传到 GitHub

1. 检查 SARIF 属性是否具有上传支持的大小，以及该文件是否与代码扫描兼容。 有关详细信息，请参阅“[对代码扫描的 SARIF 支持](/zh/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#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-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> 
   ```

| 选项                                                                         |                                                                                                                                                                                                               必选                                                                                                                                                                                                               | 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 Team否则所有者必须是GitHub Code Security企业内部或计划中启用了存储库的组织。 有关详细信息，请参阅“[管理存储库的安全和分析设置](/zh/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-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> | 使用标准输入将从机密存储中生成的用于认证的GitHub App或personal access token传递到GitHub的REST API进行身份验证。 如果命令有权访问使用此令牌设置的 `GITHUB_TOKEN` 环境变量，则不需要执行此操作。                                                                                                                                                             |

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

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

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

下面的示例将结果从 SARIF 文件 `temp/example-repo-js.sarif` 上传到存储库 `my-org/example-repo`。 它告知code scanning API，该结果是针对`main`分支上的`deb275d2d5fe9a522a0b7bd8b6b6a1c939552718`提交。 该示例假定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 
```

除非上传未成功，否则此命令不会输出。 上传完成并开始数据处理时，命令提示返回。 在较小的代码库中，你应该可以立即浏览 code scanning 警报 GitHub 。 可以直接在拉取请求（Pull Request）或 **<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 and quality** 分支选项卡上查看警报，具体取决于您签出的代码。

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

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

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

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

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

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

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

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

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

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

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

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