debian-mirror-gitlab/doc/ci/pipelines/job_artifacts.md

432 lines
13 KiB
Markdown
Raw Normal View History

2020-04-08 14:13:33 +05:30
---
2020-06-23 00:09:42 +05:30
stage: Verify
2022-04-04 11:22:00 +05:30
group: Pipeline Insights
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-04-08 14:13:33 +05:30
disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/job_artifacts.html'
---
2021-09-04 01:27:46 +05:30
# Job artifacts **(FREE)**
2020-04-08 14:13:33 +05:30
2021-11-18 22:05:49 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16675) in GitLab 12.4, artifacts in internal and private projects can be previewed when [GitLab Pages access control](../../administration/pages/index.md#access-control) is enabled.
2020-04-08 14:13:33 +05:30
2021-04-29 21:17:54 +05:30
Jobs can output an archive of files and directories. This output is known as a job artifact.
2020-04-08 14:13:33 +05:30
2021-04-29 21:17:54 +05:30
You can download job artifacts by using the GitLab UI or the [API](../../api/job_artifacts.md#get-job-artifacts).
2020-04-08 14:13:33 +05:30
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
2021-04-29 21:17:54 +05:30
For an overview of job artifacts, watch the video [GitLab CI pipelines, artifacts, and environments](https://www.youtube.com/watch?v=PCKDICEe10s).
Or, for an introduction, watch [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII).
2020-04-08 14:13:33 +05:30
2021-04-29 21:17:54 +05:30
For administrator information about job artifact storage, see [administering job artifacts](../../administration/job_artifacts.md).
2020-04-08 14:13:33 +05:30
2021-04-29 21:17:54 +05:30
## Create job artifacts
To create job artifacts, use the `artifacts` keyword in your `.gitlab-ci.yml` file:
2020-04-08 14:13:33 +05:30
```yaml
pdf:
script: xelatex mycv.tex
artifacts:
paths:
2020-07-28 23:09:34 +05:30
- mycv.pdf
2020-04-08 14:13:33 +05:30
expire_in: 1 week
```
2021-04-29 21:17:54 +05:30
In this example, a job named `pdf` calls the `xelatex` command to build a PDF file from the
LaTeX source file, `mycv.tex`.
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
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.
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
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.
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
If you run two types of pipelines (like branch and scheduled) for the same ref,
the pipeline that finishes later creates the job artifact.
2020-05-24 23:13:21 +05:30
2022-01-26 12:08:38 +05:30
To disable artifact passing, define the job with empty [dependencies](../yaml/index.md#dependencies):
```yaml
job:
stage: build
script: make build
dependencies: []
```
You may want to create artifacts only for tagged releases to avoid filling the
build server storage with temporary build artifacts. For example, use [`rules`](../yaml/index.md#rules)
to create artifacts only for tags:
```yaml
default-job:
script:
- mvn test -U
rules:
- if: $CI_COMMIT_BRANCH
release-job:
script:
- mvn package -U
artifacts:
paths:
- target/*.war
rules:
- if: $CI_COMMIT_TAG
```
You can use wildcards for directories too. For example, if you want to get all the
files inside the directories that end with `xyz`:
```yaml
job:
artifacts:
paths:
- path/*xyz/*
```
### Use CI/CD variables to define the artifacts name
You can use [CI/CD variables](../variables/index.md) to dynamically define the
artifacts file's name.
For example, to create an archive with a name of the current job:
```yaml
job:
artifacts:
name: "$CI_JOB_NAME"
paths:
- binaries/
```
To create an archive with a name of the current branch or tag including only
the binaries directory:
```yaml
job:
artifacts:
name: "$CI_COMMIT_REF_NAME"
paths:
- binaries/
```
If your branch-name contains forward slashes
(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG`
instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact.
To create an archive with a name of the current job and the current branch or
tag including only the binaries directory:
```yaml
job:
artifacts:
name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
paths:
- binaries/
```
To create an archive with a name of the current [stage](../yaml/index.md#stages) and branch name:
```yaml
job:
artifacts:
name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
paths:
- binaries/
```
If you use **Windows Batch** to run your shell scripts you must replace
`$` with `%`:
```yaml
job:
artifacts:
name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
paths:
- binaries/
```
If you use **Windows PowerShell** to run your shell scripts you must replace
`$` with `$env:`:
```yaml
job:
artifacts:
name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
paths:
- binaries/
```
### Exclude files from job artifacts
Use [`artifacts:exclude`](../yaml/index.md#artifactsexclude) to prevent files from
being added to an artifacts archive.
For example, to store all files in `binaries/`, but not `*.o` files located in
subdirectories of `binaries/`.
```yaml
artifacts:
paths:
- binaries/
exclude:
- binaries/**/*.o
```
Unlike [`artifacts:paths`](../yaml/index.md#artifactspaths), `exclude` paths are not recursive.
To exclude all of the contents of a directory, match them explicitly rather
than matching the directory itself.
For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory:
```yaml
artifacts:
paths:
- binaries/
exclude:
- binaries/temp/**/*
```
### Add untracked files to artifacts
Use [`artifacts:untracked`](../yaml/index.md#artifactsuntracked) to add all Git untracked
2022-04-04 11:22:00 +05:30
files as artifacts (along with the paths defined in [`artifacts:paths`](../yaml/index.md#artifactspaths)). Untracked
files are those that haven't been added to the repository but exist in the repository checkout.
2022-01-26 12:08:38 +05:30
Save all Git untracked files and files in `binaries`:
```yaml
artifacts:
untracked: true
paths:
- binaries/
```
Save all untracked files but [exclude](../yaml/index.md#artifactsexclude) `*.txt`:
```yaml
artifacts:
untracked: true
exclude:
- "*.txt"
```
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
## Download job artifacts
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
You can download job artifacts or view the job archive:
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
- On the **Pipelines** page, to the right of the pipeline:
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
![Job artifacts in Pipelines page](img/job_artifacts_pipelines_page_v13_11.png)
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
- On the **Jobs** page, to the right of the job:
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
![Job artifacts in Jobs page](img/job_artifacts_jobs_page_v13_11.png)
2020-06-23 00:09:42 +05:30
2021-04-29 21:17:54 +05:30
- On a job's detail page. The **Keep** button indicates an `expire_in` value was set:
2020-06-23 00:09:42 +05:30
2021-04-29 21:17:54 +05:30
![Job artifacts browser button](img/job_artifacts_browser_button_v13_11.png)
2020-06-23 00:09:42 +05:30
2021-04-29 21:17:54 +05:30
- On a merge request, by the pipeline details:
2020-06-23 00:09:42 +05:30
2021-04-29 21:17:54 +05:30
![Job artifacts in merge request](img/job_artifacts_merge_request_v13_11.png)
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
- When browsing an archive:
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
![Job artifacts browser](img/job_artifacts_browser_v13_11.png)
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
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.
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
## View failed job artifacts
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
If the latest job has failed to upload the artifacts, you can see that
information in the UI.
2021-02-22 17:27:13 +05:30
2021-04-29 21:17:54 +05:30
![Latest artifacts button](img/job_latest_artifacts_browser.png)
2020-05-24 23:13:21 +05:30
2021-04-29 21:17:54 +05:30
## Delete job artifacts
2020-05-24 23:13:21 +05:30
2021-02-22 17:27:13 +05:30
WARNING:
2021-04-29 21:17:54 +05:30
This is a destructive action that leads to data loss. Use with caution.
2020-04-08 14:13:33 +05:30
2021-04-29 21:17:54 +05:30
You can delete a single job, which also removes the job's
artifacts and log. You must be:
2021-03-08 18:12:59 +05:30
2021-04-29 21:17:54 +05:30
- The owner of the job.
2022-04-04 11:22:00 +05:30
- A user with at least the Maintainer role for the project.
2021-03-08 18:12:59 +05:30
2021-04-29 21:17:54 +05:30
To delete a job:
2020-04-08 14:13:33 +05:30
2021-04-29 21:17:54 +05:30
1. Go to a job's detail page.
2021-10-27 15:23:28 +05:30
1. On the top right of the job's log, select **Erase job log** (**{remove}**).
1. On the confirmation dialog, select **OK**.
2020-04-08 14:13:33 +05:30
2022-01-26 12:08:38 +05:30
## Expose job artifacts in the merge request UI
Use the [`artifacts:expose_as`](../yaml/index.md#artifactsexpose_as) keyword to expose
[job artifacts](../pipelines/job_artifacts.md) in the [merge request](../../user/project/merge_requests/index.md) UI.
For example, to match a single file:
```yaml
test:
script: ["echo 'test' > file.txt"]
artifacts:
expose_as: 'artifact 1'
paths: ['file.txt']
```
With this configuration, GitLab adds a link **artifact 1** to the relevant merge request
that points to `file.txt`. To access the link, select **View exposed artifact**
below the pipeline graph in the merge request overview.
An example that matches an entire directory:
```yaml
test:
script: ["mkdir test && echo 'test' > test/file.txt"]
artifacts:
expose_as: 'artifact 1'
paths: ['test/']
```
2021-04-29 21:17:54 +05:30
## Retrieve job artifacts for other projects
2020-04-08 14:13:33 +05:30
2021-04-29 21:17:54 +05:30
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.
2020-04-08 14:13:33 +05:30
2021-04-29 21:17:54 +05:30
## How searching for job artifacts works
2020-04-08 14:13:33 +05:30
2021-11-18 22:05:49 +05:30
In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201784), artifacts
2021-09-30 23:02:18 +05:30
for [parent and child pipelines](parent_child_pipelines.md) are searched in hierarchical
2021-01-03 14:25:43 +05:30
order from parent to child. For example, if both parent and child pipelines have a
2021-04-29 21:17:54 +05:30
job with the same name, the job artifact from the parent pipeline is returned.
2021-01-03 14:25:43 +05:30
2021-04-29 21:17:54 +05:30
## Access the latest job artifacts by URL
2020-04-08 14:13:33 +05:30
2021-06-08 01:23:25 +05:30
You can download job artifacts from the latest successful pipeline by using a URL.
2021-04-29 21:17:54 +05:30
To download the whole artifacts archive:
2020-04-08 14:13:33 +05:30
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/download?job=<job_name>
```
2021-04-29 21:17:54 +05:30
To download a single file from the artifacts:
2020-04-08 14:13:33 +05:30
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/raw/<path_to_file>?job=<job_name>
```
2021-04-29 21:17:54 +05:30
For example, to download the latest artifacts of the job named `coverage` in
the `main` branch of the `gitlab` project in the `gitlab-org`
namespace:
2020-04-08 14:13:33 +05:30
```plaintext
2021-04-29 21:17:54 +05:30
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/main/download?job=coverage
2020-04-08 14:13:33 +05:30
```
2021-09-04 01:27:46 +05:30
To download the file `review/index.html` from the same artifacts:
2020-04-08 14:13:33 +05:30
```plaintext
2021-09-04 01:27:46 +05:30
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/main/raw/review/index.html?job=coverage
2020-04-08 14:13:33 +05:30
```
2021-04-29 21:17:54 +05:30
To browse the latest job artifacts:
2020-04-08 14:13:33 +05:30
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name>
```
For example:
```plaintext
2021-09-04 01:27:46 +05:30
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/main/browse?job=coverage
2020-04-08 14:13:33 +05:30
```
2021-04-29 21:17:54 +05:30
To download specific files, including HTML files that
2020-04-08 14:13:33 +05:30
are shown in [GitLab Pages](../../administration/pages/index.md):
```plaintext
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name>
```
2021-04-29 21:17:54 +05:30
For example, when a job `coverage` creates the artifact `htmlcov/index.html`:
2020-04-08 14:13:33 +05:30
```plaintext
2021-09-04 01:27:46 +05:30
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/main/file/htmlcov/index.html?job=coverage
2020-04-08 14:13:33 +05:30
```
2021-04-29 21:17:54 +05:30
## When job artifacts are deleted
2020-04-08 14:13:33 +05:30
2021-09-30 23:02:18 +05:30
See the [`expire_in`](../yaml/index.md#artifactsexpire_in) documentation for information on when
2021-06-08 01:23:25 +05:30
job artifacts are deleted.
2021-01-03 14:25:43 +05:30
2021-04-29 21:17:54 +05:30
### Keep artifacts from most recent successful jobs
2021-03-08 18:12:59 +05:30
> - [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.
2022-01-26 12:08:38 +05:30
By default artifacts are always kept for the most recent successful pipeline for
each ref. This means that the latest artifacts do not immediately expire according
to the `expire_in` specification.
If a new pipeline for the same ref completes successfully, the previous pipeline's
artifacts are deleted according to the `expire_in` configuration. The artifacts
2022-04-04 11:22:00 +05:30
of the new pipeline are kept automatically.
2022-01-26 12:08:38 +05:30
2021-03-08 18:12:59 +05:30
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:
2021-10-27 15:23:28 +05:30
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Settings > CI/CD**.
1. Expand **Artifacts**.
2021-04-29 21:17:54 +05:30
1. Clear the **Keep artifacts from most recent successful jobs** checkbox.
2021-03-08 18:12:59 +05:30
2021-03-11 19:13:27 +05:30
You can disable this behavior for all projects on a self-managed instance in the
2021-04-29 21:17:54 +05:30
[instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
2021-03-11 19:13:27 +05:30
2021-04-29 21:17:54 +05:30
## Troubleshooting job artifacts
2021-01-03 14:25:43 +05:30
### Error message `No files to upload`
2021-04-29 21:17:54 +05:30
This message is often preceded by other errors or warnings that specify the filename and why it wasn't
generated. Check the job log for these messages.
2021-01-03 14:25:43 +05:30
2021-04-29 21:17:54 +05:30
If you find no helpful messages, retry the failed job after activating
2021-09-30 23:02:18 +05:30
[CI/CD debug logging](../variables/index.md#debug-logging).
2021-04-29 21:17:54 +05:30
This logging should provide information to help you investigate further.
2022-03-02 08:16:31 +05:30
### Error message `Missing /usr/bin/gitlab-runner-helper. Uploading artifacts is disabled.`
There is a [known issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3068) where setting a CI/CD variable named `DEBUG` can cause artifact uploads to fail.
To work around this, either use a different variable name or set it inline with `script`:
```yaml
# This job might fail due to issue gitlab-org/gitlab-runner#3068
failing_test_job:
variables:
DEBUG: true
script: bin/mycommand
artifacts:
paths:
- bin/results
# This job does not define a CI/CD variable named `DEBUG` and is not affected by the issue
successful_test_job:
script: DEBUG=true bin/mycommand
artifacts:
paths:
- bin/results
```