{"meta":{"title":"将 CodeQL 分析结果上传到GitHub","intro":"可以使用  CodeQL CLI 将分析结果CodeQL上传到 GitHub 。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/code-security","title":"安全性和代码质量"},{"href":"/zh/enterprise-cloud@latest/code-security/tutorials","title":"Tutorials"},{"href":"/zh/enterprise-cloud@latest/code-security/tutorials/customize-code-scanning","title":"自定义代码扫描"},{"href":"/zh/enterprise-cloud@latest/code-security/tutorials/customize-code-scanning/upload-results","title":"上传结果"}],"documentType":"article"},"body":"# 将 CodeQL 分析结果上传到GitHub\n\n可以使用  CodeQL CLI 将分析结果CodeQL上传到 GitHub 。\n\n使用 CodeQL 分析 CodeQL CLI 数据库后，您将获得包含结果的 SARIF 文件。 然后，可以使用CodeQL CLI将结果上传到GitHub。\n\n如果使用了其他 CodeQL CLI 方法来生成结果，则可以使用其他上传方法。 有关详细信息，请参阅“[将 SARIF 文件上传到 GitHub](/zh/enterprise-cloud@latest/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file)”。\n\n## 使用GitHub生成用于身份验证的令牌\n\n在将您的结果上传到 GitHub 之前，您首先需要生成 personal access token。 请参阅“[管理个人访问令牌](/zh/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)”。\n\n* **Personal access token (classic)** 需要所需存储库的“Code scanning 警报”**读取和写入**访问权限。\n* **Fine-grained personal access token** 需要“存储库”**security\\_events** 访问权限。\n\n如果已在第三方 CI 系统中安装CodeQL CLI，那么您也可以使用GitHub App将结果上传到GitHub。 请参阅“[在现有 CI 系统上使用代码扫描](/zh/enterprise-cloud@latest/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)”。\n\n## 将结果上传到 GitHub\n\n1. 检查 SARIF 属性是否具有上传支持的大小，以及该文件是否与代码扫描兼容。 有关详细信息，请参阅“[对代码扫描的 SARIF 支持](/zh/enterprise-cloud@latest/code-security/reference/code-scanning/sarif-files/sarif-support#file-compatibility)”。\n\n2. 确定将上一节中创建的 GitHub App 或 personal access token 最佳方式传递给 CodeQL CLI。 建议查看 CI 系统有关安全使用机密存储的指南。\n   CodeQL CLI 支持：\n\n   * 使用 `--github-auth-stdin` 选项（建议）与机密存储库进行交互。\n   * 将机密保存在环境变量 `GITHUB_TOKEN` 中，并在不包含 `--github-auth-stdin` 选项的情况下运行 CLI。\n   * 出于测试目的，可以传递 `--github-auth-stdin` 命令行选项，并通过标准输入提供临时令牌。\n\n3. 为配置确定最安全可靠的方法后，请在每个 SARIF 结果文件上运行 `codeql github upload-results` 并包含 `--github-auth-stdin`，除非该令牌在环境变量 `GITHUB_TOKEN` 中可用。\n\n   ```shell\n   # GitHub App or personal access token available from a secret store\n   <call-to-retrieve-secret> | codeql github upload-results \\\n       --repository=<repository-name> \\\n       --ref=<ref> --commit=<commit> \\\n       --sarif=<file> --github-auth-stdin\n\n   # GitHub App or personal access token available in GITHUB_TOKEN\n   codeql github upload-results \\\n       --repository=<repository-name> \\\n       --ref=<ref> --commit=<commit> \\\n       --sarif=<file> \n   ```\n\n| 选项                                                                         |                                                                                                                                                                                                               必需                                                                                                                                                                                                               | Usage                                                                                                                                                                                                                                                                                                                        |\n| -------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| <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/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)”。 |\n| <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`。                                                                                                                                                                 |\n| <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。                                                                                                                                                                                                                                                                                                              |\n| <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 文件。                                                                                                                                                                                                                                                                                                             |\n|                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                              |\n| <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` 环境变量，则不需要执行此操作。                                                                                                                                                                                  |\n\n有关详细信息，请参阅“[GitHub上传结果](/zh/enterprise-cloud@latest/code-security/reference/code-scanning/codeql/codeql-cli-manual/github-upload-results)”。\n\n> \\[!NOTE]\n> 如果为单个提交分析多个 CodeQL 数据库，则必须为由此命令生成的每个结果集指定一个 SARIF 类别。 将结果 GitHub上传到后， code scanning 使用此类别单独存储每种语言的结果。 如果忘记执行此操作，则每次上传都会覆盖之前的结果。 有关详细信息，请参阅“[使用 CodeQL 查询分析代码](/zh/enterprise-cloud@latest/code-security/tutorials/customize-code-scanning/analyze-code#running-codeql-database-analyze)”。\n\n### 将结果上传到GitHub的基本示例\n\n下面的示例将结果从 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`环境变量。\n\n```shell\ncodeql github upload-results \\\n    --repository=my-org/example-repo \\\n    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \\\n    --sarif=/temp/example-repo-js.sarif \n```\n\n除非上传未成功，否则此命令不会输出。 上传完成并开始数据处理时，命令提示返回。 在较小的代码库中，稍后应该能够在 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 and quality** 选项卡上查看警报，具体取决于已签出的代码。\n\n## 在分析失败时，将诊断信息上传到GitHub\n\n当CodeQL CLI成功分析一个数据库后，它会收集诊断信息，例如文件覆盖、警告和错误，并将其包含在带有结果的SARIF文件中。 将 SARIF 文件上传到 GitHub 后，诊断信息会显示在存储库的 code scanning工具状态页 上，以便轻松查看 CodeQL 的运行情况并调试任何问题。 有关详细信息，请参阅“[使用工具状态页进行代码扫描](/zh/enterprise-cloud@latest/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning)”。\n\n如果 `codeql database analyze` 因任何原因失败，则没有 SARIF 文件可以上传到 GitHub，也没有诊断信息可以显示在存储库的 code scanning工具状态页 上。 这使得用户难以对分析进行故障排除，除非他们有权访问你的 CI 系统中的日志文件。\n\n建议将 CI 工作流配置为在分析失败时导出诊断信息 GitHub 并将其上传到该工作流。 可以使用下面的简单命令执行此操作，以导出诊断信息并将其上传到 GitHub。\n\n### 如果分析失败，则导出诊断信息\n\n可以使用 [database export-diagnostics](/zh/enterprise-cloud@latest/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-export-diagnostics) 为失败的分析创建 SARIF 文件，例如：\n\n```shell\n$ codeql database export-diagnostics codeql-dbs/example-repo \\\n    --sarif-category=javascript-typescript --format=sarif-latest \\\n    --output=/temp/example-repo-js.sarif\n```\n\n此 SARIF 文件将包含失败分析的诊断信息，其中包括分析期间生成的任何文件覆盖率信息、警告和错误。\n\n### 如果分析失败，则上传诊断信息\n\n可以通过使用工具状态页将GitHub上传到[](/zh/enterprise-cloud@latest/code-security/reference/code-scanning/codeql/codeql-cli-manual/github-upload-results)，来提供此诊断信息，例如：\n\n```shell\ncodeql github upload-results \\\n    --repository=my-org/example-repo \\\n    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \\\n    --sarif=/temp/example-repo-js.sarif \n```\n\n这与从成功分析上传 SARIF 文件的过程相同。"}