SonarQube 与 GitHub Enterprise 和 GitHub.com 的集成使您可以维护 GitHub 存储库中的代码质量和安全性

SonarQube 与 GitHub Enterprise 和 GitHub.com 的集成使您可以维护 GitHub 存储库中的代码质量和安全性。

通过这种集成，您将能够：

• 导入 GitHub 存储库：将 GitHub 存储库导入 SonarQube 以轻松设置 SonarQube 项目。

• 使用 GitHub Actions 分析项目：将分析集成到您的构建管道中。从 Developer Edition开始，在 GitHub Actions 作业中运行的 SonarScanner 可以自动检测正在构建的分支或拉取请求，因此您无需专门将它们作为参数传递给扫描器。

• 向您的分支报告您的质量门状态并拉取请求：（从 Developer Edition开始）直接在 GitHub 中查看您的质量门和代码指标结果，以便您知道合并更改是否安全。

• 使用 GitHub 进行身份验证：使用您的 GitHub 凭据登录到 SonarQube。

• 在 GitHub 中显示漏洞问题的代码扫描警报：在 GitHub 界面中将 SonarQube 发现的安全漏洞问题显示为代码扫描警报。

先决条件

• 如果您使用的是 GitHub Enterprise，我们建议使用 GitHub Enterprise 版本 3.4+。

• 您已在 Administration  >  Configuration  >  General Settings > General中设置了 SonarQube Server 基本 URL。

分支分析

Community Edition 不支持多个分支的分析，因此您只能分析您的主分支。使用 Developer Edition，您可以分析多个分支和拉取请求。

将 GitHub 存储库导入 SonarQube

您需要使用 GitHub 应用程序将 SonarQube 与 GitHub 连接，并将 GitHub 存储库导入 SonarQube。这也是添加身份验证的第一步，并且从 Developer Edition开始，也是向拉取请求报告分析和质量门状态的第一步。

如果您想在不导入 GitHub 存储库的情况下设置身份验证，请参阅Github 身份验证 以获取有关设置身份验证的说明。

在本部分中，您将完成以下步骤以使用 GitHub 应用程序连接 SonarQube 和 GitHub：

1. 创建您的 GitHub 应用程序。

2. 在您的组织中安装 GitHub 应用程序。

3. 使用 GitHub 应用程序信息更新您的 SonarQube 全局设置。

第 1 步：创建 GitHub 应用程序

 有关创建应用程序的一般信息，请参阅 GitHub 有关 创建GitHub应用程序的文档。

在您的应用程序中指定以下设置：

• GitHub 应用程序名称：您的应用程序的名称。

• 主页 URL：您可以使用任何 URL，例如 https://www.sonarqube.org/。

• 用户授权回调 URL：您的实例的基本 URL。例如，  。请注意，要使其发挥作用，您的 SonarQube 实例必须可通过公共 URL 访问。http://sonarqube.yourcompany.com

• Webhook URL：为了提高安全性，自版本 8.9LTS 以来，默认情况下不允许 Webhook 指向 SonarQube 服务器，因此我们建议您禁用该功能。除非您想在 GitHub 中启用针对安全漏洞的代码扫描警报，否则您应该清除 Webhook Active 复选框以消除即将出现的弃用警告，并  在创建 GitHub 应用程序时清除Webhook URL 和 Webhook 秘密字段。

• 授予以下 存储库权限： 

• 对于私有存储库，授予对以下 存储库权限的访问权限： 

• 如果设置 GitHub 身份验证，除了上述存储库权限之外，还授予以下 帐户权限： 

• 并授予以下 组织权限：

• 在“这个 GitHub 应用程序可以安装在哪里？”下，选择 任何帐户。

步骤 2：在您的组织中安装 GitHub 应用程序

接下来，您需要在您的组织中安装 GitHub 应用程序。 有关更多信息，请参阅 GitHub 有关 安装 GitHub 应用程序的文档。

步骤 3：使用 GitHub 应用程序信息更新您的 SonarQube 全局设置

创建并安装 GitHub 应用程序后，更新全局 SonarQube 设置以完成集成并允许导入 GitHub 项目。

导航到 管理>配置>常规设置> DevOps 平台集成> GitHub 并指定以下设置：

• 配置名称 （仅限企业版和数据中心版）：用于在项目级别标识 GitHub 配置的名称。使用简洁且易于识别的内容。

• GitHub URL：例如， https://github.company.com/api/v3 对于 GitHub Enterprise 或 https://api.github.com/ GitHub.com。

• GitHub 应用程序 ID：应用程序 ID 可在 GitHub 上的 GitHub 应用程序页面上找到，位置为 设置>开发人员设置> GitHub 应用程序。

• 客户端 ID：客户端 ID 可在您的 GitHub 应用程序页面上找到。

• 客户端密钥：客户端密钥可在您的 GitHub 应用程序页面上找到。管理员可以在Administration > Configuration > Encryption中加密此机密 。 有关详细信息，请参阅 “安全”页面 的 “设置加密”部分。

• 私钥：您的 GitHub 应用程序的 PEM 格式的私钥。您可以 .pem 从 GitHub 应用程序页面的 私钥下生成文件。将文件的全部内容复制并粘贴到此处。管理员可以在管理>配置>加密中加密该密钥 。 有关详细信息， 请参阅 “安全”页面 的 “设置加密”部分。

使用 GitHub Actions 分析项目

在 GitHub Actions 中运行的 SonarScanner 可以自动检测正在构建的分支和拉取请求，因此您无需专门将它们作为参数传递给扫描器。

要使用 GitHub Actions 分析您的项目，您需要：

• 创建您的 GitHub Secret。

• 配置您的工作流程 YAML 文件。

• 提交并推送您的代码以开始分析。

创建您的 GitHub 机密

您可以从 GitHub 存储库创建存储库机密。 有关更多信息，请参阅 GitHub 有关 加密机密的文档。

您需要设置以下 GitHub 存储库机密才能使用 GitHub Actions 分析您的项目：

• Sonar Token：生成 SonarQube 令牌 ，并在 GitHub 中创建一个新的存储库密钥，名称为 SONAR_TOKEN Name  ， 生成的令牌为 Value。

• Sonar Host URL：在 GitHub 中，创建一个新的存储库密钥，名称 SONAR_HOST_URL 为 Name  ，SonarQube 服务器 URL 为 Value。

配置您的 .github/workflows/build.yml 文件

本节向您展示如何配置 .github/workflows/build.yml 文件。

您将根据您的 SonarQube 版本设置您的构建：

• 社区版：社区版不支持多个分支，因此您应该只分析您的主分支。on.push.branches 您可以将分析限制在主分支上，方法是将其设置为工作流 YAML 文件中配置 中的唯一分支 ，而不是使用on.pull_request.

• 开发版及以上版本on.push.branches：如果您使用 和 on.pull-requests 配置如下例所示，GitHub Actions 可以构建特定分支和拉取请求 。

单击下面您正在使用的扫描仪以展开示例配置：

plugins {  id "org.sonarqube" version "3.5.0.2730"}

name: Buildon:
  push:
    branches:
      - main # the name of your main branch
  pull_request:
    types: [opened, synchronize, reopened]jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: Set up JDK 17
        uses: actions/setup-java@v1
        with:
          java-version: 17
      - name: Cache SonarQube packages
        uses: actions/cache@v1
        with:
          path: ~/.sonar/cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar
      - name: Cache Gradle packages
        uses: actions/cache@v1
        with:
          path: ~/.gradle/caches
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}
          restore-keys: ${{ runner.os }}-gradle
      - name: Build and analyze
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: ./gradlew build sonar --info

name: Buildon:
  push:
    branches:
      - main # the name of your main branch
  pull_request:
    types: [opened, synchronize, reopened]jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: Set up JDK 17
        uses: actions/setup-java@v1
        with:
          java-version: 17
      - name: Cache SonarQube packages
        uses: actions/cache@v1
        with:
          path: ~/.sonar/cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar
      - name: Cache Maven packages
        uses: actions/cache@v1
        with:
          path: ~/.m2
          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
          restore-keys: ${{ runner.os }}-m2
      - name: Build and analyze
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar

name: Buildon:
  push:
    branches:
      - main # the name of your main branch
  pull_request:
    types: [opened, synchronize, reopened]jobs:
  build:
    name: Build
    runs-on: windows-latest
    steps:
      - name: Set up JDK 17
        uses: actions/setup-java@v1
        with:
          java-version: 1.17
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: Cache SonarQube packages
        uses: actions/cache@v1
        with:
          path: ~\.sonar\cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar
      - name: Cache SonarQube scanner
        id: cache-sonar-scanner
        uses: actions/cache@v1
        with:
          path: .\.sonar\scanner
          key: ${{ runner.os }}-sonar-scanner
          restore-keys: ${{ runner.os }}-sonar-scanner
      - name: Install SonarQube scanner
        if: steps.cache-sonar-scanner.outputs.cache-hit != 'true'
        shell: powershell
        run: |
          New-Item -Path .\.sonar\scanner -ItemType Directory
          dotnet tool update dotnet-sonarscanner --tool-path .\.sonar\scanner      - name: Build and analyze
        shell: powershell
        run: |
          .\.sonar\scanner\dotnet-sonarscanner begin /k:"example" /d:sonar.token="${{ secrets.SONAR_TOKEN }}" /d:sonar.host.url="${{ secrets.SONAR_HOST_URL }}"
          dotnet build
          .\.sonar\scanner\dotnet-sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"

当质量门失败时管道作业失败

您可以使用 SonarQube 质量门检查 GitHub Action，在质量门失败 时使管道作业失败，以确保您的代码符合质量标准  。

如果您不想使用 SonarQube 质量门检查操作，您可以指示扫描仪在分析结束时等待 SonarQube 质量门状态。要启用此功能，请将 -Dsonar.qualitygate.wait=true 参数传递到工作流 YAML 文件中的扫描器。

这将使分析步骤定期轮询 SonarQube，直到计算出质量门。这将增加您的管道持续时间。请注意，如果质量门为红色，这将使分析步骤失败，即使实际分析本身是成功的。我们建议仅在必要时使用此参数（例如，如果质量门为红色，则阻止部署管道）。它不应该用于报告拉取请求中的质量门状态，因为这已经通过拉取请求装饰完成了。

您可以将该 sonar.qualitygate.timeout 属性设置为扫描仪等待处理报告的时间（以秒为单位）。默认值为 300 秒。

提交并推送您的代码

提交并推送您的代码以开始分析。您在分支上进行的每个新推送或拉取请求都将触发 SonarQube 中的新分析。

在 GitHub 中报告您的质量门状态

在上面创建并安装 GitHub 应用程序后，SonarQube 可以将您的质量门状态和分析指标直接报告给您的 GitHub 分支和拉取请求。

为此，请通过执行以下操作之一从 GitHub 添加项目：

• 在项目概述页面上，选择添加项目 > GitHub，然后按照 SonarQube 中的步骤分析您的项目。 

• 从 GitHub 操作扫描项目。SonarQube 将找到匹配的 GitHub 配置。

SonarQube 自动设置在分支和拉取请求中显示质量门所需的项目设置。

如果您手动创建项目或将质量门报告添加到现有项目，请参阅以下部分。

报告手动创建或现有项目中的质量门状态

SonarQube 还可以向现有和手动创建的项目的 GitHub 拉取请求和分支报告您的质量门状态。创建并安装 GitHub 应用程序并更新全局 DevOps 平台集成设置（如 上面将 GitHub 存储库导入 SonarQube部分所示）后，请在Project Settings > General Settings > DevOps Platform Integration 中设置以下项目设置 ：

• 配置名称：与您的 GitHub 实例对应的配置名称。

• 存储库标识符：存储库 URL 的路径。

高级配置

当质量门失败时防止拉取请求合并

在 GitHub 中，如果拉取请求未通过质量门，您可以阻止合并拉取请求。去做这个：

1. 在 GitHub 中，转到存储库设置>分支>分支保护规则，如果您希望保护的分支已有规则，请选择添加规则或编辑按钮。

2. 填写分支机构保护规则表：

• 定义分支名称模式（您要保护的分支的名称）

• 选择合并之前需要通过状态检查以打开补充表单字段。

• 在“搜索该存储库上周的状态检查”字段中，选择“合并前要求分支保持最新”，然后查找SonarQube Code Analysis 并将其添加到所需检查列表中。

使用 GitHub 进行身份验证

有关 GitHub 中身份验证设置的更多详细信息， 请参阅使用 GitHub 进行身份验证。

GitHub 代码扫描安全漏洞警报

从 Developer Edition 开始，SonarQube 可以提供有关 GitHub 界面本身内部安全漏洞的反馈。SonarQube发现的安全漏洞会出现在以下两个方面：

• SonarQube 界面，作为显示分析结果的一部分。

• GitHub 界面，作为 “安全” 选项卡下的代码扫描警报。

注意：此功能是GitHub 高级安全包的一部分  ，目前对公共项目免费。它可作为私人项目和 GitHub Enterprise 的付费选项。这个选项完全在 GitHub 这边。Sonar 不会收取任何额外费用来启用代码扫描警报功能。

在配置针对漏洞问题的 GitHub 代码扫描警报之前，必须首先将 GitHub 存储库导入到 SonarQube，如上所述。

启用此功能后，您必须运行 SonarQube 分析，以将安全漏洞视为 GitHub 代码扫描警报。

配置 GitHub

1. 转到 设置>开发者设置> GitHub 应用程序 ，然后选择您的 GitHub 应用程序。

2. 转到 常规> Webhook 部分，并确保选中 活动 复选框。

3. 添加以下 Webhook URL：  https://<yourinstance>.sonarqube.com/api/alm_integrations/webhook_github。替换 <yourinstance>.sonarqube.com 为您的 SonarQube 实例。

4. 设置 Webhook 机密 （请参阅 GitHub 的 webhook 安全建议）。

5. 在“权限和事件” > “存储库权限” > “代码扫描警报”下 ，将访问级别设置为 “读取”和“写入”。当您更新此权限时，GitHub 会向 GitHub 组织的管理员发送一封电子邮件，要求他们验证 GitHub 应用程序安装上的更改。

6. 在“权限和事件” > “订阅事件”下 ，选择 “代码扫描警报”。

配置 SonarQube

1. 在您的 SonarQube 项目中，转到 Administration > DevOps Platform Integrations > GitHub。

2. 单击您的 GitHub 应用程序并选择 edit。

3. 输入 GitHub 应用程序中定义的 Webhook 密钥。

现在，您可以在 SonarQube 中分析项目，并检查检测到的漏洞问题是否显示在 GitHub 界面上（位于存储库的 安全 > 代码扫描警报选项卡下）。

选择 “查看警报” 以查看完整列表：

管理对安全警报的访问

在 GitHub 中，您可以 配置对存储库的安全警报的访问，以启用和禁用安全和分析功能。

关于同步状态更改

当您更改 SonarQube 界面中安全漏洞的状态时，该状态更改会立即反映在 GitHub 界面中。

例如，如果您  在 SonarQube 中将问题从“打开”更改为“ 解决 ”误报：

该更改反映在 GitHub 中的代码扫描警报中，如下所示：

同样，如果您在 GitHub 中将问题从 “打开”更改 为 “驳回：不会修复”  ，则该更改会反映在 SonarQube 中。

状态对应关系

最初，所有在 SonarQube 上标记为 “打开”的问题都在 GitHub 上 标记为 “打开”  。由于两个系统上的可用状态并不完全相同，因此使用以下逻辑来管理转换。