使用自定义步骤接入 SonarQube 代码扫描

本文为您介绍如何通过自定义步骤接入 SonarQube 代码扫描。

场景介绍

SonarQube 用于对代码进行静态扫描，帮助检测代码中的问题，管控代码质量。持续交付流水线已预置通用的 SonarQube 代码扫描任务，满足日常代码质量检测需求。如果您需要传入特定的配置，或者使用特定版本的 sonarqube scanner 时，就需要通过自定义步骤进行定制化的拓展。

背景信息

自定义步骤由以下 3 个文件组成：

Dockerfile    # 用于构建自定义步骤镜像
entrypoint.sh # 步骤执行脚本，需要和 Dockerfile 一起构建成 Docker 镜像
step.yaml     # 步骤的描述文件。1. 指定步骤运行使用的 Docker 镜像。2. 描述步骤，包括名称、分类、描述、参数(及参数描述)

为了方便与持续交付流水线对接，我们提供了以下基础镜像。您可基于该镜像编写 Dockerfile。

# 查看该镜像的用法
docker run cp-test1-cn-beijing.cr.volces.com/cp-system/sonar-scan --help

# 目前支持的参数
start sonarqube scan

Usage:
  sonarctrl [flags]

Flags:
  -h, --help                        help for sonarctrl
      --scan-quality-gate string    sonarqube quality gate that will fail CP pipeline if not pass
      --sonar-cmd-arg string        arguments passed through to sonar scanner, override any other settings
      --sonar-host-url string       sonarqube server url
      --sonar-project-name string   sonarqube project name
      --sonar-token string          token to access sonarqube server

前提条件

• 账号已具备 CPAdminAccess 权限。子用户可联系对应火山引擎账号授予该权限，具体操作请参考 配置权限。

• 已部署 SonarQube 服务，具体可参考 官方文档。

• 已获取 SonarQube 的 Token，具体操作可参考 获取 SonarQube 的 Token。

• 镜像仓库

  • 已开通火山引擎镜像仓库服务。

  • 已创建命名空间，具体操作可参见 镜像仓库快速入门。

• 持续交付

  • 已创建工作区，详细操作请参见 创建工作区。

  • 已创建代码源，详细操作请参见 创建代码源。

使用限制

• 上传自定义步骤时，仅支持上传 Zip 文件，一次可上传 1 个文件，文件大小不超过 1 M。如需上传超过限制的 Zip 文件，请 提交工单 申请。

• 自定义步骤镜像必须可公开访问。

• 部署 SonarQube 服务时，有以下注意事项：

  • SonarQube 服务必须和您使用的构建资源池网络互通。

    • 如果您使用公共资源池，需保证 SonarQube 服务可通过公网访问。

    • 如果您使用私有资源池，需自行打通 SonarQube 服务和您的私有资源池网络。

  • SonarQube 服务的版本不低于 LTS 8.9 。

  • values.yaml文件中postgresql.volumePermissions.enabled参数的值必须修改为 true，其他参数配置请按需修改。

操作步骤

步骤一：编写自定义步骤

在本地编写 step.yaml 、Dockerfile 、entrypoint.sh 文件。

1. 编写 step.yaml 文件。step.yaml 文件支持的前端组件及标准属性请参考 步骤 YAML 描述语言。

name: sonarqube-step # 自定义步骤的名称, 用于前端展示
sign: sonarqubedemo  # 步骤的唯一标识
# 镜像地址，请替换实际使用的 Docker 镜像地址。此处填写的镜像地址必须与步骤二构建的镜像地址保持一致
image: xxx.cr.volces.com/yournamespace/sonar-scan:V1 
version: 1.0.0 # 原子步骤版本, 需遵循 X.Y.Z 规范
description: this is a customized sonarqube scan image # 描述
category: Test # 自定义步骤的分类，用于前端分类展示自定义步骤
# 定义入参表单
items:
- name: SONAR_URL # 该组件的唯一标识。在自定义镜像中可以通过同 name 的环境变量引用输入值
  label: sonarqube 服务URL # 输入 SonarQube 服务的访问地址
  type: Input
- name: SONAR_TOKEN
  label: sonarqube token # 输入 SonarQube 服务的 Token 
  type: Input
- name: SCAN_QUALITY_GATE
  label: 质量门禁 # 支持使用质量门禁值作为 SonarQube 代码扫描任务是否通过的判断条件，您可使用 bugs 和 vulnerabilities 作为判断指标。
  type: Input
  description: 例如 [{"name":"bugs", "value":10}, {"name":"vulnerabilities", "value":5}]
#输入 sonarqube scanner 的控制台参数，会被原样传递
- name: SONAR_SCANNER_ARG
  label: sonarqube 参数 # 输入特定的 sonarqube 参数，可以留空
  type: Input
  defaultValue: -Dsonar.java.binaries=. -Dsonar.sources=. -Dsonar.java.libraries=. -Dsonar.language=java
- name: SONAR_PROJECT_NAME
  label: 扫描项目名称 # 输入 Project name。如果留空，流水线会使用 cp_[scm_project_name]_[step hash]
  type: Input
# 设置流水线运行记录中包含的返回值，目前支持返回缺陷数（Bugs）、漏洞数（Vulnerabilities）、代码异味（Code Smells）、覆盖率（Coverage）、SonarQube 扫描报告
results: report,vulnerabilities,bugs,coverage,code_smells

2. 编辑 Dockerfile 文件。

# 基础镜像。使用预置的 sonarqube 步骤镜像
FROM cp-test1-cn-beijing.cr.volces.com/cp-system/sonar-scan:latest
# 工作目录。流水线的工作目录会 mount 到 /workspace 下，其他步骤产生/依赖的文件也会存在这个目录下（e.g. git clone)
WORKDIR /workspace 
# 容器启动后执行的命令。ENTRYPOINT 必须是自定义步骤文件中的 entrypoint.sh，请勿修改
ENTRYPOINT ["/entrypoint.sh"] 
ADD entrypoint.sh /entrypoint.sh

# 安装需要的工具。基础镜像为 Alpine
# 安装工具用，值得注意的是流水线运行时总是会指定用 nobody 运行
USER root
# 提供 envsubst
RUN apk add --no-cache gettext

3. 编写 entrypoint 文件。

#!/bin/bash

# 镜像中预置了 sonarqube scanner 可执行文件，如果需要可以自行添加 scanner 
# 并通过设置如下环境变量启用
SCANNER_PATH="sonar-scanner" # replace me to use custom scanner

# 保证自定义步骤中的参数可以使用流水线中的变量替换能力
SONAR_URL=$(envsubst <<< "$SONAR_URL")
SONAR_TOKEN=$(envsubst <<< "$SONAR_TOKEN")
SCAN_QUALITY_GATE=$(envsubst <<< "$SCAN_QUALITY_GATE")
SONAR_SCANNER_ARG=$(envsubst <<< "$SONAR_SCANNER_ARG")
SONAR_PROJECT_NAME=$(envsubst <<< "$SONAR_PROJECT_NAME")

# 此处支持编写希望执行的自定义命令

# sonar-scan 镜像中预置了 sonarctrl， 用于启动 sonar scanner：将流水线给出的输入处理并传递给 scanner，并在 scan 完成后收集结果传递回流水线
exec /usr/local/bin/sonarctrl --sonar-host-url="$SONAR_URL" \
                              --sonar-token="$SONAR_TOKEN" \
                              --scan-quality-gate="$SCAN_QUALITY_GATE" \
                              --sonar-cmd-arg="$SONAR_SCANNER_ARG" \
                              --sonar-project-name="$SONAR_PROJECT_NAME"

步骤二：构建 Docker 镜像

使用编写完成的 Dockerfile 和 entrypoint.sh 制作自定义步骤运行时所需的 Docker 镜像，并将镜像推送至可公开访问的镜像仓库。

# 本示例将镜像构建并推送至火山引擎镜像仓库

# 登录火山引擎镜像仓库。请替换实际的 username 和仓库地址。
docker login --username=xxx@2100****** xxx.cr.volces.com

# 进入 Dockerfile 所在目录。本示例在 sonar-step 文件夹下
cd sonar-step

# 构建镜像并推送至目标镜像仓库
# 请替换实际的镜像地址。镜像地址需要与 step.yaml 文件中填写的 image 保持一致
# 镜像仓库需设置为可公开访问，否则流水线（使用公共资源池）无法拉取到镜像
docker buildx build -t xxx.cr.volces.com/yournamespace/sonar-scan:V1 -f Dockerfile . --push

步骤三：上传自定义步骤

1. 将编写好的 step.yaml 、Dockerfile 、entrypoint.sh 打包为 Zip 文件。

2. 登录 持续交付控制台，在左侧导航栏选择 模板市场 > 步骤模板。

3. 单击 创建自定义步骤，弹出说明框。

4. 单击 上传自定义模板，选择本地打包好的 Zip 文件。上传后，单击 保存文件。
   您可在 步骤模板 > 自定义步骤 页面的 测试 分类下查看到该 sonarqube-step 步骤。

   

结果验证

1. 在流水线中配置代码源和 sonarqube-step 步骤，并保存流水线。

   

2. 手动运行流水线，sonarqube-step 步骤运行成功，系统成功返回 step.yaml 中设置的 result 信息。