{"meta":{"title":"将 CodeQL 分析结果上传到GitHub","intro":"可以使用 CodeQL CLI 将分析结果CodeQL上传到 GitHub 。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/code-security","title":"安全性和代码质量"},{"href":"/zh/code-security/tutorials","title":"Tutorials"},{"href":"/zh/code-security/tutorials/customize-code-scanning","title":"自定义代码扫描"},{"href":"/zh/code-security/tutorials/customize-code-scanning/uploading-codeql-analysis-results-to-github","title":"将结果上传到GitHub"}],"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/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)”。\n\n## 使用GitHub生成用于身份验证的令牌\n\n在将您的结果上传到 GitHub 之前，您首先需要生成 personal access token。 请参阅“[管理个人访问令牌](/zh/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)”。\n\n***\n\n```\n Personal access token (classic)\n **需要对所需存储库具有“警报”Code scanning**读取和写入**访问权限。\n```\n\n***\n\n```\n Fine-grained personal access token\n ** 需要“存储库” **security_events** 访问。\n```\n\n如果已在第三方 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)”。\n\n## 将结果上传到 GitHub\n\n1. 检查 SARIF 属性是否具有上传支持的大小，以及该文件是否与代码扫描兼容。 有关详细信息，请参阅“[对代码扫描的 SARIF 支持](/zh/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#file-compatibility)”。\n\n2. 确定将上一节中创建的 GitHub App 或 personal access token 最佳方式传递给 CodeQL CLI。 建议查看 CI 系统有关安全使用机密存储的指南。 支持 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 | codeql github upload-results \\\n --repository= \\\n --ref= --commit= \\\n --sarif= --github-auth-stdin\n\n # GitHub App or personal access token available in GITHUB_TOKEN\n codeql github upload-results \\\n --repository= \\\n --ref= --commit= \\\n --sarif= \n ```\n\n| 选项 | 必选 | Usage |\n| -------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| --repository | | 指定要将数据上传到的存储库的所有者/名称。 除非存储库是公共的，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)”。 |\n| --ref | | 指定你签出和分析的 `ref` 的名称，以便使结果与正确的代码匹配。 对于分支使用：使用 `refs/heads/BRANCH-NAME`。对于拉取请求的头提交，使用 `refs/pull/NUMBER/head`。或对于拉取请求中由GitHub生成的合并提交，使用 `refs/pull/NUMBER/merge`。 |\n| --commit | | 指定分析的提交的完整 SHA。 |\n| --sarif | | 指定要加载的 SARIF 文件。 |\n| | | |\n| --github-auth-stdin | | 使用标准输入将从机密存储中生成的用于认证的GitHub App或personal access token传递到GitHub的REST API进行身份验证。 如果命令有权访问使用此令牌设置的 `GITHUB_TOKEN` 环境变量，则不需要执行此操作。 |\n\n有关详细信息，请参阅“[GitHub上传结果](/zh/code-security/codeql-cli/codeql-cli-manual/github-upload-results)”。\n\n> \\[!NOTE]\n> 如果为单个提交分析多个 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)”。\n\n### 将结果上传到GitHub的基本示例\n\n下面的示例将结果从 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`环境变量。\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 。 可以直接在拉取请求（Pull Request）或 ** Security and quality** 分支选项卡上查看警报，具体取决于您签出的代码。\n\n## 在分析失败时，将诊断信息上传到GitHub\n\n当CodeQL CLI成功分析一个数据库后，它会收集诊断信息，例如文件覆盖、警告和错误，并将其包含在带有结果的SARIF文件中。 将 SARIF 文件上传到 GitHub 后，诊断信息会在 code scanning工具状态页 上显示，以便轻松查看 CodeQL 的工作情况并调试任何问题。 有关详细信息，请参阅“[使用工具状态页进行代码扫描](/zh/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page)”。\n\n如果 `codeql database analyze` 因任何原因失败，则没有 SARIF 文件可以上传到 GitHub，也没有诊断信息可以显示在存储库的 code scanning工具状态页 上。 这使得用户难以对分析进行故障排除，除非他们有权访问你的 CI 系统中的日志文件。\n\n建议将 CI 工作流配置为在分析失败时导出诊断信息 GitHub 并将其上传到该工作流。 可以使用下面的简单命令执行此操作，以导出诊断信息并将其上传到 GitHub。\n\n### 如果分析失败，则导出诊断信息\n\n可以使用 [database export-diagnostics](/zh/code-security/codeql-cli/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/code-security/codeql-cli/codeql-cli-manual/github-upload-results)将工具状态页上传到GitHub，来提供此诊断信息，例如：\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 文件的过程相同。"}