Gitlab Pipeline – artifacts – What is artifacts in GitLab CI/CD?

The artifacts keyword in a GitLab CI/CD job specifies a list of files and directories that should be saved and uploaded when a job finishes. These artifacts are then available for download from the GitLab UI and can be used by jobs in later stages of the same pipeline.

This is essential for:

• Passing build outputs (like compiled binaries, distributable packages, or static website files) to subsequent jobs (e.g., for testing or deployment).
• Storing reports (test reports, code coverage reports, etc.).
• Making build results available for users to download.

---

Example .gitlab-ci.yml with artifacts:

YAML

# .gitlab-ci.yml

stages:
  - build
  - test
  - package

default:
  image: alpine:latest

# Job 1: Builds the application and creates artifacts
build_application:
  stage: build
  script:
    - echo "--- Building Application ---"
    - mkdir -p dist/app  # Create a directory for distributable files
    - echo "MyApplication_v1.0_binary" > dist/app/my_app
    - echo "Configuration file content" > dist/app/config.json
    - echo "Build successful!"

    - echo "Generating a build report..."
    - echo "Build report for commit $CI_COMMIT_SHORT_SHA" > build_report.txt
    - echo "Timestamp: $(date)" >> build_report.txt

  artifacts:
    name: "${CI_JOB_NAME}_${CI_COMMIT_REF_SLUG}" # Optional: Custom name for the artifact archive
    paths:
      - dist/ # Save the entire 'dist' directory
      - build_report.txt # Save an individual file
    expire_in: '1 week' # Optional: How long to keep the artifacts (e.g., 1 day, 1 week, 3 months)
    when: on_success # Optional: When to create artifacts (on_success, on_failure, always). Default is on_success.
    # untracked: true # Optional: Set to true to also include all Git untracked files

# Job 2: Tests the application using artifacts from the 'build_application' job
test_application:
  stage: test
  # This job will automatically download artifacts from 'build_application'
  # because it's in a later stage and 'dependencies' is not set to [].
  script:
    - echo "--- Testing Application ---"
    - echo "Checking for build artifacts..."
    - ls -R dist/ # List contents of the 'dist' directory (should contain 'app/my_app' and 'app/config.json')
    - if [ -f "dist/app/my_app" ]; then echo "Application binary found."; else echo "ERROR: Application binary NOT found!"; exit 1; fi
    - if [ -f "build_report.txt" ]; then cat build_report.txt; else echo "ERROR: Build report NOT found!"; exit 1; fi
    - echo "Simulating tests on my_app..."
    - sleep 5
    - echo "Tests passed!"

# Job 3: Packages the application, also using artifacts from 'build_application'
# This demonstrates another job in a later stage accessing the same artifacts.
package_release:
  stage: package
  script:
    - echo "--- Packaging Release ---"
    - echo "Using build artifacts for packaging..."
    - if [ -f "dist/app/my_app" ]; then echo "Packaging $(cat dist/app/my_app)..."; else echo "ERROR: Application binary for packaging NOT found!"; exit 1; fi
    - tar -czvf "release_package_${CI_COMMIT_SHORT_SHA}.tar.gz" dist/ build_report.txt
    - echo "Release package created: release_package_${CI_COMMIT_SHORT_SHA}.tar.gz"
  artifacts:
    paths:
      - "*.tar.gz" # Save the created tarball as an artifact of this job
    expire_in: '30 days'

Code language: PHP (php)

---

Explanation:

1. artifacts: Keyword:
   • Used within a job definition to specify which files and directories should be preserved after the job completes.
   • GitLab collects these files, archives them (usually as a ZIP file), and uploads them.
2. build_application Job (Artifact Producer):
   • script:: This section creates a dist/app/ directory with some dummy application files and a build_report.txt.
   • artifacts::
     • name: "${CI_JOB_NAME}_${CI_COMMIT_REF_SLUG}":
       • (Optional) Allows you to define a custom name for the downloadable artifact archive. Here, it uses predefined CI/CD variables to make the name dynamic (e.g., build_application_main.zip). If omitted, GitLab generates a default name.
     • paths::
       • (Required if artifacts is used) An array of file paths or directory paths that should be included in the artifact archive. Paths are relative to the project’s root directory ($CI_PROJECT_DIR).
       • - dist/: Includes the entire dist directory and its contents.
       • - build_report.txt: Includes the individual build_report.txt file.
     • expire_in: '1 week':
       • (Optional) Specifies how long the artifacts for this job should be stored in GitLab. After this period, they might be deleted to save space (unless “Keep artifacts from most recent successful_jobs jobs” is enabled in project settings). The format can be natural language (e.g., '1 day', '2 hrs 30 mins', '6 mos') or a specific duration.
     • when: on_success:
       • (Optional) Determines when artifacts are created.
         • on_success (Default): Artifacts are saved only if the job completes successfully.
         • on_failure: Artifacts are saved only if the job fails (useful for logs or debug info).
         • always: Artifacts are saved regardless of the job’s success or failure.
     • untracked: true:
       • (Optional) If set to true, GitLab will also include all files that are untracked by Git in the artifact archive, in addition to the paths specified. Use with caution.
3. test_application Job (Artifact Consumer):
   • This job is in the test stage, which is later than the build stage where build_application ran.
   • Automatic Artifact Download: By default, jobs in later stages automatically download artifacts from all jobs in all previous stages if those jobs completed successfully and produced artifacts. This happens unless you use dependencies: [] in the consuming job or manage dependencies with needs: in a way that excludes certain artifacts.
   • The script section in test_application can therefore access the files from dist/ and build_report.txt as if they were part of its own workspace.
4. package_release Job (Another Artifact Consumer & Producer):
   • This job also benefits from the default artifact download from build_application.
   • It then creates its own artifact (release_package_${CI_COMMIT_SHORT_SHA}.tar.gz) by packaging the received artifacts and the report.

Key Concepts and Behavior:

• Purpose: To persist files and directories created by a job for use in subsequent jobs, for manual download, or for features like GitLab Pages or test reporting.
• Storage: Artifacts are stored on the GitLab server (or external storage if configured) and are associated with the job and pipeline run.
• Downloading Artifacts:
  • From UI: You can download artifacts as a ZIP file from the job’s page in the GitLab UI, or from the pipeline view.
  • By Other Jobs: As shown, later jobs often get them automatically. needs: provides more explicit control over which artifacts are downloaded from specified prerequisite jobs. dependencies: can also be used for more fine-grained control when not using needs.
• Artifacts vs. Cache:
  • Artifacts: Intended for passing outputs between stages, for final build products, or for reports. They are generally meant to be kept (at least until expire_in). They are uploaded to GitLab.
  • Cache: Intended to speed up subsequent runs of the same job or related jobs (e.g., node_modules, compiler caches). Caches are best-effort and might be deleted by runners to save space. They are typically stored on the runner or a shared cache storage like S3.
• artifacts:reports: (Advanced):
  • GitLab has special support for certain types of reports (e.g., JUnit XML for test results, Cobertura for code coverage). Using artifacts:reports:junit: report.xml allows GitLab to parse these reports and display information directly in the UI (e.g., in Merge Requests).

Using artifacts is fundamental to building effective CI/CD pipelines in GitLab, as it enables the flow of work and results between different stages of your development lifecycle.