root
/
gitlab-ce
mirror of https://gitlab.com/free-releases/gitlab-ce.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
gitlab-ce/doc/ci/testing/code_quality.md

534 lines
22 KiB
Markdown
Raw Blame History

---
stage: Secure
group: Static Analysis
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Code Quality
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** SaaS, self-managed
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2.
Use Code Quality to analyze your source code's quality and complexity. This helps keep your
project's code simple, readable, and easier to maintain. Code Quality should supplement your
other review processes, not replace them.
Code Quality runs in CI/CD pipelines, and helps you avoid merging changes that would degrade your code's quality.
Code Quality uses the open source Code Climate tool, and selected
[plugins](https://docs.codeclimate.com/docs/list-of-engines), to analyze your source code.
To confirm if your code's languages are covered, see the Code Climate list of
[Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability).
You can extend the code coverage either by using Code Climate
[Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a
[custom tool](#implement-a-custom-tool).
## Features per tier
Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/),
as shown in the following table:
| Feature | In Free | In Premium | In Ultimate |
|:----------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|
| [Configure scanners](#customizing-scan-settings) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
| [Integrate custom scanners](#implement-a-custom-tool) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
| [Generate JSON or HTML report artifacts](#output) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
| [Findings in merge request widget](#merge-request-widget) | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes |
| [Findings in pipelines](#pipeline-details-view) | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes |
| [Findings in merge request changes view](#merge-request-changes-view) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
| [Summary in project quality view](#project-quality-view) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes |
## 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
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2.
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.
![Code Quality Widget](img/code_quality_widget_13_11.png)
### Merge request changes view
DETAILS:
**Tier:** Ultimate
**Offering:** SaaS, self-managed
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in GitLab 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../administration/feature_flags.md).
> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12.
> - [Disabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0 due to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334116).
> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1.
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.
![Code Quality Inline Indicator](img/code_quality_inline_indicator_v16_7.png)
### Pipeline details view
DETAILS:
**Tier:** Premium, Ultimate
**Offering:** SaaS, self-managed
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.
![Code Quality Report](img/code_quality_report_13_11.png)
### Project quality view
DETAILS:
**Tier:** Ultimate
**Offering:** SaaS, self-managed
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`](../../user/feature_flags.md) feature flag to be enabled for this particular project.
![Code Quality Summary](img/code_quality_summary_15_9.png)
## Enable Code Quality
Prerequisites:
- GitLab CI/CD configuration (`.gitlab-ci.yml`) must include the `test` stage.
- If you're using instance runners, the Code Quality job must be configured for the
[Docker-in-Docker workflow](../docker/using_docker_build.md#use-docker-in-docker).
- If you're using private runners, you should use an
[alternative configuration](#improve-code-quality-performance-with-private-runners)
recommended for running Code Quality analysis more efficiently.
- The runner must have enough disk space to store the generated Code Quality files. For example, on
the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB.
To enable Code Quality, either:
- Enable [Auto DevOps](../../topics/autodevops/index.md), which includes
[Auto Code Quality](../../topics/autodevops/stages.md#auto-code-quality).
- Include the Code Quality template in your
`.gitlab-ci.yml` file.
Example:
```yaml
include:
- template: Code-Quality.gitlab-ci.yml
```
Code Quality now runs in pipelines.
WARNING:
On self-managed instances, if a malicious actor compromises the Code Quality job definition they
could execute privileged Docker commands on the runner host. Having proper access control policies
mitigates this attack vector by allowing access only to trusted actors.
### Improve Code Quality performance with private runners
If you have private runners, you should use this configuration for improved performance of Code
Quality because:
- Privileged mode is not used.
- Docker-in-Docker is not used.
- Docker images, including all CodeClimate images, are cached, and not re-fetched for subsequent jobs.
This alternative configuration uses socket binding to share the Runner's Docker daemon
with the job environment. Before implementing this configuration, consider its
[limitations](../docker/using_docker_build.md#use-the-docker-executor-with-docker-socket-binding).
To use private runners:
1. Register a new runner:
```shell
$ gitlab-runner register --executor "docker" \
--docker-image="docker:latest" \
--url "https://gitlab.com/" \
--description "cq-sans-dind" \
--tag-list "cq-sans-dind" \
--locked="false" \
--access-level="not_protected" \
--docker-volumes "/cache"\
--docker-volumes "/builds:/builds"\
--docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \
--registration-token="<project_token>" \
--non-interactive
```
1. **Optional, but recommended:** Set the builds directory to `/tmp/builds`,
so job artifacts are periodically purged from the runner host. If you skip
this step, you must clean up the default builds directory (`/builds`) yourself.
You can do this by adding the following two flags to `gitlab-runner register`
in the previous step.
```shell
--builds-dir "/tmp/builds"
--docker-volumes "/tmp/builds:/tmp/builds" # Use this instead of --docker-volumes "/builds:/builds"
```
The resulting configuration:
```toml
[[runners]]
name = "cq-sans-dind"
url = "https://gitlab.com/"
token = "<project_token>"
executor = "docker"
builds_dir = "/tmp/builds"
[runners.docker]
tls_verify = false
image = "docker:latest"
privileged = false
disable_entrypoint_overwrite = false
oom_kill_disable = false
disable_cache = false
volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock", "/tmp/builds:/tmp/builds"]
shm_size = 0
[runners.cache]
[runners.cache.s3]
[runners.cache.gcs]
```
1. Apply two overrides to the `code_quality` job created by the template:
```yaml
include:
- template: Code-Quality.gitlab-ci.yml
code_quality:
services: # Shut off Docker-in-Docker
tags:
- cq-sans-dind # Set this job to only run on our new specialized runner
```
Code Quality now runs in standard Docker mode.
## Disable Code Quality
The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable
is present. For more information about how to define a variable, see
[GitLab CI/CD variables](../variables/index.md).
To disable Code Quality, create a custom CI/CD variable named `CODE_QUALITY_DISABLED`, for either:
- [The whole project](../variables/index.md#for-a-project).
- [A single pipeline](../pipelines/index.md#run-a-pipeline-manually).
## Customizing scan settings
The Code Quality scan settings can be changed using [CI/CD variables](#available-cicd-variables)
in `.gitlab-ci.yml`.
To configure the Code Quality job:
1. Declare a job with the same name as the Code Quality job, after the template's inclusion.
1. Specify additional keys in the job's stanza.
For an example, see [Download output in HTML format](#output-in-only-html-format).
## Available CI/CD variables
Code Quality can be customized by defining available CI/CD variables:
| CI/CD variable | Description |
|---------------------------------|-------------|
| `CODECLIMATE_DEBUG` | Set to enable [Code Climate debug mode](https://github.com/codeclimate/codeclimate#environment-variables). |
| `CODECLIMATE_DEV` | Set to enable `--dev` mode which lets you run engines not known to the CLI. |
| `CODECLIMATE_PREFIX` | Set a prefix to use with all `docker pull` commands in CodeClimate engines. Useful for [offline scanning](https://github.com/codeclimate/codeclimate/pull/948). For more information, see [Use a private container registry](#use-a-private-container-image-registry). |
| `CODECLIMATE_REGISTRY_USERNAME` | Set to specify the username for the registry domain parsed from `CODECLIMATE_PREFIX`. |
| `CODECLIMATE_REGISTRY_PASSWORD` | Set to specify the password for the registry domain parsed from `CODECLIMATE_PREFIX`. |
| `CODE_QUALITY_DISABLED` | Prevents the Code Quality job from running. |
| `CODE_QUALITY_IMAGE` | Set to a fully prefixed image name. Image must be accessible from your job environment. |
| `ENGINE_MEMORY_LIMIT_BYTES` | Set the memory limit for engines. Default: 1,024,000,000 bytes. |
| `REPORT_STDOUT` | Set to print the report to `STDOUT` instead of generating the usual report file. |
| `REPORT_FORMAT` | Set to control the format of the generated report file. Either `json` or `html`. |
| `SOURCE_CODE` | Path to the source code to scan. Must be the absolute path to a directory where cloned sources are stored. |
| `TIMEOUT_SECONDS` | Custom timeout per engine container for the `codeclimate analyze` command. Default: 900 seconds (15 minutes) |
## Output
Code Quality outputs a report containing details of issues found. The content of this report is
processed internally and the results shown in the UI. The report is also output as a job artifact of
the `code_quality` job, named `gl-code-quality-report.json`. You can optionally output the report in
HTML format. For example, you could publish the HTML format file on GitLab Pages for even easier
reviewing.
### Output in JSON and HTML format
To output the Code Quality report in JSON and HTML format, you create an additional job. This requires
Code Quality to be run twice, once each for file format.
To output the Code Quality report in HTML format, add another job to your template by using
`extends: code_quality`:
```yaml
include:
- template: Code-Quality.gitlab-ci.yml
code_quality_html:
extends: code_quality
variables:
REPORT_FORMAT: html
artifacts:
paths: [gl-code-quality-report.html]
```
Both the JSON and HTML files are output as job artifacts. The HTML file is contained in the
`artifacts.zip` job artifact.
### Output in only HTML format
To download the Code Quality report in _only_ HTML format, set `REPORT_FORMAT` to `html`, overriding
the default definition of the `code_quality` job.
NOTE:
This does not create a JSON format file, so Code Quality results are not shown in the merge request
widget, pipeline report, or changes view.
```yaml
include:
- template: Code-Quality.gitlab-ci.yml
code_quality:
variables:
REPORT_FORMAT: html
artifacts:
paths: [gl-code-quality-report.html]
```
The HTML file is output as a job artifact.
## Use Code Quality with merge request pipelines
The default Code Quality configuration does not allow the `code_quality` job to run on
[merge request pipelines](../pipelines/merge_request_pipelines.md).
To enable Code Quality to run on merge request pipelines, overwrite the code quality `rules`,
or [`workflow: rules`](../yaml/index.md#workflow), so that they match your current `rules`.
For example:
```yaml
include:
- template: Code-Quality.gitlab-ci.yml
code_quality:
rules:
- if: $CODE_QUALITY_DISABLED
when: never
- if: $CI_PIPELINE_SOURCE == "merge_request_event" # Run code quality job in merge request pipelines
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run code quality job in pipelines on the default branch (but not in other branch pipelines)
- if: $CI_COMMIT_TAG # Run code quality job in pipelines for tags
```
## Use a private container image registry
> - [Introduced](https://gitlab.com/gitlab-org/ci-cd/codequality/-/merge_requests/30) in GitLab 13.7.
Using a private container image registry can reduce the time taken to download images, and also
reduce external dependencies. You must configure the registry prefix to be passed down
to CodeClimate's subsequent `docker pull` commands for individual engines, because of
the nested method of container execution.
The following variables can address all of the required image pulls:
- `CODE_QUALITY_IMAGE`: A fully prefixed image name that can be located anywhere
accessible from your job environment. GitLab container registry can be used here
to host your own copy.
- `CODECLIMATE_PREFIX`: The domain of your intended container image registry. This
is a configuration option supported by [CodeClimate CLI](https://github.com/codeclimate/codeclimate/pull/948).
You must:
- Include a trailing slash (`/`).
- Not include a protocol prefix, such as `https://`.
- `CODECLIMATE_REGISTRY_USERNAME`: An optional variable to specify the username for the registry domain parsed from `CODECLIMATE_PREFIX`.
- `CODECLIMATE_REGISTRY_PASSWORD`: An optional variable to specify the password for the registry domain parsed from `CODECLIMATE_PREFIX`.
```yaml
include:
- template: Code-Quality.gitlab-ci.yml
code_quality:
variables:
CODE_QUALITY_IMAGE: "my-private-registry.local:12345/codequality:0.85.24"
CODECLIMATE_PREFIX: "my-private-registry.local:12345/"
```
This example is specific to GitLab Code Quality. For more general instructions on how to configure
DinD with a registry mirror, see
[Enable registry mirror for Docker-in-Docker service](../docker/using_docker_build.md#enable-registry-mirror-for-dockerdind-service).
### Required images
The following images are required for the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template):
- `codeclimate/codeclimate-structure:latest`
- `codeclimate/codeclimate-csslint:latest`
- `codeclimate/codeclimate-coffeelint:latest`
- `codeclimate/codeclimate-duplication:latest`
- `codeclimate/codeclimate-eslint:latest`
- `codeclimate/codeclimate-fixme:latest`
- `codeclimate/codeclimate-rubocop:rubocop-0-92`
If you are using a custom `.codeclimate.yml` configuration file, you must add the specified plugins in your private container registry.
## Use DockerHub with authentication
You can use DockerHub as an alternate source of the Code Quality images.
Prerequisites:
- Add the username and password as [protected CI/CD variables](../variables/index.md#for-a-project)
in the project.
To use DockerHub, configure the following variables in the `.gitlab-ci.yml` file:
- `CODECLIMATE_PREFIX`
- `CODECLIMATE_REGISTRY_USERNAME`
- `CODECLIMATE_REGISTRY_PASSWORD`
Example:
```yaml
include:
- template: Jobs/Code-Quality.gitlab-ci.yml
code_quality:
variables:
CODECLIMATE_PREFIX: "registry-1.docker.io/"
CODECLIMATE_REGISTRY_USERNAME: $DOCKERHUB_USERNAME
CODECLIMATE_REGISTRY_PASSWORD: $DOCKERHUB_PASSWORD
```
## Use the Dependency Proxy
You can use a Dependency Proxy to reduce the time taken to download dependencies.
Prerequisites:
- [Dependency Proxy](../../user/packages/dependency_proxy/index.md) enabled in the project's
group.
To reference the Dependency Proxy, configure the following variables in the `.gitlab-ci.yml` file:
- `CODE_QUALITY_IMAGE`
- `CODECLIMATE_PREFIX`
- `CODECLIMATE_REGISTRY_USERNAME`
- `CODECLIMATE_REGISTRY_PASSWORD`
For example:
```yaml
include:
- template: Code-Quality.gitlab-ci.yml
code_quality:
variables:
## You must add a trailing slash to `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`.
CODECLIMATE_PREFIX: $CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/
CODECLIMATE_REGISTRY_USERNAME: $CI_DEPENDENCY_PROXY_USER
CODECLIMATE_REGISTRY_PASSWORD: $CI_DEPENDENCY_PROXY_PASSWORD
```
## Implement a custom tool
You can integrate a custom tool into GitLab to provide Code Quality reports.
The Code Quality report artifact JSON file must contain an array of objects with the following
properties:
| Name | Description |
|-----------------------------------------------------------|-------------|
| `description` | A description of the code quality violation. |
| `check_name` | A unique name representing the static analysis check that emitted this issue. |
| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. |
| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). |
| `location.path` | The relative path to the file containing the code quality violation. |
| `location.lines.begin` or `location.positions.begin.line` | The line on which the code quality violation occurred. |
NOTE:
Although the Code Climate specification supports more properties, those are ignored by GitLab.
The GitLab parser does not allow a [byte order mark](https://en.wikipedia.org/wiki/Byte_order_mark)
at the beginning of the file.
To implement a custom Code Quality tool:
1. Define a job in your `.gitlab-ci.yml` file that generates the
[Code Quality report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality).
1. Configure the tool to generate the Code Quality report artifact as a JSON
file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types).
Example:
```json
[
{
"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 multiple tools
Code Quality combines the results from all jobs in a pipeline into a single `gl-code-quality-report.json` file. As a result, multiple individual tools can be used in a pipeline, either alongside, or in place of, the supported `Code-Quality.gitlab-ci.yml` template.
Here is an example that returns ESLint output in the necessary format:
```yaml
eslint:
image: node:18-alpine
script:
- npm ci
- npx eslint --format gitlab .
artifacts:
reports:
codequality: gl-code-quality-report.json
```
## Using Analysis Plugins
Code Quality functionality can be extended by using Code Climate
[Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines).
For example, to use the [SonarJava analyzer](https://docs.codeclimate.com/docs/sonar-java):
1. Add a file named `.codeclimate.yml` to the root of your repository
1. Add the [enablement code](https://docs.codeclimate.com/docs/sonar-java#enable-the-plugin)
for the plugin to the root of your repository to the `.codeclimate.yml` file:
```yaml
version: "2"
plugins:
sonar-java:
enabled: true
```
This adds SonarJava to the `plugins:` section of the
[default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template)
included in your project.
Changes to the `plugins:` section do not affect the `exclude_patterns` section of the default
`.codeclimate.yml`. See the Code Climate documentation on
[excluding files and folders](https://docs.codeclimate.com/docs/excluding-files-and-folders)
for more details.
Reference in New Issue View Git Blame Copy Permalink