# GitHub上传结果

将 SARIF 文件上传到 GitHub 代码扫描。

> \[!NOTE]
> 此内容描述了 CodeQL CLI 的最新版本。 有关此版本的详细信息，请参阅 <https://github.com/github/codeql-cli-binaries/releases> 。
>
> 若要查看早期版本中此命令可用选项的详细信息，请在终端中使用 <span style="white-space: nowrap;">`--help`</span> 选项运行命令。

## 概要

```shell copy
codeql github upload-results --sarif=<file> [--github-auth-stdin] [--github-url=<url>] [--repository=<repository-name>] [--ref=<ref>] [--commit=<commit>] [--checkout-path=<path>] <options>...
```

## Description

将 SARIF 文件上传到 GitHub 代码扫描。

请参阅：“[将 CodeQL 分析结果上传到GitHub](/zh/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github)”

必须设置 GitHub Apps 令牌或个人访问令牌。 为确保安全，最佳做法是设置 `--github-auth-stdin` 标志并通过标准输入将令牌传递给命令。
或者，可以设置 `GITHUB_TOKEN` 环境变量。

此令牌必须具有 `security_events` 范围。

## 选项

### 主要选项

#### `-s, --sarif=<file>`

```
          \[必选] 要使用的 SARIF 文件的路径。 这应该是 [codeql database analyze](/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze)（或 [codeql database interpret-results](/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-interpret-results)）的输出，其中 `--format sarif-latest` 面向到 github.com 的上传内容，或者是相应的 GitHub Enterprise Server 实例支持的格式标记（有关你的版本支持的 SARIF 版本，请参阅 [AUTOTITLE](/enterprise-server@latest/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)）。
```

#### `-r, --repository=<repository-name>`

用作上传终结点的 GitHub 存储库所有者和名称（例如 *github/octocat*）。 如果省略，CLI 将尝试从签出路径自动检测此项。

#### `-f, --ref=<ref>`

已分析的引用名称。 如果此引用是拉取请求合并提交，则使用 *refs/pull/1234/merge* 或 *refs/pull/1234/head*（取决于此提交对应的是 PR 的 HEAD 提交还是 MERGE 提交） 否则，应为分支：*refs/heads/branch-name*。 如果省略，CLI 将尝试从签出路径的当前分支（如果存在）自动填充此项。

#### `-c, --commit=<commit>`

已分析的提交的 SHA。 如果省略，CLI 将尝试从签出路径自动检测此项。

#### `-p, --checkout-path=<path>`

签出路径。 默认值为当前工作目录。

#### `--merge`

```
          \[高级] 允许指定多个 SARIF 文件，并在上传前将它们合并为单个文件。 此建议仅旨在实现后向兼容性。 对于新的分析，建议上传两个具有不同类别的独立 SARIF 文件。 此选项仅适用于 CodeQL 使用 SARIF 2.1.0 版（这是 CodeQL 使用的 SARIF 的默认版本）生成的 SARIF 文件。
```

#### `--no-wait-for-processing`

默认情况下，CLI 将等待 GitHub 处理 SARIF 文件最多 2 分钟，如果在处理分析结果的过程中出现任何错误，则返回非零退出代码。 你可以使用 `--wait-for-processing-timeout` 自定义 CLI 的等待时间，或使用 `--no-wait-for-processing` 禁用该功能。

#### `--wait-for-processing-timeout=<waitForProcessingTimeout>`

CLI 等待上传的 SARIF 文件由 GitHub 处理的最长时间（以秒为单位）。 默认值为 120 秒（2 分钟）。
仅当启用 `--wait-for-processing` 时，此选项才有效。

#### `--format=<fmt>`

选择输出格式。 选项包括：

```
          `text`
          _（默认）_：打印用于跟踪 SARIF 上传状态的 URL。

          `json`：打印 SARIF 上传 API 请求的响应正文。
```

另请参阅：“[适用于代码扫描的 REST API 终结点](/zh/rest/code-scanning/code-scanning)”

### 用于配置 SARIF 文件上传位置的选项。

#### `-a, --github-auth-stdin`

通过标准输入接受 GitHub Apps 令牌或个人访问令牌。

这会替代 GITHUB\_TOKEN 环境变量。

#### `-g, --github-url=<url>`

要使用的 GitHub 实例的 URL。 如果省略，CLI 将尝试从签出路径自动检测此项，如果这不可行，则默认为 <https://github.com/>

### 常用选项

#### `-h, --help`

显示此帮助文本。

#### `-J=<opt>`

```
          \[高级] 向运行命令的 JVM 提供选项。
```

（请注意，无法正确处理包含空格的选项。）

#### `-v, --verbose`

以增量方式增加输出的进度消息数。

#### `-q, --quiet`

以增量方式减少输出的进度消息数。

#### `--verbosity=<level>`

```
          \[高级] 明确将详细级别设置为 errors、warnings、progress、progress+、progress++、progress+++ 之一。 重写 `-v` 和 `-q`。
```

#### `--logdir=<dir>`

```
          \[高级] 将详细日志写入指定目录中的一个或多个文件，生成的文件名包含时间戳和正在运行的子命令名称。
```

（要使用可以完全控制的名称编写日志文件，请根据需要提供 `--log-to-stderr` 并重定向 stderr。）

#### `--common-caches=<dir>`

```
          \[高级] 控制磁盘上缓存数据的位置，这些数据将在 CLI 的多次运行之间保留，例如下载的 QL 包和编译的查询计划。 如果未明确设置，则默认为用户主目录中名为 `.codeql` 的目录；如果尚不存在，则会创建该目录。
```

自 `v2.15.2` 起可用。