Code Quality

原文：https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html

Code Quality

Introduced in GitLab Starter 9.3.

确保项目的代码保持简单，易读和易于贡献可能会引起问题. 借助GitLab CI / CD ，您可以使用 GitLab 代码质量分析源代码质量.

代码质量：

更进一步，GitLab 可以在合并请求小部件区域中显示”代码质量”报告：

Code Quality Widget

观看实践中的代码质量快速演练：

观看视频： 代码质量：快速运行 .

注意：对于一位客户，审核员发现，在 GitLab CI / CD 中使代码质量，SAST 和容器扫描全部自动化几乎比手动审核要好！ 阅读更多 .

另请参阅” 可维护性支持的语言的代码气候列表”.

Use cases

例如，考虑以下工作流程：

  1. 您的后端团队成员将开始新的实施，以更快地使您的应用中的某些功能.
  2. 通过代码质量报告，他们可以分析其实施如何影响代码质量.
  3. The metrics show that their code degrades the quality by 10 points.
  4. 您要求同事来帮助他们进行此修改.
  5. 他们都将对更改进行处理，直到”代码质量”报告显示不降级，仅显示改进.
  6. 您批准合并请求并授权其部署到暂存.
  7. 验证后，其更改将部署到生产中.

Example configuration

注意： GitLab 11.11 和更高版本支持以下所示的作业定义. 它还需要 GitLab Runner 11.5 或更高版本. 对于早期版本，请使用先前的作业定义 .

本示例说明如何使用 GitLab CI / CD 和 Docker 在代码上运行代码质量.

首先，您需要配置 GitLab Runner：

设置运行器后，在您的 CI 配置中包括代码质量模板：

  1. include:
  2.   - template: Code-Quality.gitlab-ci.yml

上面的示例将在 CI / CD 管道中创建一个code_quality作业，该作业将扫描源代码以查看代码质量问题. 该报告将另存为“代码质量”报告工件 ，您以后可以下载和分析该工件 .

通过设置CODE_QUALITY_IMAGE变量，也可以覆盖 URL 到”代码质量”图像. 如果您想锁定特定版本的 Code Quality 或使用其中的一个分支，这将特别有用：

  1. include:
  2.   - template: Code-Quality.gitlab-ci.yml
  4. code_quality:
  5.   variables:
  6.     CODE_QUALITY_IMAGE: "registry.example.com/codequality-fork:latest"

默认情况下，报告工件不可下载. 如果需要在工作详细信息页面上下载它们，则可以将gl-code-quality-report.json到工件路径，如下所示：

  1. include:
  2.   - template: Code-Quality.gitlab-ci.yml
  4. code_quality:
  5.   artifacts:
  6.     paths: [gl-code-quality-report.json]

包含的code_quality作业正在test阶段运行，因此需要将其包含在 CI 配置中，如下所示：

  1. stages:
  2.   - test

提示：该信息将被自动提取并显示在合并请求小部件中.注意：在自我管理的实例上，如果恶意行为者破坏了 Code Quality 作业定义，则他们将能够在 Runner 主机上执行特权的 Docker 命令. 拥有适当的访问控制策略，可以通过仅允许访问受信任的参与者来减轻这种攻击.

Previous job definitions

警告：在 GitLab 11.5 之前，必须专门命名代码质量作业和工件以自动提取报告数据并将其显示在合并请求小部件中. 尽管这些旧的作业定义仍然保留，但它们已被弃用，并且在 GitLab 12.0 或更高版本中不再受支持. 建议您更新.gitlab-ci.yml配置以反映该更改.

对于 GitLab 11.5 及更高版本，该工作应如下所示：

  1. code_quality:
  2.   image: docker:stable
  3.   variables:
  4.     DOCKER_DRIVER: overlay2
  5.   allow_failure: true
  6.   services:
  7.     - docker:stable-dind
  8.   script:
  9.     - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
  10.     - docker run
  11.         --env SOURCE_CODE="$PWD"
  12.         --volume "$PWD":/code
  13.         --volume /var/run/docker.sock:/var/run/docker.sock
  14.         "registry.gitlab.com/gitlab-org/ci-cd/codequality:$SP_VERSION" /code
  15.   artifacts:
  16.     reports:
  17.       codequality: gl-code-quality-report.json

在 GitLab 12.6 中，”代码质量”切换到了新的版本控制方案 . 强烈建议包括代码质量模板，如示例配置所示，该模板使用新的版本控制方案. 如果不使用模板，则可以将SP_VERSION变量硬编码为使用新的映像版本：

  1. code_quality:
  2.   image: docker:stable
  3.   variables:
  4.     DOCKER_DRIVER: overlay2
  5.     SP_VERSION: 0.85.6
  6.   allow_failure: true
  7.   services:
  8.     - docker:stable-dind
  9.   script:
  10.     - docker run
  11.         --env SOURCE_CODE="$PWD"
  12.         --volume "$PWD":/code
  13.         --volume /var/run/docker.sock:/var/run/docker.sock
  14.         "registry.gitlab.com/gitlab-org/ci-cd/codequality:$SP_VERSION" /code
  15.   artifacts:
  16.     reports:
  17.       codequality: gl-code-quality-report.json

对于 GitLab 11.4 和更早版本，该工作应如下所示：

  1. code_quality:
  2.   image: docker:stable
  3.   variables:
  4.     DOCKER_DRIVER: overlay2
  5.   allow_failure: true
  6.   services:
  7.     - docker:stable-dind
  8.   script:
  9.     - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
  10.     - docker run
  11.         --env SOURCE_CODE="$PWD"
  12.         --volume "$PWD":/code
  13.         --volume /var/run/docker.sock:/var/run/docker.sock
  14.         "registry.gitlab.com/gitlab-org/ci-cd/codequality:$SP_VERSION" /code
  15.   artifacts:
  16.       paths: [gl-code-quality-report.json]

或者，作业名称可以是codeclimate或codequality ，工件名称可以是codeclimate.json . 这些名称已在 GitLab 11.0 中弃用，并可能在下一个主要版本 GitLab 12.0 中删除.

对于 GitLab 10.3 及更早版本，该工作应如下所示：

  1. codequality:
  2.   image: docker:latest
  3.   variables:
  4.     DOCKER_DRIVER: overlay
  5.   services:
  6.     - docker:dind
  7.   script:
  8.     - docker pull codeclimate/codeclimate:0.69.0
  9.     - docker run --env CODECLIMATE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock --volume /tmp/cc:/tmp/cc codeclimate/codeclimate:0.69.0 init
  10.     - docker run --env CODECLIMATE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock --volume /tmp/cc:/tmp/cc codeclimate/codeclimate:0.69.0 analyze -f json > codeclimate.json || true
  11.   artifacts:
  12.     paths: [codeclimate.json]

Configuring jobs using variables

代码质量作业支持环境变量，用户可以将其设置为在运行时配置作业执行.

For a list of available environment variables, see Environment variables.

Implementing a custom tool

可以使用自定义工具在 GitLab 中提供代码质量报告. 去做这个：

  1. 在.gitlab-ci.yml文件中定义一个生成代码质量报告工件的作业 .
  2. 配置您的工具以将代码质量报告工件作为 JSON 文件生成，该文件实现了Code Climate 规范的子集.

代码质量报告工件 JSON 文件必须包含具有以下属性的对象数组：

Name Description
description A description of the code quality violation.
fingerprint 用于识别代码质量违规的唯一指纹. 例如，MD5 哈希.
location.path 包含代码质量违规的文件的相对路径.
location.lines.begin 发生代码质量违规的行.

Example:

  1. [  {  "description":  "'unused' is assigned a value but never used.",  "fingerprint":  "7815696ecbf1c96e6894b779456d330e",  "location":  {  "path":  "lib/index.js",  "lines":  {  "begin":  42  }  }  }  ]

注意：尽管 Code Climate 规范支持更多属性，但 GitLab 会忽略这些属性.

Code Quality reports

代码质量工作完成后：

  • 管道生成的违反代码质量的完整列表可在”管道详细信息”页面的”代码质量”选项卡中找到.
  • 代码质量的潜在更改直接在合并请求中显示. 合并请求中的”代码质量”窗口小部件比较分支基础和头部的报告，然后列出合并分支时将解决或创建的所有违例.
  • 完整的 JSON 报告可作为code_quality作业的可下载工件获得.

Extending functionality

Using Analysis Plugins

如果有需要延长的代码质量所提供的默认功能，如在规定的代码质量 ， 分析插件可供选择.

例如，要使用SonarJava 分析器 ，请在存储库的根目录中添加一个名为.codeclimate.yml的文件， .codeclimate.yml包含插件的启用代码 ：

  1. version: "2"
  2. plugins:
  3.   sonar-java:
  4.     enabled: true

这会将 SonarJava 添加到项目中默认.codeclimate.yml的plugins:部分.

对plugins:部分的更改不会影响 defeault .codeclimate.yml的exclude_patterns部分. 有关更多详细信息，请参见代码气候文档以排除文件和文件夹 .

这是一个示例项目 ， 该示例项目将 Code Quality 与.codeclimate.yml文件一起使用.

Troubleshooting

Changing the default configuration has no effect

一个普遍的问题是Code Quality （特定于 GitLab）和Code Climate （GitLab 使用的引擎）这两个术语非常相似. 您必须添加.codeclimate.yml文件来更改默认配置， 而不是 .codequality.yml文件. 如果使用错误的文件名，仍将使用默认的.codeclimate.yml .

No Code Quality report is displayed in a Merge Request

这可能是由于多种原因：

  • 您刚刚在.gitlab-ci.yml添加了代码质量工作. 该报告尚无可比较的内容，因此无法显示任何信息. 将来的合并请求将具有可比性.
  • 如果未检测到降级或错误 ，则不会显示任何内容.
  • artifacts:expire_in CI / CD 设置可能导致代码质量构件过期快于所需.
  • codeclimate.json较大的codeclimate.json文件（尤其是> 10 MB）会阻止报告的显示 . 解决方法是，尝试删除GitLab 忽略的 属性 . 您可以：
    • 配置代码质量工具以不输出那些类型.
    • 在作业完成之前，请在.gitlab-ci.yml脚本中使用sed ， awk或类似命令来编辑codeclimate.json .

Only a single Code Quality report is displayed, but more are defined

GitLab 仅使用最新创建的作业（具有最大的作业 ID）的代码质量工件. 如果管道中的多个作业生成代码质量工件，则较早作业的那些将被忽略. 为避免混淆，仅配置一个作业即可生成codeclimate.json .