SonarQube 与 GitLab 自我管理和 GitLab.com 的集成使您能够维护 GitLab 项目中的代码质量和安全性。

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

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

• 导入您的 GitLab 项目：将您的 GitLab 项目导入 SonarQube 以轻松设置 SonarQube 项目。

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

• 向合并请求报告质量门状态：（从 Developer Edition开始）直接在 GitLab 中查看质量门和代码指标结果，以便了解合并更改是否安全。

先决条件

• 要将 SonarQube 与 GitLab 自我管理订阅集成，我们建议使用GitLab 版本 15.6+。

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

分支分析

Community Edition 不支持多个分支的分析，因此您只能分析您的主分支。从 Developer Edition开始，您可以分析多个分支和合并请求。

使用 GitLab 进行身份验证

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

将 GitLab 项目导入 SonarQube

设置将 GitLab 项目导入到 SonarQube 中，您可以轻松地从 GitLab 项目创建 SonarQube 项目。如果您使用的是 Developer Edition 或更高版本，这也是添加合并请求修饰的第一步。

要设置 GitLab 项目的导入：

1. 设置您的全局设置

2. 添加个人访问令牌以导入存储库

设置您的全局设置

要将 GitLab 项目导入 SonarQube，您需要首先设置全局 SonarQube 设置。导航到 Administration > Configuration > General Settings > DevOps Platform Integrations，选择 GitLab 选项卡，然后指定以下设置：

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

• GitLab URL：GitLab API URL。我们建议使用https://gitlab.com。您还可以使用自己的 GitLab 服务器 URL。

• 个人访问令牌：GitLab 用户帐户用于装饰合并请求。我们建议使用至少具有 记者 权限的专用 GitLab 帐户 （该帐户需要发表评论的权限）。使用此帐户中的个人访问令牌以及  为您正在分析的存储库授权的api范围。管理员可以在Administration > Configuration > Encryption中加密此令牌 。请参阅 安全性 的 设置加密部分 页面了解更多信息。此个人访问令牌用于向拉取请求报告您的质量门状态。在下一部分中，您将被要求提供另一个个人访问令牌来导入项目。

添加个人访问令牌以导入项目

设置完这些全局设置后，您可以通过单击 项目 主页右上角的 添加项目按钮 并选择 GitLab从 GitLab 添加项目。

然后，系统会要求您提供具有 read_api 范围的个人访问令牌，以便 SonarQube 可以访问并列出您的 GitLab 项目。该令牌将存储在 SonarQube 中，并且可以随时在 GitLab 中撤销。

保存个人访问令牌后，您将看到 GitLab 项目列表，您可以将其设置为添加到 SonarQube。以这种方式设置项目还会设置合并请求修饰的项目设置。

有关使用 GitLab CI/CD 分析项目的信息，请参阅以下部分。

使用 GitLab CI/CD 分析项目

在 GitLab CI/CD 作业中运行的 SonarScanner 可以自动检测正在构建的分支或合并请求，因此您无需专门将它们作为参数传递给扫描器。

产品内教程将为您提供分析项目所需的所有信息。

要使用 GitLab CI/CD 分析您的项目，您需要：

• 设置您的环境变量。

• 配置您的 .gitlab-ci.yml 文件。

以下部分详细介绍了这些步骤。

设置环境变量

您可以在 GitLab 设置中为所有管道安全地设置环境变量。有关更多信息，请参阅 GitLab 有关 CI/CD 变量的文档 。

需要在GitLab中设置以下环境变量进行分析：

• Sonar 令牌：为 GitLab 生成 SonarQube 令牌 ，并在 GitLab 中创建一个自定义环境变量，将其 SONAR_TOKEN 作为 Key 并使用您生成的令牌作为 Value。

• Sonar Host URL：创建一个自定义环境变量，将其 SONAR_HOST_URL 作为 键 ，将您的 SonarQube 服务器 URL 作为 值。

创建或更新配置文件

配置您的属性文件

如果需要，当您选择描述构建的选项时，SonarQube 会为您提供一个片段以添加到属性文件中：

例如，对于Gradle，提供了以下示例：

配置 .gitlab-ci.yml 文件

本部分向您展示如何配置 GitLab CI/CD .gitlab-ci.yml 文件。示例中的参数 allow_failure 允许作业失败，而不影响 CI 套件的其余部分。

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

• 社区版：社区版不支持多个分支，因此您应该只分析您的主分支。您可以通过使用规则在 .yml 文件中添加分支名称来限制对主分支的分析。

• 开发版及以上版本： 默认情况下，GitLab 将构建所有分支，但不构建合并请求。要构建合并请求，您需要在 .gitlab-ci.yml. 有关详细信息，请参阅下面的示例配置。

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

sonarqube-check:
  image: gradle:8.2.0-jdk17-jammy
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script: gradle sonarqube -Dsonar.qualitygate.wait=true
  allow_failure: true
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'

C/C++/Objective-C 配置示例

对于一些示例，您可以参考sonarsource-cfamily-examples存储库。

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

为了使质量门在 SonarQube 端失败时在 GitLab 端也失败，扫描器需要等待 SonarQube 质量门状态。要启用此功能，请 在文件sonar.qualitygate.wait=true 中设置参数 .gitlab-ci.yml 。

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

了解更多信息

有关使用 GitLab CI/CD 配置构建的更多信息，请参阅 GitLab CI/CD 管道配置参考。

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

如上一节所示，设置 SonarQube 导入 GitLab 项目后，SonarQube 可以直接向 GitLab 报告质量门状态和分析指标。

为此，请单击 项目 主页右上角的 添加项目按钮，然后 从下拉菜单中 选择 GitLab ，从 GitLab 添加项目。

然后，按照 SonarQube 中的步骤分析您的项目。SonarQube 会自动设置在合并请求中显示质量门所需的项目设置。

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

SonarQube 还可以向 GitLab 报告现有项目和手动创建项目的质量门状态。按照上面将GitLab 项目导入到 SonarQube部分所示更新全局设置后 ，请在Project Settings > General Settings > DevOps Platform Integration 中设置以下项目设置 ：

• 配置名称: 与您的 GitLab 实例对应的配置名称

• 项目 ID：在 GitLab 中找到的您的 GitLab 项目 ID

报告 GitLab 中的漏洞

此功能从Developer Edition开始提供，并且需要 GitLab Ultimate。

SonarQube 可以提供有关 GitLab 界面本身内部安全漏洞的反馈。SonarQube 发现的安全漏洞将显示在Gitlab >漏洞报告页面上。

先决条件

确保拥有个人访问令牌的用户具有浏览权限（请参阅安全 > 身份验证 > 项目权限）。 

配置 .gitlab-ci.yml 文件

要激活此功能，请将漏洞报告阶段添加到您的.gitlab-ci.yml文件中，如下所示：

关于同步状态更改

最初，所有在 SonarQube 上标记为“打开”的问题在 GitLab 上都标记为“需要分类”。 

当您在 SonarQube 中更新问题的状态时，它也会在 GitLab 中更新。 

状态对应关系

由于两个系统上的可用状态并不完全相同，因此使用以下逻辑来管理转换：

严重性映射

下表列出了两个系统中的严重级别：

故障排除

在 Gitlab 中，修改文件后您的问题可能会重复出现。在这种情况下，我们建议使用“活动” > “仍检测到”过滤器。

高级配置