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
| Feature | Cache | Artifacts |
|---|---|---|
| Purpose | Speed up repeated downloads | Pass job results forward |
| Guaranteed to exist | No | Yes |
| Downloadable from the pipeline page | No | Yes |
| Shared across pipelines | Yes | No, each pipeline owns its own |
| Typical content | node_modules, .m2, pip packages | Compiled 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.
| Policy | Reads | Writes | Use For |
|---|---|---|---|
| pull-push | Yes | Yes | Default behavior |
| pull | Yes | No | Test jobs that only need the libraries |
| push | No | Yes | One 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.
