Managing Artifacts

1. Defining Artifacts

Property	Description	Values	Notes
artifacts	Defines artifacts to be stored and passed between jobs	`artifacts:`	Can be defined at job or global level
artifacts.paths	Paths to include in the artifacts	`paths:`	Supports wildcards and excludes
artifacts.name	Name of the artifact archive	`name: "artifact-name"`	Defaults to job name if not specified
artifacts.expiration	Time after which artifacts expire	`expiration: "1 week"`	Supports ISO 8601 duration format
artifacts.reports	Reports to be included in artifacts	`reports:`	Supports JUnit, cobertura, and coverage

Example: Defining Artifacts in a Job

job_name:
  script:
    - echo "Hello World"
  artifacts:
    paths:
      - build/
      - logs/
    name: "build-artifacts"
    expiration: "1 month"

2. Setting Artifact Paths

Property	Value	Description
artifacts.paths	`['path/to/artifact']`	Defines the file or directory paths to include in the artifact. Supports wildcards like `**`.
artifacts.name	`artifact-name`	Specifies the name of the artifact archive. Defaults to `artifacts`.
artifacts.expiration	`30 days`	Sets the expiration time for the artifact. Supports formats like `1 day`, `2 weeks`.
artifacts.reports	`{ junit: ['junit.xml'] }`	Defines artifact reports such as JUnit XML for test results.

Example: Basic Artifact Path Configuration

job_name:
  artifacts:
    paths:
      - dist/
      - logs/
    name: "build-artifacts"
    expiration: 1 week

Example: Using Wildcards in Artifact Paths

test_job:
  artifacts:
    paths:
      - coverage/*.xml
      - reports/**/*.html

3. Excluding Files from Artifacts

Option	Values	Description
artifacts.exclude	`string[]`	Defines a list of files or directories to exclude from artifacts. Supports glob patterns.

Example: Exclude specific files from artifacts

job_name:
  artifacts:
    paths:
      - build/
    exclude:
      - build/*.log
      - build/temp/

Note: The exclude option works in conjunction with paths to define which files are included or excluded from the artifact archive.

4. Setting Artifact Expiration

Property	Values	Description
artifacts.expire_in	`1d`, `30 days`, `1 month`	Time period after which artifacts are automatically deleted. Supports `d`, `w`, `m`, `y` units.
artifacts.expire_in	`never`	Disables automatic expiration of artifacts.

Example: Setting Artifact Expiration

job_name:
  artifacts:
    expire_in: 30 days

Note: Artifact expiration is applied per job and can be overridden at the project or group level via CI_JOB_ARTIFACT_EXPIRE_IN environment variable.

5. Using artifacts:when Conditions

Condition	Description	Usage Example
on_success	Artifacts are uploaded when the job succeeds.	`artifacts:` `when: on_success`
on_failure	Artifacts are uploaded when the job fails.	`artifacts:` `when: on_failure`
always	Artifacts are uploaded regardless of job status.	`artifacts:` `when: always`
manual	Artifacts are uploaded only when the job is manually triggered.	`artifacts:` `when: manual`

Example: Using artifacts:when with on_success

build_job:
  script:
    - echo "Building..."
  artifacts:
    when: on_success
    paths:
      - build/

Example: Using artifacts:when with always

test_job:
  script:
    - npm test
  artifacts:
    when: always
    paths:
      - coverage/

6. Exposing Artifacts

Property	Description	Values	Notes
artifacts.expire_in	Time after which artifacts are automatically deleted	`1 day`, `30 days`, `1 year`	Default is `30 days` if not specified
artifacts.reports	Define artifact reports to be exposed in the UI	`coverage`, `security`, `test`	Used for exposing test reports, coverage, and security scan results
artifacts.paths	Paths to include in the artifact	`build/`, `dist/`	Can include wildcards like `*/.log`

Example: Exposing Test Artifacts

test:
  script:
    - npm test
  artifacts:
    reports:
      junit: test-results.xml

Example: Exposing Build Artifacts

build:
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
      - build/
    expire_in: 1 week

Note: Artifacts are exposed in the GitLab UI under the Artifacts tab of a job.

7. Using Untracked Files

Option	Description	Default
artifacts.untracked	Include untracked files in the artifact	false

Example: Using untracked files in artifacts

build:
  script:
    - mkdir -p dist
    - echo "Hello World" > dist/index.html
  artifacts:
    paths:
      - dist/
    untracked: true

8. Naming Artifacts

Property	Description	Default	Notes
artifacts.name	Name of the artifact	`artifacts`	Used to identify the artifact in the UI and for download links
artifacts.path	Path to the artifact files	`nil`	Can be a glob pattern or list of paths
artifacts.expire_in	Time after which the artifact will be deleted	`30 days`	Can use formats like `1 day`, `2 weeks`
artifacts.releases	Whether to create a release for the artifact	`false`	Requires `release` to be defined in the job

Example: Naming Artifacts

job_name:
  artifacts:
    name: "build-artifacts"
    path:
      - "dist/"
      - "logs/"
    expire_in: "1 week"

9. Downloading Artifacts via API

Property	Description	Value
project_id	Unique identifier for the project	`12345`
job_id	ID of the job that created the artifact	`67890`
artifact_name	Name of the artifact to download	`report.pdf`

Example: Download Artifact via API

curl --header "PRIVATE-TOKEN: glpat-xxxxxxxxxxxxxx" \
     --output report.pdf \
     "https://gitlab.example.com/api/v4/projects/12345/jobs/67890/artifacts/report.pdf"

Note: Ensure the PRIVATE-TOKEN has sufficient permissions to access the project and job artifacts.

Warning: Artifacts are only accessible if they were created during the job execution and have not expired.

10. Viewing Artifacts in Merge Requests

Artifact	Access Method	Notes
Pipeline Artifacts	`https://gitlab.example.com/namespace/project/-/jobs/artifacts/job_name/browse`	View artifacts from a specific job in the pipeline
Merge Request Artifacts	`https://gitlab.example.com/namespace/project/-/merge_requests/MR_ID/artifacts`	Access artifacts generated during merge request pipeline

Example: Accessing Merge Request Artifacts

curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.example.com/api/v4/projects/123/merge_requests/456/artifacts"

Note: Artifacts are only accessible to users with sufficient permissions in the project.

Warning: Artifacts are deleted after the configured retention period or when the job is removed.