Skip to content

G
gitlab-ce
Commit aef772d6 authored by Marcel Amirault's avatar Marcel Amirault
Browse files
Options

Merge branch 'selhorn-job-artifacts-1' into 'master' 

Edited for style

See merge request gitlab-org/gitlab!57185
parents 4819c058 f1030c76
Hide whitespace changes
Inline Side-by-side
Showing with 177 additions and 217 deletions
doc/administration/job_artifacts.md
View file @ aef772d6
......@@ -89,7 +89,7 @@ _The artifacts are stored by default in
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1762) in
> [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
> - Since version 9.5, artifacts are [browsable](../ci/pipelines/job_artifacts.md#browsing-artifacts),
> - Since version 9.5, artifacts are [browsable](../ci/pipelines/job_artifacts.md#download-job-artifacts),
> when object storage is enabled. 9.4 lacks this feature.
> - Since version 10.6, available in [GitLab Free](https://about.gitlab.com/pricing/).
> - Since version 11.0, we support `direct_upload` to S3.
......@@ -509,7 +509,7 @@ If you need to manually remove job artifacts associated with multiple jobs while
NOTE:
This step also erases artifacts that users have chosen to
["keep"](../ci/pipelines/job_artifacts.md#browsing-artifacts).
["keep"](../ci/pipelines/job_artifacts.md#download-job-artifacts).
```ruby
builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago)
......
doc/administration/pages/index.md
View file @ aef772d6
......@@ -487,7 +487,7 @@ internet connectivity is gated by a proxy. To use a proxy for GitLab Pages:
### Using a custom Certificate Authority (CA)
When using certificates issued by a custom CA, [Access Control](../../user/project/pages/pages_access_control.md#gitlab-pages-access-control) and
the [online view of HTML job artifacts](../../ci/pipelines/job_artifacts.md#browsing-artifacts)
the [online view of HTML job artifacts](../../ci/pipelines/job_artifacts.md#download-job-artifacts)
fails to work if the custom CA is not recognized.
This usually results in this error:
......
doc/ci/pipelines/job_artifacts.md
View file @ aef772d6
......@@ -8,25 +8,19 @@ type: reference, howto
# Job artifacts
> - Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format changed to `ZIP`, and it's now possible to browse its contents, with the added ability of downloading the files separately.
> - In GitLab 8.17, builds were renamed to jobs.
> - The artifacts browser is available only for new artifacts that are sent to GitLab using GitLab Runner version 1.0 and up. You cannot browse old artifacts already uploaded to GitLab.
> Introduced in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16675), artifacts in internal and private projects can be previewed when [GitLab Pages access control](../../administration/pages/index.md#access-control) is enabled.
Job artifacts are a list of files and directories created by a job
once it finishes. This feature is [enabled by default](../../administration/job_artifacts.md) in all
GitLab installations.
Jobs can output an archive of files and directories. This output is known as a job artifact.
Job artifacts created by GitLab Runner are uploaded to GitLab and are downloadable as a single archive using the GitLab UI or the [GitLab API](../../api/job_artifacts.md#get-job-artifacts).
You can download job artifacts by using the GitLab UI or the [API](../../api/job_artifacts.md#get-job-artifacts).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s).
Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII).
## Defining artifacts in `.gitlab-ci.yml`
## Define artifacts in the `.gitlab-ci.yml` file
A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
the following:
This example shows how to configure your `.gitlab-ci.yml` file to create job artifacts:
```yaml
pdf:
......@@ -38,19 +32,169 @@ pdf:
```
A job named `pdf` calls the `xelatex` command to build a PDF file from the
latex source file `mycv.tex`. We then define the `artifacts` paths which in
turn are defined with the `paths` keyword. All paths to files and directories
are relative to the repository that was cloned during the build.
LaTeX source file, `mycv.tex`.
By default, the artifacts upload when the job succeeds. You can also set artifacts to upload
when the job fails, or always, by using [`artifacts:when`](../yaml/README.md#artifactswhen)
keyword. GitLab keeps these uploaded artifacts for 1 week, as defined
by the `expire_in` definition. You can keep the artifacts from expiring
via the [web interface](#browsing-artifacts). If the expiry time is not defined, it defaults
to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration).
The `paths` keyword determines which files to add to the job artifacts.
All paths to files and directories are relative to the repository where the job was created.
For more examples on artifacts, follow the [artifacts reference in
`.gitlab-ci.yml`](../yaml/README.md#artifacts).
The `expire_in` keyword determines how long GitLab keeps the job artifacts.
You can also [use the UI to keep job artifacts from expiring](#download-job-artifacts).
If `expire_in` is not defined, the
[instance-wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration)
is used.
For more examples, view the [keyword reference for the `.gitlab-ci.yml` file](../yaml/README.md#artifacts).
## Download job artifacts
You can download job artifacts or view the job archive:
- On the **Pipelines** page, to the right of the pipeline:
![Job artifacts in Pipelines page](img/job_artifacts_pipelines_page.png)
- On the **Jobs** page, to the right of the job:
![Job artifacts in Builds page](img/job_artifacts_builds_page.png)
- On a job's detail page. The **Keep** button indicates an `expire_in` value was set:
![Job artifacts browser button](img/job_artifacts_browser_button.png)
- On a merge request, by the pipeline details:
![Job artifacts in Merge Request](img/job_artifacts_merge_request.png)
- When browsing an archive:
![Job artifacts browser](img/job_artifacts_browser.png)
If [GitLab Pages](../../administration/pages/index.md) is enabled in the project, you can preview
HTML files in the artifacts directly in your browser. If the project is internal or private, you must
enable [GitLab Pages access control](../../administration/pages/index.md#access-control) to preview
HTML files.
## View failed job artifacts
If the latest job has failed to upload the artifacts, you can see that
information in the UI.
![Latest artifacts button](img/job_latest_artifacts_browser.png)
## Erase job artifacts
WARNING:
This is a destructive action that leads to data loss. Use with caution.
You can erase a single job, which also removes the job's
artifacts and log. You must be:
- The owner of the job.
- A [Maintainer](../../user/permissions.md#gitlab-cicd-permissions) of the project.
To erase a job:
1. Go to a job's detail page.
1. At the top right of the job's log, select the trash icon.
1. Confirm the deletion.
## Use GitLab CI/CD to retrieve job artifacts for private projects
To retrieve a job artifact from a different project, you might need to use a
private token to [authenticate and download](../../api/job_artifacts.md#get-job-artifacts)
the artifact.
## The latest job artifacts
Job artifacts created in the most recent successful pipeline for a specific ref
are considered the latest artifacts. If you run two types of pipelines for the same ref,
timing determines which artifacts are the latest.
For example, if a merge request creates a branch pipeline at the same time as
a scheduled pipeline, the pipeline that finished most recently creates the latest job artifact.
In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201784) and later, artifacts
for [parent and child pipelines](../parent_child_pipelines.md) are searched in hierarchical
order from parent to child. For example, if both parent and child pipelines have a
job with the same name, the job artifact from the parent pipeline is returned.
## Access the latest job artifacts by URL
You can download the latest job artifacts by using a URL.
To download the whole artifacts archive:
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/download?job=<job_name>
```
To download a single file from the artifacts:
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/raw/<path_to_file>?job=<job_name>
```
For example, to download the latest artifacts of the job named `coverage` of
the `master` branch of the `gitlab` project that belongs to the `gitlab-org`
namespace:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/download?job=coverage
```
To download the file `coverage/index.html` from the same artifacts:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/raw/coverage/index.html?job=coverage
```
To browse the latest job artifacts:
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name>
```
For example:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/browse?job=coverage
```
There is also a URL for specific files, including HTML files that
are shown in [GitLab Pages](../../administration/pages/index.md):
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name>
```
For example, when a job `coverage` creates the artifact `htmlcov/index.html`:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/file/htmlcov/index.html?job=coverage
```
### Keep artifacts from most recent successful jobs
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4.
> - [Made optional with a CI/CD setting](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8.
By default, the latest job artifacts from the most recent successful jobs are never deleted.
If a job is configured with [`expire_in`](../yaml/README.md#artifactsexpire_in),
its artifacts only expire if a more recent artifact exists.
Keeping the latest artifacts can use a large amount of storage space in projects
with a lot of jobs or large artifacts. If the latest artifacts are not needed in
a project, you can disable this behavior to save space:
1. Go to the project's **Settings > CI/CD > Artifacts**.
1. Clear the **Keep artifacts from most recent successful jobs** checkbox.
You can disable this behavior for all projects on a self-managed instance in the
[instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
When you disable the feature, the latest artifacts do not immediately expire.
A new pipeline must run before the latest artifacts can expire and be deleted.
### `artifacts:reports`
......@@ -306,191 +450,7 @@ The collected Requirements report uploads to GitLab as an artifact and
existing [requirements](../../user/project/requirements/index.md) are
marked as Satisfied.
## Browsing artifacts
> - From GitLab 9.2, PDFs, images, videos, and other formats can be previewed directly in the job artifacts browser without the need to download them.
> - Introduced in [GitLab 10.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14399), HTML files in a public project can be previewed directly in a new tab without the need to download them when [GitLab Pages](../../administration/pages/index.md) is enabled. The same applies for textual formats (currently supported extensions: `.txt`, `.json`, and `.log`).
> - Introduced in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16675), artifacts in internal and private projects can be previewed when [GitLab Pages access control](../../administration/pages/index.md#access-control) is enabled.
After a job finishes, if you visit the job's specific page, there are three
buttons. You can download the artifacts archive or browse its contents, whereas
the **Keep** button appears only if you've set an [expiry date](../yaml/README.md#artifactsexpire_in) to the
artifacts in case you changed your mind and want to keep them.
![Job artifacts browser button](img/job_artifacts_browser_button.png)
The archive browser shows the name and the actual file size of each file in the
archive. If your artifacts contained directories, then you're also able to
browse inside them.
Below you can see what browsing looks like. In this case we have browsed inside
the archive and at this point there is one directory, a couple files, and
one HTML file that you can view directly online when
[GitLab Pages](../../administration/pages/index.md) is enabled (opens in a new tab).
Select artifacts in internal and private projects can only be previewed when
[GitLab Pages access control](../../administration/pages/index.md#access-control) is enabled.
![Job artifacts browser](img/job_artifacts_browser.png)
## Downloading artifacts
If you need to download an artifact or the whole archive, there are buttons in various places
in the GitLab UI to do this:
1. While on the pipelines page, you can see the download icon for each job's
artifacts and archive in the right corner:
![Job artifacts in Pipelines page](img/job_artifacts_pipelines_page.png)
1. While on the **Jobs** page, you can see the download icon for each job's
artifacts and archive in the right corner:
![Job artifacts in Builds page](img/job_artifacts_builds_page.png)
1. While inside a specific job, you're presented with a download button
along with the one that browses the archive:
![Job artifacts browser button](img/job_artifacts_browser_button.png)
1. While on the details page of a merge request, you can see the download
icon for each job's artifacts on the right side of the merge request widget:
![Job artifacts in Merge Request](img/job_artifacts_merge_request.png)
1. And finally, when browsing an archive you can see the download button at
the top right corner:
![Job artifacts browser](img/job_artifacts_browser.png)
## Downloading the latest artifacts
It's possible to download the latest artifacts of a job via a well known URL
so you can use it for scripting purposes.
NOTE:
The latest artifacts are created by jobs in the **most recent** successful pipeline
for the specific ref. If you run two types of pipelines for the same ref, timing determines the latest
artifact. For example, if a merge request creates a branch pipeline at the same time as a scheduled pipeline, the pipeline that completed most recently creates the latest artifact.
In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201784) and later, artifacts
for [parent and child pipelines](../parent_child_pipelines.md) are searched in hierarchical
order from parent to child. For example, if both parent and child pipelines have a
job with the same name, the artifact from the parent pipeline is returned.
Artifacts for other pipelines can be accessed with direct access to them.
The structure of the URL to download the whole artifacts archive is the following:
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/download?job=<job_name>
```
To download a single file from the artifacts use the following URL:
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/raw/<path_to_file>?job=<job_name>
```
For example, to download the latest artifacts of the job named `coverage` of
the `master` branch of the `gitlab` project that belongs to the `gitlab-org`
namespace, the URL would be:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/download?job=coverage
```
To download the file `coverage/index.html` from the same
artifacts use the following URL:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/raw/coverage/index.html?job=coverage
```
There is also a URL to browse the latest job artifacts:
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name>
```
For example:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/browse?job=coverage
```
There is also a URL to specific files, including HTML files that
are shown in [GitLab Pages](../../administration/pages/index.md):
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name>
```
For example, when a job `coverage` creates the artifact `htmlcov/index.html`,
you can access it at:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/file/htmlcov/index.html?job=coverage
```
The latest builds are also exposed in the UI in various places. Specifically,
look for the download button in:
- The main project's page
- The branches page
- The tags page
If the latest job has failed to upload the artifacts, you can see that
information in the UI.
![Latest artifacts button](img/job_latest_artifacts_browser.png)
## Erasing artifacts
WARNING:
This is a destructive action that leads to data loss. Use with caution.
You can erase a single job via the UI, which also removes the job's
artifacts and trace, if you are:
- The owner of the job.
- A [Maintainer](../../user/permissions.md#gitlab-cicd-permissions) of the project.
To erase a job:
1. Navigate to a job's page.
1. Click the trash icon at the top right of the job's trace.
1. Confirm the deletion.
## Retrieve artifacts of private projects when using GitLab CI
To retrieve a job artifact from a different project, you might need to use a
private token to [authenticate and download](../../api/job_artifacts.md#get-job-artifacts)
the artifact.
## Keep artifacts from most recent successful jobs
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4.
> - [Made optional with a CI/CD setting](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8.
By default, the latest artifacts from the most recent successful jobs are never deleted.
If a job is configured with [`expire_in`](../yaml/README.md#artifactsexpire_in),
its artifacts only expire if a more recent artifact exists.
Keeping the latest artifacts can use a large amount of storage space in projects
with a lot of jobs or large artifacts. If the latest artifacts are not needed in
a project, you can disable this behavior to save space:
1. Navigate to **Settings > CI/CD > Artifacts**.
1. Uncheck **Keep artifacts from most recent successful jobs**.
You can disable this behavior for all projects on a self-managed instance in the
[instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). **(CORE ONLY)**
When you disable the feature, the latest artifacts do not immediately expire.
A new pipeline must run before the latest artifacts can expire and be deleted.
## Troubleshooting
## Troubleshooting job artifacts
### Error message `No files to upload`
......
doc/ci/yaml/README.md
View file @ aef772d6
......@@ -3239,7 +3239,7 @@ Note the following:
- Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`.
- A maximum of 10 job artifacts per merge request can be exposed.
- Glob patterns are unsupported.
- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#browsing-artifacts) if there is more than
- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#download-job-artifacts) if there is more than
one file in the directory.
- For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`,
and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is:
......@@ -3508,7 +3508,7 @@ deploy:
If the artifacts of the job that is set as a dependency are
[expired](#artifactsexpire_in) or
[erased](../pipelines/job_artifacts.md#erasing-artifacts), then
[erased](../pipelines/job_artifacts.md#erase-job-artifacts), then
the dependent job fails.
You can ask your administrator to
......
doc/user/application_security/coverage_fuzzing/index.md
View file @ aef772d6
......@@ -141,7 +141,7 @@ The `gitlab-cov-fuzz` tool emits a JSON report file. For more information, see t
[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json).
You can download the JSON report file from the CI pipelines page. For more information, see
[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#downloading-artifacts).
[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts).
Here's an example coverage fuzzing report:
......
doc/user/application_security/sast/index.md
View file @ aef772d6
......@@ -536,7 +536,7 @@ The SAST tool emits a JSON report file. For more information, see the
[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json).
The JSON report file can be downloaded from the CI pipelines page, or the
pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/pipelines/job_artifacts.md#defining-artifacts-in-gitlab-ciyml) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md).
pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/README.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md).
Here's an example SAST report:
......
doc/user/project/merge_requests/accessibility_testing.md
View file @ aef772d6
......@@ -57,7 +57,7 @@ include:
creates an `a11y` job in your CI/CD pipeline, runs
Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each.
The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#browsing-artifacts).
The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts).
A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports.
It includes report data for all URLs scanned.
......
doc/user/project/merge_requests/code_quality.md
View file @ aef772d6
......@@ -355,7 +355,7 @@ After the Code Quality job completes:
The Code Quality widget in the merge request compares the reports from the base and head of the branch,
then lists any violations that are resolved or created when the branch is merged.
- The full JSON report is available as a
[downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts)
[downloadable artifact](../../../ci/pipelines/job_artifacts.md#download-job-artifacts)
for the `code_quality` job.
- The full list of code quality violations generated by a pipeline is shown in the
Code Quality tab of the Pipeline Details page. **(PREMIUM)**
......
doc/user/project/pages/introduction.md
View file @ aef772d6
......@@ -290,7 +290,7 @@ This problem most likely results from a missing `index.html` file in the public
a 404 is encountered, confirm that the public directory contains an `index.html` file. If the file contains a different name
such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-name/test.html`.
The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/pipelines/job_artifacts.md#browsing-artifacts) from the latest pipeline.
The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) from the latest pipeline.
Files listed under the public directory can be accessed through the Pages URL for the project.
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7