summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarcia Ramos <marcia@gitlab.com>2019-07-24 13:07:43 +0000
committerMarcia Ramos <marcia@gitlab.com>2019-07-24 13:07:43 +0000
commit0ef53789ea0f63598adf1377bd87c1944fd2ecd0 (patch)
tree99ae5b70fb43bafb1792bf153939b39488d1cd5e
parent3e4b15a37a09c7f5dd6fbbd54dc5507a929cba36 (diff)
parentea2a64c3ace77b23420e6bb60492af03492e0aa4 (diff)
downloadgitlab-ce-0ef53789ea0f63598adf1377bd87c1944fd2ecd0.tar.gz
Merge branch 'docs/enhance-code-quality-topics' into 'master'
Improve code quality documentation Closes #60725 See merge request gitlab-org/gitlab-ce!30545
-rw-r--r--doc/user/project/merge_requests/code_quality.md79
1 files changed, 59 insertions, 20 deletions
diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md
index ad1d79ae5b1..eb6e454062a 100644
--- a/doc/user/project/merge_requests/code_quality.md
+++ b/doc/user/project/merge_requests/code_quality.md
@@ -9,8 +9,18 @@ in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3.
With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your
source code quality using GitLab Code Quality.
-Code Quality uses [Code Climate Engines](https://codeclimate.com), which are
-free and open source. Code Quality doesn't require a Code Climate subscription.
+
+Code Quality:
+
+- Uses [Code Climate Engines](https://codeclimate.com), which are
+ free and open source. Code Quality doesn't require a Code Climate
+ subscription.
+- Runs in [pipelines](../../../ci/pipelines.md) using an Docker image built in
+ [GitLab Code
+ Quality](https://gitlab.com/gitlab-org/security-products/codequality) project.
+- Can make use of a [template](#template-and-examples).
+- Is available with [Auto
+ DevOps](../../../topics/autodevops/index.md#auto-code-quality-starter).
Going a step further, GitLab can show the Code Quality report right
in the merge request widget area:
@@ -21,22 +31,48 @@ in the merge request widget area:
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 degrade the quality in 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
+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 degrade the quality in 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.
+
+## Template and examples
+
+For most GitLab instances, the supplied template is the preferred method of
+implementing Code Quality. See
+[Analyze your project's Code Quality](../../../ci/examples/code_quality.md) for:
+
+- Information on the builtin GitLab Code Quality template.
+- Examples of manual GitLab configuration for earlier GitLab versions.
-## How it works
+## Configuring jobs using variables
-First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the
-[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter).
+The Code Quality job supports environment variables that users can set to
+configure job execution at runtime.
-The Code Quality report artifact is a subset of the
-[Code Climate spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types).
-It must be a JSON file containing an array of objects with the following properties:
+For a list of available environment variables, see
+[Environment variables](https://gitlab.com/gitlab-org/security-products/codequality/blob/master/README.md#environment-variables).
+
+## Implementing a custom tool
+
+It's possible to have a custom tool provide Code Quality reports in GitLab. To
+do this:
+
+1. Define a job in your `.gitlab-ci.yml` file that generates the
+ [Code Quality report
+ artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter).
+1. Configure your tool to generate the Code Quality report artifact as a JSON
+ file that implements subset of the [Code Climate
+ spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types).
+
+The Code Quality report artifact JSON file must contain an array of objects
+with the following properties:
| Name | Description |
| ---------------------- | -------------------------------------------------------------------------------------- |
@@ -63,13 +99,16 @@ Example:
```
NOTE: **Note:**
-Although the Code Climate spec supports more properties, those are ignored by GitLab.
+Although the Code Climate spec supports more properties, those are ignored by
+GitLab.
+
+## Code Quality reports
-For more information on what the Code Quality job should look like, check the
-example on [analyzing a project's code quality](../../../ci/examples/code_quality.md).
+Once the Code Quality job has completed, GitLab:
-GitLab then checks this report, compares the metrics between the source and target
-branches, and shows the information right on the merge request.
+- Checks the generated report.
+- Compares the metrics between the source and target branches.
+- Shows the information right on the merge request.
If multiple jobs in a pipeline generate a code quality artifact, only the artifact from
the last created job (the job with the largest job ID) is used. To avoid confusion,