Code Quality

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Code Quality identifies maintainability issues before they become technical debt. The automated feedback that occurs during code reviews can help your team write better code. The findings appear directly in merge requests, making problems visible when they're most cost-effective to fix.

Code Quality works with multiple programming languages and integrates with common linters, style checkers, and complexity analyzers. Your existing tools can feed into the Code Quality workflow, preserving your team's preferences while standardizing how results are displayed.

Features per tier

Different features are available in different GitLab tiers, as shown in the following table:

Scan code for quality violations

Code Quality is an open system that supports importing results from many scanning tools. To find violations and surface them, you can:

• Directly use a scanning tool and import its results. (Preferred.)
• Use a built-in CI/CD template to enable scanning. The template uses the CodeClimate engine, which wraps common open source tools. (Deprecated.)

You can capture results from multiple tools in a single pipeline. For example, you can run a code linter to scan your code along with a language linter to scan your documentation, or you can use a standalone tool along with CodeClimate-based scanning. Code Quality combines all of the reports so you see all of them when you view results.

Import Code Quality results from a CI/CD job

Many development teams already use linters, style checkers, or other tools in their CI/CD pipelines to automatically detect violations of coding standards. You can make the findings from these tools easier to see and fix by integrating them with Code Quality.

To see if your tool already has a documented integration, see Integrate common tools with Code Quality.

To integrate a different tool with Code Quality:

1. Add the tool to your CI/CD pipeline.
2. Configure the tool to output a report as a file.
   • This file must use a specific JSON format.
   • Many tools support this output format natively. They may call it a "CodeClimate report", "GitLab Code Quality report", or another similar name.
   • Other tools can sometimes create JSON output using a custom JSON format or template. Because the report format has only a few required fields, you may be able to use this output type to create a report for Code Quality.
3. Declare a codequality report artifact that matches this file.

Now, after the pipeline runs, the quality tool's results are processed and displayed.

Use the built-in Code Quality CI/CD template (deprecated)

[!warning] This feature was deprecated in GitLab 17.3 and is planned for removal in 19.0. Integrate the results from a supported tool directly instead.

Code Quality also includes a built-in CI/CD template, Code-Quality.gitlab-ci.yaml. This template runs a scan based on the open source CodeClimate scanning engine.

The CodeClimate engine runs:

• Basic maintainability checks for a set of supported languages.
• A configurable set of plugins, which wrap open source scanners, to analyze your source code.

For more details, see Configure CodeClimate-based Code Quality scanning.

Migrate from CodeClimate-based scanning

The CodeClimate engine uses a customizable set of analysis plugins. Some are on by default; others must be explicitly enabled. The following integrations are available to replace the built-in plugins:

View Code Quality results

Code Quality results are shown in the:

• Merge request widget
• Merge request changes view
• Pipeline details view
• Project quality view

Merge request widget

Code Quality analysis results display in the merge request widget area if a report from the target branch is available for comparison. The merge request widget displays Code Quality findings and resolutions that were introduced by the changes made in the merge request. Multiple Code Quality findings with identical fingerprints display as a single entry in the merge request widget. Each individual finding is available in the full report available in the Pipeline details view.

Merge request changes view

{{< details >}}

• Tier: Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Code Quality results display in the merge request Changes view. Lines containing Code Quality issues are marked by a symbol beside the gutter. Select the symbol to see the list of issues, then select an issue to see its details.

Pipeline details view

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

The full list of Code Quality violations generated by a pipeline is shown in the Code Quality tab of the pipeline's details page. The pipeline details view displays all Code Quality findings that were found on the branch it was run on.

Project quality view

{{< details >}}

• Tier: Ultimate
• Offering: GitLab.com, GitLab Self-Managed
• Status: Beta

{{< /details >}}

{{< history >}}

• Introduced in GitLab 14.5 with a flag named project_quality_summary_page. This feature is in beta. Disabled by default.

{{< /history >}}

The project quality view displays an overview of the code quality findings. The view can be found under Analyze > CI/CD analytics, and requires project_quality_summary_page feature flag to be enabled for this particular project.

Code Quality report format

You can import Code Quality results from any tool that can output a report in the following format. This format is a version of the CodeClimate report format that includes a smaller number of fields.

The file you provide as Code Quality report artifact must contain a single JSON array. Each object in that array must have at least the following properties:

The format is different from the CodeClimate report format in the following ways:

• Although the CodeClimate report format supports more properties, Code Quality only processes the fields listed previously.
• The GitLab parser does not allow a byte order mark at the beginning of the file.

For example, this is a compliant report:

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

Integrate common tools with Code Quality

Many tools natively support the required report format to integrate their results with Code Quality. They may call it a "CodeClimate report", "GitLab Code Quality report", or another similar name.

Other tools can be configured to create JSON output by providing a custom template or format specification. Because the report format has only a few required fields, you may be able to use this output type to create a report for Code Quality.

If you already use a tool in your CI/CD pipeline, you should adapt the existing job to add a Code Quality report. Adapting the existing job prevents you from running a separate job that may confuse developers and make your pipelines take longer to run.

If you don't already use a tool, you can write a CI/CD job from scratch or adopt the tool by using a component from the CI/CD Catalog.

Code scanning tools

ESLint

If you already have an ESLint job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Add eslint-formatter-gitlab as a development dependency in your project.
2. Add the --format gitlab option to the command you use to run ESLint.
3. Declare a codequality report artifact that points to the location of the report file.
   • By default, the formatter reads your CI/CD configuration and infers the filename where it should save the report. If the formatter can't infer the filename you used in your artifact declaration, set the CI/CD variable ESLINT_CODE_QUALITY_REPORT to the filename specified for your artifact, such as gl-code-quality-report.json.

You can also use or adapt the ESLint CI/CD component to run the scan and integrate its output with Code Quality.

Stylelint

If you already have a Stylelint job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Add @studiometa/stylelint-formatter-gitlab as a development dependency in your project.
2. Add the --custom-formatter=@studiometa/stylelint-formatter-gitlab option to the command you use to run Stylelint.
3. Declare a codequality report artifact that points to the location of the report file.
   • By default, the formatter reads your CI/CD configuration and infers the filename where it should save the report. If the formatter can't infer the filename you used in your artifact declaration, set the CI/CD variable STYLELINT_CODE_QUALITY_REPORT to the filename specified for your artifact, such as gl-code-quality-report.json.

For more details and an example CI/CD job definition, see the documentation for @studiometa/stylelint-formatter-gitlab.

MyPy

If you already have a MyPy job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Install mypy-gitlab-code-quality as a dependency in your project.

2. Change your mypy command to send its output to a file.

3. Add a step to your job script to reprocess the file into the required format by using mypy-gitlab-code-quality. For example:

   yamlCopy

   - mypy $(find -type f -name "*.py" ! -path "**/.venv/**") --no-error-summary > mypy-out.txt || true  # "|| true" is used for preventing job failure when mypy find errors
   - mypy-gitlab-code-quality < mypy-out.txt > gl-code-quality-report.json
   

4. Declare a codequality report artifact that points to the location of the report file.

You can also use or adapt the MyPy CI/CD component to run the scan and integrate its output with Code Quality.

Flake8

If you already have a Flake8 job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Install flake8-gl-codeclimate as a dependency in your project.
2. Add the arguments --format gl-codeclimate --output-file gl-code-quality-report.json to the command you use to run Flake8.
3. Declare a codequality report artifact that points to the location of the report file.

You can also use or adapt the Flake8 CI/CD component to run the scan and integrate its output with Code Quality.

Pylint

If you already have a Pylint job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Install pylint-gitlab as a dependency in your project.
2. Add the argument --output-format=pylint_gitlab.GitlabCodeClimateReporter to the command you use to run Pylint.
3. Change your pylint command to send its output to a file.
4. Declare a codequality report artifact that points to the location of the report file.

You can also use or adapt the Pylint CI/CD component to run the scan and integrate its output with Code Quality.

Ruff

If you already have a Ruff job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Add the argument --output-format=gitlab to the command you use to run Ruff.
2. Change your ruff check command to send its output to a file.
3. Declare a codequality report artifact that points to the location of the report file.

You can also use or adapt the documented Ruff GitLab CI/CD integration to run the scan and integrate its output with Code Quality.

golangci-lint

If you already have a golangci-lint job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Add the arguments to the command you use to run golangci-lint.

   • For v1 add --out-format code-climate:gl-code-quality-report.json,line-number.
   • For v2 add --output.code-climate.path=gl-code-quality-report.json.

2. Declare a codequality report artifact that points to the location of the report file.

You can also use or adapt the golangci-lint CI/CD component to run the scan and integrate its output with Code Quality.

PMD Copy/Paste Detector

The PMD Copy/Paste Detector (CPD) requires additional configuration because its default output doesn't conform to the required format.

You can use or adapt the PMD CI/CD component to run the scan and integrate its output with Code Quality.

SwiftLint

Using SwiftLint requires additional configuration because its default output doesn't conform to the required format.

You can use or adapt the Swiftlint CI/CD component to run the scan and integrate its output with Code Quality.

RuboCop

Using RuboCop requires additional configuration because its default output doesn't conform to the required format.

You can use or adapt the RuboCop CI/CD component to run the scan and integrate its output with Code Quality.

Roslynator

Using Roslynator requires additional configuration because its default output doesn't conform to the required format.

You can use or adapt the Roslynator CI/CD component to run the scan and integrate its output with Code Quality.

Documentation scanning tools

You can use Code Quality to scan any file stored in a repository, even if it isn't code.

Vale

If you already have a Vale job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Create a Vale template file in your repository that defines the required format.
   • You can copy the open source template used to check GitLab documentation.
   • You can also use another open source variant like the one used in the community gitlab-ci-utils Vale project. This community project also provides a pre-made container image that includes the same template so you can use it directly in your pipelines.
2. Add the arguments --output="$VALE_TEMPLATE_PATH" --no-exit to the command you use to run Vale.
3. Change your vale command to send its output to a file.
4. Declare a codequality report artifact that points to the location of the report file.

You can also use or adapt an open source job definition to run the scan and integrate its output with Code Quality, for example:

• The Vale linting step used to check GitLab documentation.
• The community gitlab-ci-utils Vale project.

markdownlint-cli2

If you already have a markdownlint-cli2 job in your CI/CD pipelines, you should add a report to send its output to Code Quality. To integrate its output:

1. Add markdownlint-cli2-formatter-codequality as a development dependency in your project.

2. If you don't already have one, create a .markdownlint-cli2.jsonc file at the top level of your repository.

3. Add an outputFormatters directive to .markdownlint-cli2.jsonc:

   jsonCopy

   {
     "outputFormatters": [
       [ "markdownlint-cli2-formatter-codequality" ]
     ]
   }
   

4. Declare a codequality report artifact that points to the location of the report file. By default, the report file is named markdownlint-cli2-codequality.json.

   1. Recommended. Add the report's filename to the repository's .gitignore file.

For more details and an example CI/CD job definition, see the documentation for markdownlint-cli2-formatter-codequality.