Merge branch 'docs-artifacts-reports' into 'master'

Move artifact reports from yaml reference to job artifacts doc

See merge request gitlab-org/gitlab!30465

doc/.vale/gitlab/spelling-exceptions.txt

@@ -55,6 +55,7 @@ CentOS
 Chatops
 Citrix
 Cloudwatch
+Cobertura
 Cognito
 colocated
 colocating
@@ -85,6 +86,7 @@ discoverability
 Disqus
 Dockerfile
 Dockerfiles
+Dotenv
 downvoted
 downvotes
 Dpl

doc/ci/environments.md

@@ -173,7 +173,7 @@ GitLab supports [dotenv](https://github.com/bkeepers/dotenv) file as the format,
 and expands the `environment:url` value with variables defined in the dotenv file.
 
 To use this feature, specify the
-[`artifacts:reports:dotenv`](yaml/README.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
+[`artifacts:reports:dotenv`](pipelines/job_artifacts.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70jDXtOf4Ig).

doc/ci/junit_test_reports.md

@@ -68,7 +68,7 @@ For a list of supported languages on JUnit tests, check the
 [Wikipedia article](https://en.wikipedia.org/wiki/JUnit#Ports).
 
 To enable the JUnit reports in merge requests, you need to add
-[`artifacts:reports:junit`](yaml/README.md#artifactsreportsjunit)
+[`artifacts:reports:junit`](pipelines/job_artifacts.md#artifactsreportsjunit)
 in `.gitlab-ci.yml`, and specify the path(s) of the generated test reports.
 
 In the following examples, the job in the `test` stage runs and GitLab

doc/ci/metrics_reports.md

@@ -34,7 +34,7 @@ All values are considered strings and string compare is used to find differences
 
 ## How to set it up
 
-Add a job that creates a [metrics report](yaml/README.md#artifactsreportsmetrics-premium) (default filename: `metrics.txt`). The file should conform to the [OpenMetrics](https://openmetrics.io/) format.
+Add a job that creates a [metrics report](pipelines/job_artifacts.md#artifactsreportsmetrics-premium) (default filename: `metrics.txt`). The file should conform to the [OpenMetrics](https://openmetrics.io/) format.
 
 For example:
 

doc/ci/pipelines/job_artifacts.md

@@ -198,6 +198,208 @@ To erase a job:
 
 In order to retrieve a job artifact of a different project, you might need to use a private token in order to [authenticate and download](../../api/jobs.md#get-job-artifacts) the artifacts.
 
+## `artifacts:reports`
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390) in GitLab 11.2.
+> - Requires GitLab Runner 11.2 and above.
+
+The `artifacts:reports` keyword is used for collecting test reports, code quality
+reports, and security reports from jobs. It also exposes these reports in GitLab's
+UI (merge requests, pipeline views, and security dashboards).
+
+NOTE: **Note:**
+The test reports are collected regardless of the job results (success or failure).
+You can use [`artifacts:expire_in`](../yaml/README.md#artifactsexpire_in) to set up an expiration
+date for their artifacts.
+
+NOTE: **Note:**
+If you also want the ability to browse the report output files, include the
+[`artifacts:paths`](../yaml/README.md#artifactspaths) keyword.
+
+### `artifacts:reports:junit`
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390) in GitLab 11.2.
+> - Requires GitLab Runner 11.2 and above.
+
+The `junit` report collects [JUnit XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html)
+as artifacts. Although JUnit was originally developed in Java, there are many
+[third party ports](https://en.wikipedia.org/wiki/JUnit#Ports) for other
+languages like JavaScript, Python, Ruby, and so on.
+
+See [JUnit test reports](../junit_test_reports.md) for more details and examples.
+Below is an example of collecting a JUnit XML file from Ruby's RSpec test tool:
+
+```yaml
+rspec:
+  stage: test
+  script:
+  - bundle install
+  - rspec --format RspecJunitFormatter --out rspec.xml
+  artifacts:
+    reports:
+      junit: rspec.xml
+```
+
+The collected JUnit reports will be uploaded to GitLab as an artifact and will
+be automatically shown in merge requests.
+
+NOTE: **Note:**
+In case the JUnit tool you use exports to multiple XML files, you can specify
+multiple test report paths within a single job and they will be automatically
+concatenated into a single file. Use a filename pattern (`junit: rspec-*.xml`),
+an array of filenames (`junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]`), or a
+combination thereof (`junit: [rspec.xml, test-results/TEST-*.xml]`).
+
+### `artifacts:reports:dotenv`
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/17066) in GitLab 12.9.
+> - Requires GitLab Runner 11.5 and later.
+
+The `dotenv` report collects a set of environment variables as artifacts.
+
+The collected variables are registered as runtime-created variables of the job,
+which is useful to [set dynamic environment URLs after a job finishes](../environments.md#set-dynamic-environment-urls-after-a-job-finishes).
+It's not available for download through the web interface.
+
+There are a couple of limitations on top of the [original Dotenv rules](https://github.com/motdotla/dotenv#rules).
+
+- The variable key can contain only letters, digits and underscore ('_').
+- The size of the Dotenv file must be smaller than 5 kilobytes.
+- The number of variables must be less than 10.
+- It does not support variable substitution in the Dotenv file itself.
+- It does not support empty lines and comments (`#`) in Dotenv file.
+- It does not support quote escape, spaces in a quote, a new line expansion in a quote, in Dotenv file.
+
+### `artifacts:reports:cobertura`
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3708) in GitLab 12.9.
+> - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above.
+
+The `cobertura` report collects [Cobertura coverage XML files](../../user/project/merge_requests/test_coverage_visualization.md).
+The collected Cobertura coverage reports will be uploaded to GitLab as an artifact
+and will be automatically shown in merge requests.
+
+Cobertura was originally developed for Java, but there are many
+third party ports for other languages like JavaScript, Python, Ruby, and so on.
+
+### `artifacts:reports:terraform`
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/207527) in GitLab 12.10.
+> - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above.
+
+The `terraform` report collects Terraform `tfplan.json` files. The collected Terraform
+plan reports will be uploaded to GitLab as artifacts and will be automatically shown
+in merge requests.
+
+### `artifacts:reports:codequality` **(STARTER)**
+
+> - Introduced in GitLab 11.5.
+> - Requires GitLab Runner 11.5 and above.
+
+The `codequality` report collects [CodeQuality issues](../../user/project/merge_requests/code_quality.md)
+as artifacts.
+
+The collected Code Quality report will be uploaded to GitLab as an artifact and will
+be summarized in merge requests. It's not available for download through the web interface.
+
+### `artifacts:reports:sast` **(ULTIMATE)**
+
+> - Introduced in GitLab 11.5.
+> - Requires GitLab Runner 11.5 and above.
+
+The `sast` report collects [SAST vulnerabilities](../../user/application_security/sast/index.md)
+as artifacts.
+
+The collected SAST report will be uploaded to GitLab as an artifact and will be summarized
+in the merge requests and pipeline view. It's also used to provide data for security
+dashboards. It's not available for download through the web interface.
+
+### `artifacts:reports:dependency_scanning` **(ULTIMATE)**
+
+> - Introduced in GitLab 11.5.
+> - Requires GitLab Runner 11.5 and above.
+
+The `dependency_scanning` report collects [Dependency Scanning vulnerabilities](../../user/application_security/dependency_scanning/index.md)
+as artifacts.
+
+The collected Dependency Scanning report will be uploaded to GitLab as an artifact and will
+be summarized in the merge requests and pipeline view. It's also used to provide data for security
+dashboards. It's not available for download through the web interface.
+
+### `artifacts:reports:container_scanning` **(ULTIMATE)**
+
+> - Introduced in GitLab 11.5.
+> - Requires GitLab Runner 11.5 and above.
+
+The `container_scanning` report collects [Container Scanning vulnerabilities](../../user/application_security/container_scanning/index.md)
+as artifacts.
+
+The collected Container Scanning report will be uploaded to GitLab as an artifact and will
+be summarized in the merge requests and pipeline view. It's also used to provide data for security
+dashboards. It's not available for download through the web interface.
+
+### `artifacts:reports:dast` **(ULTIMATE)**
+
+> - Introduced in GitLab 11.5.
+> - Requires GitLab Runner 11.5 and above.
+
+The `dast` report collects [DAST vulnerabilities](../../user/application_security/dast/index.md)
+as artifacts.
+
+The collected DAST report will be uploaded to GitLab as an artifact and will
+be summarized in the merge requests and pipeline view. It's also used to provide data for security
+dashboards. It's not available for download through the web interface.
+
+### `artifacts:reports:license_management` **(ULTIMATE)**
+
+> - Introduced in GitLab 11.5.
+> - Requires GitLab Runner 11.5 and above.
+
+CAUTION: **Warning:**
+This artifact is still valid but is **deprecated** in favor of the
+[artifacts:reports:license_scanning](../pipelines/job_artifacts.md#artifactsreportslicense_scanning-ultimate)
+introduced in GitLab 12.8.
+
+The `license_management` report collects [Licenses](../../user/compliance/license_compliance/index.md)
+as artifacts.
+
+The collected License Compliance report will be uploaded to GitLab as an artifact and will
+be summarized in the merge requests and pipeline view. It's also used to provide data for security
+dashboards. It's not available for download through the web interface.
+
+### `artifacts:reports:license_scanning` **(ULTIMATE)**
+
+> - Introduced in GitLab 12.8.
+> - Requires GitLab Runner 11.5 and above.
+
+The `license_scanning` report collects [Licenses](../../user/compliance/license_compliance/index.md)
+as artifacts.
+
+The License Compliance report will be uploaded to GitLab as an artifact and will
+be automatically shown in merge requests, pipeline view and provide data for security
+dashboards.
+
+### `artifacts:reports:performance` **(PREMIUM)**
+
+> - Introduced in GitLab 11.5.
+> - Requires GitLab Runner 11.5 and above.
+
+The `performance` report collects [Performance metrics](../../user/project/merge_requests/browser_performance_testing.md)
+as artifacts.
+
+The collected Performance report will be uploaded to GitLab as an artifact and will
+be automatically shown in merge requests. It's not available for download through the web interface.
+
+### `artifacts:reports:metrics` **(PREMIUM)**
+
+> Introduced in GitLab 11.10.
+
+The `metrics` report collects [Metrics](../metrics_reports.md)
+as artifacts.
+
+The collected Metrics report will be uploaded to GitLab as an artifact and will
+be automatically shown in merge requests. It's not available for download through the web interface.
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues

doc/development/integrations/secure.md

@@ -53,7 +53,7 @@ so the [`allow_failure`](../../ci/yaml/README.md#allow_failure) parameter should
 ### Artifacts
 
 Scanning jobs must declare a report that corresponds to the type of scanning they perform,
-using the [`artifacts:reports`](../../ci/yaml/README.md#artifactsreports) keyword.
+using the [`artifacts:reports`](../../ci/pipelines/job_artifacts.md#artifactsreports) keyword.
 Valid reports are: `dependency_scanning`, `container_scanning`, `dast`, and `sast`.
 
 For example, here is the definition of a SAST job that generates a file named `gl-sast-report.json`,
@@ -178,7 +178,7 @@ It is recommended to name the output file after the type of scanning, and to use
 Since all Secure reports are JSON files, it is recommended to use `.json` as a file extension.
 For instance, a suggested file name for a Dependency Scanning report is `gl-dependency-scanning.json`.
 
-The [`artifacts:reports`](../../ci/yaml/README.md#artifactsreports) keyword
+The [`artifacts:reports`](../../ci/pipelines/job_artifacts.md#artifactsreports) keyword
 of the job definition must be consistent with the file path where the Security report is written.
 For instance, if a Dependency Scanning analyzer writes its report to the CI project directory,
 and if this report file name is `depscan.json`,

doc/development/integrations/secure_partner_integration.md

@@ -68,7 +68,7 @@ and complete an intgration with the Secure stage.
 1. Ensure your pipeline jobs create a report artifact that GitLab can process
    to successfully display your own product's results with the rest of GitLab.
    - See detailed [technical directions](secure.md) for this step.
-   - Read more about [job report artifacts](../../ci/yaml/README.md#artifactsreports).
+   - Read more about [job report artifacts](../../ci/pipelines/job_artifacts.md#artifactsreports).
    - Read about [job artifacts](../../user/project/pipelines/job_artifacts.md).
    - Your report artifact must be in one of our currently supported formats.
      For more information, see the [documentation on reports](secure.md#report).

doc/user/application_security/container_scanning/index.md

@@ -103,7 +103,7 @@ The included template will:
    and scan it for possible vulnerabilities.
 
 The results will be saved as a
-[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate)
+[Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning-ultimate)
 that you can later download and analyze.
 Due to implementation limitations, we always take the latest Container Scanning
 artifact available. Behind the scenes, the

doc/user/application_security/dast/index.md

@@ -101,7 +101,7 @@ The included template will create a `dast` job in your CI/CD pipeline and scan
 your project's source code for possible vulnerabilities.
 
 The results will be saved as a
-[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate)
+[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate)
 that you can later download and analyze. Due to implementation limitations we
 always take the latest DAST artifact available. Behind the scenes, the
 [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast)
@@ -147,7 +147,7 @@ variables:
 ```
 
 The results will be saved as a
-[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate)
+[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate)
 that you can later download and analyze.
 Due to implementation limitations, we always take the latest DAST artifact available.
 

doc/user/application_security/dependency_scanning/index.md

@@ -91,7 +91,7 @@ The included template will create a `dependency_scanning` job in your CI/CD
 pipeline and scan your project's source code for possible vulnerabilities.
 
 The results will be saved as a
-[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate)
+[Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate)
 that you can later download and analyze. Due to implementation limitations, we
 always take the latest Dependency Scanning artifact available.
 

doc/user/application_security/sast/index.md

@@ -118,7 +118,7 @@ The included template will create a `sast` job in your CI/CD pipeline and scan
 your project's source code for possible vulnerabilities.
 
 The results will be saved as a
-[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate)
+[SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast-ultimate)
 that you can later download and analyze. Due to implementation limitations, we
 always take the latest SAST artifact available. Behind the scenes, the
 [GitLab SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast)

doc/user/application_security/security_dashboard/index.md

@@ -30,7 +30,7 @@ To use the instance, group, project, or pipeline security dashboard:
 
 1. At least one project inside a group must be configured with at least one of
    the [supported reports](#supported-reports).
-1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports).
+1. The configured jobs must use the [new `reports` syntax](../../../ci/pipelines/job_artifacts.md#artifactsreports).
 1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used.
    If you're using the shared Runners on GitLab.com, this is already the case.
 

doc/user/compliance/license_compliance/index.md

@@ -112,7 +112,7 @@ so you're advised to migrate to the `license_scanning` job and used the new
 `License-Scanning.gitlab-ci.yml` template.
 
 The results will be saved as a
-[License Compliance report artifact](../../../ci/yaml/README.md#artifactsreportslicense_scanning-ultimate)
+[License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning-ultimate)
 that you can later download and analyze. Due to implementation limitations, we
 always take the latest License Compliance artifact available. Behind the scenes, the
 [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/license-management)

doc/user/project/merge_requests/browser_performance_testing.md

@@ -42,7 +42,7 @@ For instance, consider the following workflow:
 ## How it works
 
 First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the
-[Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance-premium).
+[Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium).
 For more information on how the Performance job should look like, check the
 example on [Configuring Browser Performance Testing](#configuring-browser-performance-testing).
 
@@ -100,7 +100,7 @@ It also requires GitLab Runner 11.5 or later. For earlier versions, use the
 The above example will create a `performance` job in your CI/CD pipeline and will run
 sitespeed.io against the webpage you defined in `URL` to gather key metrics.
 The [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance)
-is downloaded in order to save the report as a [Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance-premium)
+is downloaded in order to save the report as a [Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium)
 that you can later download and analyze. Due to implementation limitations we always
 take the latest Performance artifact available.
 

doc/user/project/merge_requests/code_quality.md

@@ -79,7 +79,7 @@ include:
 
 The above example will create a `code_quality` job in your CI/CD pipeline which
 will scan your source code for code quality issues. The report will be saved as a
-[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter)
+[Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality-starter)
 that you can later download and analyze. Due to implementation limitations we always
 take the latest Code Quality artifact available.
 
@@ -239,7 +239,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-starter).
+   artifact](../../../ci/pipelines/job_artifacts.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/platform/blob/master/spec/analyzers/SPEC.md#data-types).

doc/user/project/merge_requests/test_coverage_visualization.md

@@ -17,14 +17,14 @@ MR is merged.
 ## How test coverage visualization works
 
 Collecting the coverage information is done via GitLab CI/CD's
-[artifacts reports feature](../../../ci/yaml/README.md#artifactsreports).
+[artifacts reports feature](../../../ci/pipelines/job_artifacts.md#artifactsreports).
 You can specify one or more coverage reports to collect, including wildcard paths.
 GitLab will then take the coverage information in all the files and combine it
 together.
 
 For the coverage analysis to work, you have to provide a properly formatted
 [Cobertura XML](https://cobertura.github.io/cobertura/) report to
-[`artifacts:reports:cobertura`](../../../ci/yaml/README.md#artifactsreportscobertura).
+[`artifacts:reports:cobertura`](../../../ci/pipelines/job_artifacts.md#artifactsreportscobertura).
 This format was originally developed for Java, but most coverage analysis frameworks
 for other languages have plugins to add support for it, like: