GitLab CI Caching

A cache stores files that jobs download or build repeatedly, such as project libraries. A later job restores the stored files and skips the download. Pipelines that took ten minutes often drop to three.

Think of a chef who buys flour once and keeps a bag in the pantry. Every new dish uses the pantry bag. A trip to the market happens only when the bag runs low.

Pipeline Time With and Without a Cache

  WITHOUT CACHE
  Job: install libraries ████████████████ 4 min
  Job: run tests         ██████ 1.5 min
  Total: 5.5 min

  WITH CACHE
  Job: restore cache     █ 10 sec
  Job: run tests         ██████ 1.5 min
  Total: 1.7 min

Cache and Artifacts Compared

FeatureCacheArtifacts
PurposeSpeed up repeated downloadsPass job results forward
Guaranteed to existNoYes
Downloadable from the pipeline pageNoYes
Shared across pipelinesYesNo, each pipeline owns its own
Typical contentnode_modules, .m2, pip packagesCompiled app, test reports

A cache can disappear at any time. Every job must work when the cache is empty.

Your First Cache

install-and-test:
  image: node:20
  cache:
    paths:
      - node_modules/
  script:
    - npm install
    - npm test

The first run downloads everything and saves node_modules at the end. Later runs restore the folder before the script starts.

Cache Keys

A key names the cache. Jobs with the same key share the same stored files.

One Cache per Branch

cache:
  key: $CI_COMMIT_REF_SLUG
  paths:
    - node_modules/

Each branch keeps its own copy. Branch changes never disturb other branches.

Cache Tied to a Lock File

The files keyword builds the key from the contents of a file. The cache stays valid until that file changes.

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/

A new library in package-lock.json creates a fresh cache. Unchanged libraries reuse the old one.

Key Prefix

cache:
  key:
    files:
      - package-lock.json
    prefix: $CI_JOB_NAME
  paths:
    - node_modules/

The prefix separates caches of different jobs.

Cache Policy

The policy controls whether a job reads, writes, or does both.

PolicyReadsWritesUse For
pull-pushYesYesDefault behavior
pullYesNoTest jobs that only need the libraries
pushNoYesOne job that builds the cache
prepare:
  stage: build
  script:
    - npm ci
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
    policy: push

unit-tests:
  stage: test
  script:
    - npm test
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
    policy: pull

One job builds the cache and many jobs read it. Parallel test jobs save time because none of them upload files.

Cache Package Manager Folders

Some tools keep downloads outside the project folder. Point them to a folder inside the project so GitLab can store it.

cache:
  paths:
    - .npm/
script:
  - npm ci --cache .npm --prefer-offline

Where the Cache Lives

  Job finishes → Runner zips cached folders → Stores archive
                                               ├─ on the runner machine (default)
                                               └─ in shared object storage (large setups)
  Next job starts → Runner finds a matching key → Unzips archive into the project

A runner on a different machine may not find a local cache. Shared storage fixes that gap for teams with many runners.

Clear a Broken Cache

Open Build → Pipelines and select Clear runner caches. GitLab bumps an internal counter, so jobs build fresh caches on the following run.

Cache Best Practices

  • Cache dependency folders, never source code.
  • Tie keys to lock files.
  • Use the pull policy in jobs that never change the cache.
  • Keep cached folders small; huge archives slow the restore step.
  • Check job logs for the lines "Checking cache" and "Successfully extracted cache" to confirm the cache works.