222 lines
8.6 KiB
Markdown
222 lines
8.6 KiB
Markdown
---
|
|
stage: Verify
|
|
group: Continuous Integration
|
|
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
|
|
disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/job_artifacts.html'
|
|
type: reference, howto
|
|
---
|
|
|
|
# Job artifacts
|
|
|
|
> 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.
|
|
|
|
Jobs can output an archive of files and directories. This output is known as a job artifact.
|
|
|
|
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).
|
|
|
|
Administrators should review our [job artifacts administration](../../administration/job_artifacts.md) documentation.
|
|
|
|
## Define artifacts in the `.gitlab-ci.yml` file
|
|
|
|
This example shows how to configure your `.gitlab-ci.yml` file to create job artifacts:
|
|
|
|
```yaml
|
|
pdf:
|
|
script: xelatex mycv.tex
|
|
artifacts:
|
|
paths:
|
|
- mycv.pdf
|
|
expire_in: 1 week
|
|
```
|
|
|
|
A job named `pdf` calls the `xelatex` command to build a PDF file from the
|
|
LaTeX source file, `mycv.tex`.
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
|
|
|
|
- On the **Jobs** page, to the right of the job:
|
|
|
|
|
|
|
|
- On a job's detail page. The **Keep** button indicates an `expire_in` value was set:
|
|
|
|
|
|
|
|
- On a merge request, by the pipeline details:
|
|
|
|
|
|
|
|
- When browsing an archive:
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## Troubleshooting job artifacts
|
|
|
|
### Error message `No files to upload`
|
|
|
|
This is often preceded by other errors or warnings that specify the filename and why it wasn't
|
|
generated in the first place. Please check the entire job log for such messages.
|
|
|
|
If you find no helpful messages, please retry the failed job after activating
|
|
[CI/CD debug logging](../variables/README.md#debug-logging).
|
|
This provides useful information to investigate further.
|
|
|
|
<!-- ## Troubleshooting
|
|
|
|
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
|
|
one might have when setting this up, or when something is changed, or on upgrading, it's
|
|
important to describe those, too. Think of things that may go wrong and include them here.
|
|
This is important to minimize requests for support, and to avoid doc comments with
|
|
questions that you know someone might ask.
|
|
|
|
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
|
|
If you have none to add when creating a doc, leave this section in place
|
|
but commented out to help encourage others to add to it in the future. -->
|