Understanding GitLab CI Artifacts: Paths, Exposure, Naming, Conditions, Expiration, and Reports

GitLab CI artifacts allow you to attach files or directories to a job so they can be downloaded from the GitLab UI after the job finishes.

artifacts:paths defines relative paths inside the project that will be stored as artifacts; paths must stay within the project directory.

artifacts:
  paths:
    - target/

To disable artifact transfer, set an empty dependencies list:

job:
  stage: build
  script: make build
  dependencies: []

artifacts:expose_as makes an artifact publicly visible in the merge request UI. Example:

test:
  script:
    - echo 1
  artifacts:
    expose_as: 'artifact 1'
    paths:
      - path/to/file.txt

Each merge request can expose up to ten job artifacts, and directories with multiple files will link to the artifact browser. Enabling GitLab Pages allows rendering of .html, .htm, .txt, .json, .log files.

artifacts:name sets a custom name for the artifact archive, supporting predefined variables such as $CI_JOB_NAME , $CI_COMMIT_REF_NAME , or combinations thereof.

job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/

artifacts:when controls when artifacts are uploaded: on_success (default), on_failure , or always . Example for uploading only on failure:

job:
  artifacts:
    when: on_failure

artifacts:expire_in defines how long artifacts are kept; the default is 30 days. The value can include units, e.g., 1 week :

job:
  artifacts:
    expire_in: 1 week

artifacts:reports collects test, code quality, and security reports for display in the GitLab UI. The junit report example:

build:
  stage: build
  script:
    - mvn test
    - mvn cobertura:cobertura
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    when: on_success
    expose_as: 'artifact 1'
    paths:
      - target/*.jar
    reports:
      junit: target/surefire-reports/TEST-*.xml

Multiple JUnit files can be specified using patterns or arrays, and they will be merged automatically.

dependencies lists jobs whose artifacts should be downloaded; an empty array skips downloading any artifacts. If a dependent job’s artifacts have expired or been deleted, the dependent job fails.

A comprehensive pipeline example combines before_script, variables, cache, stages, and jobs with artifacts, dependencies, retries, and after_script:

before_script:
  - echo "before-script!!"
variables:
  DOMAIN: example.com
cache:
  paths:
    - target/
stages:
  - build
  - test
  - deploy
build:
  stage: build
  tags:
    - build
  only:
    - master
  script:
    - mvn test
    - mvn cobertura:cobertura
    - ls target
    - echo "$DOMAIN"
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    when: on_success
    paths:
      - target/*.jar
    reports:
      junit: target/surefire-reports/TEST-*.xml
      cobertura: target/site/cobertura/coverage.xml
  coverage: '/Code coverage: \d+\.\d+/'
unittest:
  dependencies:
    - build
  stage: test
  script:
    - echo "run test"
    - echo 'test' >> target/a.txt
  retry:
    max: 2
    when:
      - script_failure
deploy:
  stage: deploy
  script:
    - echo "run deploy"
  retry:
    max: 2
    when:
      - script_failure
after_script:
  - echo "after-script"

For further details, refer to the official GitLab documentation on JUnit test reports.