Commit 7de01b0c authored by Evan Read's avatar Evan Read

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

Move artifact reports from yaml reference to job artifacts doc

See merge request gitlab-org/gitlab!30465
parents 4827484e a6c3acb7
......@@ -55,6 +55,7 @@ CentOS
Chatops
Citrix
Cloudwatch
Cobertura
Cognito
colocated
colocating
......@@ -85,6 +86,7 @@ discoverability
Disqus
Dockerfile
Dockerfiles
Dotenv
downvoted
downvotes
Dpl
......
......@@ -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).
......
......@@ -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
......
......@@ -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:
......
......@@ -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
......
This diff is collapsed.
......@@ -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`,
......
......@@ -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).
......
......@@ -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
......
......@@ -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.
......
......@@ -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.
......
......@@ -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)
......
......@@ -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.
......
......@@ -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)
......
......@@ -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.
......
......@@ -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).
......
......@@ -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:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment