diff options
Diffstat (limited to 'doc/user/project/merge_requests/code_quality.md')
| -rw-r--r-- | doc/user/project/merge_requests/code_quality.md | 83 |
1 files changed, 31 insertions, 52 deletions
diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 27642a9bd5d..19302572dc9 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -10,17 +10,22 @@ type: reference, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. -Ensuring your project's code stays simple, readable and easy to contribute to can be problematic. With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your -source code quality using GitLab Code Quality. +To ensure your project's code stays simple, readable, and easy to contribute to, +you can use [GitLab CI/CD](../../../ci/index.md) to analyze your source code quality. + +For example, while you're implementing a feature, you can run Code Quality reports +to analyze how your improvements are impacting your code's quality. You can +use this information to ensure that your changes are improving performance rather +than degrading it. Code Quality: -- Uses [Engines](https://docs.codeclimate.com/docs/list-of-engines) supported by Code Climate, which are +- Uses [plugins](https://docs.codeclimate.com/docs/list-of-engines) supported by Code Climate, which are free and open source. Code Quality does not require a Code Climate subscription. -- Runs in [pipelines](../../../ci/pipelines/index.md) using a Docker image built in the - [GitLab Code - Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). +- Runs in [pipelines](../../../ci/pipelines/index.md) by using a Docker image built in the + [GitLab Code Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project. +- Uses [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). - Can make use of a [template](#example-configuration). - Is available by using [Auto Code Quality](../../../topics/autodevops/stages.md#auto-code-quality), provided by [Auto DevOps](../../../topics/autodevops/index.md). - Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). @@ -54,42 +59,14 @@ See also the Code Climate list of [Supported Languages for Maintainability](http > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. -> - [Feature enhanced](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. +> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.1. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example:  -Previously, an indicator was displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view: - - - -To switch to the previous version of this feature, a GitLab administrator can run the following in a -[Rails console](../../../administration/operations/rails_console.md): - -```ruby -# For the instance -Feature.disable(:codequality_mr_diff_annotations) -# For a single project -Feature.disable(:codequality_mr_diff_annotations, Project.find(<project id>)) -``` - -## Use cases - -For instance, consider the following workflow: - -1. Your backend team member starts a new implementation for making a certain - feature in your app faster. -1. With Code Quality reports, they analyze how their implementation is impacting - the code quality. -1. The metrics show that their code degrades the quality by 10 points. -1. You ask a co-worker to help them with this modification. -1. They both work on the changes until Code Quality report displays no - degradations, only improvements. -1. You approve the merge request and authorize its deployment to staging. -1. Once verified, their changes are deployed to production. - ## Example configuration This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. @@ -111,7 +88,7 @@ include: The above example creates a `code_quality` job in your CI/CD pipeline which scans your source code for code quality issues. The report is saved as a -[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality) +[Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality) that you can later download and analyze. It's also possible to override the URL to the Code Quality image by @@ -262,13 +239,13 @@ was chosen as an operational decision by the runner team, instead of exposing `d ### Disabling the code quality job The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable -is present. Please refer to the CI/CD variables [documentation](../../../ci/variables/README.md) +is present. Please refer to the CI/CD variables [documentation](../../../ci/variables/index.md) to learn more about how to define one. To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom CI/CD variable. This can be done: -- For [the whole project](../../../ci/variables/README.md#custom-cicd-variables). +- For [the whole project](../../../ci/variables/index.md#custom-cicd-variables). - For a single pipeline run: 1. Go to **CI/CD > Pipelines** @@ -278,11 +255,11 @@ This can be done: ### Using with merge request pipelines The configuration provided by the Code Quality template does not let the `code_quality` job -run on [pipelines for merge requests](../../../ci/merge_request_pipelines/index.md). +run on [pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md). If pipelines for merge requests is enabled, the `code_quality:rules` must be redefined. -The template has these [`rules`](../../../ci/yaml/README.md#rules) for the `code quality` job: +The template has these [`rules`](../../../ci/yaml/index.md#rules) for the `code quality` job: ```yaml code_quality: @@ -292,7 +269,7 @@ code_quality: - if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH' ``` -If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflow)) +If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/index.md#workflow)) might look like this example: ```yaml @@ -334,7 +311,7 @@ do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the [Code Quality report - artifact](../../../ci/yaml/README.md#artifactsreportscodequality). + artifact](../../../ci/yaml/index.md#artifactsreportscodequality). 1. Configure your 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). @@ -342,13 +319,13 @@ do this: 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. | -| `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` | The line on which the code quality violation occurred. | +| Name | Description | +| ---------------------- | ----------------------------------------------------------------------------------------- | +| `description` | A description of the code quality violation. | +| `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. | Example: @@ -371,6 +348,8 @@ Example: NOTE: Although the Code Climate spec 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. ## Code Quality reports **(PREMIUM)** @@ -389,7 +368,7 @@ After the Code Quality job completes: - The full list of code quality violations generated by a pipeline is shown in the Code Quality tab of the Pipeline Details page. **(PREMIUM)** -### Generating an HTML report +## Generate an HTML report In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10), it is possible to generate an HTML report file by setting the `REPORT_FORMAT` @@ -535,7 +514,7 @@ This can be due to multiple reasons: - Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. -- The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD +- The [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. - The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. |