Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท GitLab CI/CD Pipelines

Artifacts and Cache

Understand the difference between GitLab CI artifacts and cache, pass build output between jobs, expire artifacts, key caches on lockfiles and test reports.

Every job starts on a clean runner with a fresh checkout. That is wonderful for reproducibility and terrible for speed: if each job has to download 500 MB of dependencies, your pipeline crawls. And if the build job produces a binary, how does the deploy job get it? GitLab has two different tools for these two different problems, and mixing them up is the most common CI beginner mistake.

The key difference

  • Artifacts are the results of a job. They are uploaded to GitLab, stored with the job, available for download in the UI, and passed to later jobs in the same pipeline. They are reliable: a later job can depend on them.
  • Cache is a speed-up. It stores files such as downloaded dependencies so that future pipelines (and jobs) can reuse them. It is best-effort: a cache may be missing (new runner, expired, evicted), so your job must still work without it.
Artifacts Cache
Purpose Pass results between jobs, keep outputs Reuse downloads between runs
Guaranteed? Yes, within the pipeline No, never rely on it
Stored On GitLab Usually on the runner or in object storage
Typical content Build output, test reports, binaries node_modules, .m2, pip caches

Artifacts

Declare them with artifacts:paths (relative to the project directory):

YAML
stages: [build, test, deploy]

build-site:
  stage: build
  image: node:22
  script:
    - npm ci
    - npm run build          # writes ./dist
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

test-site:
  stage: test
  script:
    - ls dist                # dist/ was downloaded automatically
    - ./check-links.sh dist

publish:
  stage: deploy
  script:
    - ./upload.sh dist

Jobs in later stages download artifacts from all earlier jobs by default. To be precise, use dependencies: (a list of jobs to fetch from, or an empty list to fetch none) or needs: (see the next lesson).

Useful options:

  • expire_in: how long GitLab keeps them (30 minutes, 1 day, 1 week, never). Short expiry saves storage; your instance also has a default and a maximum.
  • when: always or on_failure: upload artifacts even when the job fails (the default is on success). Good for logs and screenshots of a failing test.
  • exclude: patterns to leave out.
  • name: the archive name for download.
  • untracked: true: include all files not tracked by Git.
  • reports: special artifacts GitLab understands, for example JUnit test results shown in the merge request:
YAML
unit-tests:
  script: npm test -- --reporter=junit --outputFile=junit.xml
  artifacts:
    when: always
    reports:
      junit: junit.xml

With a JUnit report, the merge request widget lists test counts and failures without opening the log. Other report types cover coverage, code quality and security scans.

You can download a job's artifacts from the job page (Download or Browse), and the keep button stops them from expiring. Artifacts count toward your storage quota, so expire the ones nobody needs.

Cache

Declare a cache with a key and paths:

YAML
default:
  cache:
    key: npm-$CI_COMMIT_REF_SLUG
    paths:
      - .npm/

install-and-test:
  image: node:22
  script:
    - npm ci --cache .npm --prefer-offline
    - npm test

Two rules to remember:

  1. Cache paths must be inside the project directory. That is why we point npm's cache to .npm/ instead of its default location in the home directory.
  2. Caches are restored at the start of a job and saved at the end (when the job succeeds). Which runner holds the cache matters: with several machines, each has its own local cache unless you configure a shared cache (distributed cache backed by object storage such as S3).

Choosing a good key

The key decides when a cache is reused:

  • A fixed key (key: deps) shares one cache for everything, which can become stale or polluted.
  • A per-branch key ($CI_COMMIT_REF_SLUG) separates branches.
  • A lockfile key is the best for dependencies: cache:key:files derives the key from the files you list, so the cache changes only when dependencies change.
YAML
cache:
  key:
    files:
      - package-lock.json
  paths:
    - .npm/

The stand-in below shows the logic: the key is a digest of the lockfile contents, so editing the lockfile produces a different key and a cache miss, while unrelated changes reuse the cache. GitLab's real implementation hashes based on the last commits that changed those files, but the effect is the same. The digest here is plain SHA-1 of the contents.

Python Stand-in: a cache key from a lockfile

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Cache policies

By default a job pulls the cache at the start and pushes it at the end (policy: pull-push). In a pipeline where one job builds the dependency cache and many jobs only read it, set policy: pull on the readers so they do not waste time re-uploading:

YAML
cache:
  key: deps
  paths: [node_modules/]
  policy: pull

Artifacts versus cache in practice

A well-built Node pipeline uses both:

YAML
install:
  stage: .pre
  script: npm ci --cache .npm --prefer-offline
  cache:
    key: { files: [package-lock.json] }
    paths: [.npm/]
    policy: pull-push

build:
  stage: build
  script: npm run build
  artifacts:
    paths: [dist/]
    expire_in: 1 day

Dependencies are cached across pipelines, and the built site is passed on as an artifact within each pipeline.

The stand-in below models artifact expiry. Given job completion dates and expire_in, it tells you which artifacts still exist on a given day, which is the kind of reasoning you do when someone asks "why can't I download that build?".

Python Stand-in: which artifacts have expired?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Troubleshooting

  • Cache never hits: the key changes every time (for example it includes $CI_COMMIT_SHA), or jobs run on different runners with local caches.
  • "No files to upload" warning: the artifact path does not exist after the script ran; check the working directory and the path.
  • Artifact too large: compress or narrow paths; there is a per-job size limit.
  • Stale cache hides a problem: clear caches from the Pipelines page or change the key.
  • Keep secrets out of artifacts; anyone who can read the job can download them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You need the build output from the build job in the deploy job of the same pipeline. What do you use?

    Artifacts are the reliable way to hand job results to later jobs.
  2. 2. Why must your job still work when the cache is missing?

    A cache is an optimization only. A new runner or expired entry means a miss.
  3. 3. What is a good cache key for npm dependencies?

    A key from the lockfile changes only when dependencies change, which maximizes reuse without going stale.
  4. 4. Which setting stops a job from re-uploading a cache it only reads?

    policy: pull downloads the cache but never saves it back.

Summary

  • Artifacts carry job results to later jobs and to people; caches reuse downloads across pipelines.
  • Set expire_in to control storage and use when: always to keep failure evidence.
  • Cache paths must be inside the project directory; derive keys from lockfiles with cache:key:files.
  • Use policy: pull for jobs that only read a cache.
  • Reports such as JUnit show results directly in merge requests.

Next: Needs, Includes and Reusable Pipelines