doc/ci/jobs/job_artifacts.md
{{< details >}}
{{< /details >}}
Jobs can output an archive of files and directories. This output is known as a job artifact. Artifacts can include build output or report files. By default, later jobs fetch a copy of all artifacts from jobs in earlier stages.
For example, an early job can build a project and save the output as an artifact. Then a later job fetches the artifact and runs tests on the saved build output.
For a full list of supported configuration for the artifacts keyword,
see the GitLab CI/CD YAML syntax reference.
Related topics:
To create job artifacts, use the artifacts keyword in your .gitlab-ci.yml file:
pdf:
script: xelatex mycv.tex
artifacts:
paths:
- mycv.pdf
In this example, 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.
You can use wildcards for paths and directories. For example, to create an artifact
with all the files inside the directories that end with xyz:
job:
script: echo "build xyz project"
artifacts:
paths:
- path/*xyz/*
The expire_in keyword determines how long GitLab keeps the artifacts defined in artifacts:paths. For example:
pdf:
script: xelatex mycv.tex
artifacts:
paths:
- mycv.pdf
expire_in: 1 week
If expire_in is not defined, the Default artifacts expiration
instance setting is used.
To prevent artifacts from expiring, you can select Keep from the job details page. The option is not available when an artifact has no expiry set.
By default, artifacts are always kept for the most recent successful pipeline on each ref.
You can explicitly customize artifact names using the artifacts:name configuration:
job:
artifacts:
name: "job1-artifacts-file"
paths:
- binaries/
Use artifacts:exclude 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/:
artifacts:
paths:
- binaries/
exclude:
- binaries/**/*.o
Unlike artifacts:paths, 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:
artifacts:
paths:
- binaries/
exclude:
- binaries/temp/**/*
Use artifacts:untracked to add all Git untracked files as artifacts along with the paths
defined in artifacts:paths. Untracked files are those that haven't been added to the
repository but exist in the repository checkout.
For example, to save all Git untracked files and files in binaries:
artifacts:
untracked: true
paths:
- binaries/
For example, to save all untracked files but exclude *.txt files:
artifacts:
untracked: true
exclude:
- "*.txt"
Variable expansion is supported for artifacts:name, artifacts:paths, and artifacts:exclude.
Instead of using shell, GitLab Runner uses its internal variable expansion mechanism. Only CI/CD variables are supported in this context.
For example, to create an archive using the current branch or tag name including only files from a directory named after the current project:
job:
artifacts:
name: "$CI_COMMIT_REF_NAME"
paths:
- binaries/${CI_PROJECT_NAME}/
When your branch name contains forward slashes (for example, feature/my-feature),
use $CI_COMMIT_REF_SLUG instead of $CI_COMMIT_REF_NAME to ensure proper artifact naming.
Variables are expanded before globs.
By default, jobs fetch all artifacts from jobs defined in previous stages. These artifacts are downloaded into the job's working directory.
You can control which artifacts to download by using the dependencies or needs:artifacts keywords.
When you use these keywords, the default behavior changes and artifacts are fetched from only the jobs you specify.
To prevent a job from downloading any artifacts, set dependencies to an empty array ([]):
job:
stage: test
script: make build
dependencies: []
{{< history >}}
artifacts_management_page removed.{{< /history >}}
You can view all artifacts stored in a project from the Build > Artifacts page. This list displays all jobs and their associated artifacts. Expand an entry to access all artifacts associated with a job, including:
artifacts: keyword.You can download or delete individual artifacts from this list.
You can download job artifacts by using the GitLab UI or the API.
From the GitLab UI, you can download job artifacts from:
Report artifacts can only be downloaded from the Pipelines list or Artifacts page.
You can download the artifacts archive for a specific job with a publicly accessible URL.
For example, to download the latest artifacts of a job named build in the main branch
of a project on GitLab.com:
https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build
To download a specific file from the artifacts:
https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/raw/review/index.html?job=build
Files returned by this endpoint always have the plain/text content type.
In both examples, replace <project-id> with a valid project ID. You can find the project ID
on the project overview page.
Artifacts for parent and child pipelines 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 artifacts from the parent pipeline are returned.
{{< details >}}
{{< /details >}}
You can use a CI/CD job token to authenticate with the jobs artifacts API endpoint and fetch artifacts from a different pipeline. You must specify which job to retrieve artifacts from, for example:
build_submodule:
stage: test
script:
- apt update && apt install -y unzip
- curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"
- unzip artifacts.zip
To fetch artifacts from a job in the same pipeline, use the needs:artifacts keyword.
To restrict who can download job artifacts, use the artifacts:access keyword in your .gitlab-ci.yml file. For example:
job:
artifacts:
access: maintainer
paths:
- build/
You can browse the contents of the artifacts from the UI without downloading the artifact locally, from:
If GitLab Pages is enabled globally, even if it is disabled in the project settings, you can preview some artifacts file extensions directly in your browser. If the project is internal or private, you must enable GitLab Pages access control to enable the preview.
The following extensions are supported:
| File extension | GitLab.com | Linux package with built-in NGINX |
|---|---|---|
.html | {{< yes >}} | {{< yes >}} |
.json | {{< yes >}} | {{< yes >}} |
.xml | {{< yes >}} | {{< yes >}} |
.txt | {{< no >}} | {{< yes >}} |
.log | {{< no >}} | {{< yes >}} |
You can browse the job artifacts of the latest successful pipeline for a specific job with a publicly accessible URL.
For example, to browse the latest artifacts of a job named build in the main branch
of a project on GitLab.com:
https://gitlab.com/<full-project-path>/-/jobs/artifacts/main/browse?job=build
Replace <full-project-path> with a valid project path, you can find it in the URL for your project.
[!warning] Deleting the job log and artifacts is a destructive action that cannot be reverted. Use with caution. Deleting certain files, including report artifacts, job logs, and metadata files, affects GitLab features that use these files as data sources.
You can delete a job's artifacts and log.
Prerequisites:
To delete a job:
You can also delete individual artifacts from the Artifacts page.
{{< history >}}
ci_job_artifact_bulk_destroy. Disabled by default.ci_job_artifact_bulk_destroy removed.{{< /history >}}
You can delete multiple artifacts at the same time:
Use the artifacts:expose_as keyword to provide direct access to artifacts from the merge request UI.
For example, for an artifact with a single file:
test:
script: ["echo 'test' > file.txt"]
artifacts:
expose_as: 'artifact 1'
paths: ['file.txt']
With this configuration, the View exposed artifact section displays a link to file.txt labeled artifact 1.
{{< history >}}
{{< /history >}}
By default, artifacts are always kept for the most recent successful pipeline on each ref.
Any expire_in configuration does not apply to the most recent artifacts.
When a new pipeline on the same ref completes successfully, the previous pipeline's artifacts
are deleted according to the expire_in configuration. The artifacts of the new pipeline
are kept automatically.
A pipeline's artifacts are only deleted according to the expire_in configuration if a
new pipeline runs for the same ref and:
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:
After disabling this setting, all new artifacts expire according to the expire_in configuration.
Artifacts in old pipelines continue to be kept until a new pipeline runs for the same ref.
Then the artifacts in the earlier pipeline for that ref are allowed to expire too.
You can disable this behavior for all projects on GitLab Self-Managed with the Keep artifacts from latest successful pipelines instance setting.
You can disable this behavior for all projects on GitLab Self-Managed in the instance's CI/CD settings.