Understanding GitLab CI Cache Configuration and Best Practices

The article introduces the cache feature in GitLab CI, which specifies files or directories to be cached between jobs using paths relative to the project directory. Global cache definitions apply to all jobs unless overridden locally.

cache:paths selects files or directories to cache, e.g., caching all .jar files in the target directory:

build:
  script: test
  cache:
    paths:
      - target/*.jar

When a global cache:paths is defined, it can be overridden in a job, as shown in the example that caches the binaries directory:

cache:
  paths:
    - my/files

build:
  script: echo "hello"
  cache:
    key: build
    paths:
      - target/

To avoid cache collisions between jobs, a unique cache:key can be set. The key can incorporate predefined variables, such as the branch name:

cache:
  key: ${CI_COMMIT_REF_SLUG}

Keys can also be generated from file changes using the files sub‑key, optionally combined with a prefix (e.g., $CI_JOB_NAME) to create distinct caches per job:

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

The cache:policy controls when the cache is downloaded or uploaded. The default pull-push downloads at the start and uploads at the end. Setting policy: pull skips uploading, while policy: push skips downloading.

stages:
  - setup
  - test

prepare:
  stage: setup
  cache:
    key: gems
    paths:
      - vendor/bundle
  script:
    - bundle install --deployment

rspec:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - bundle exec rspec ...

A comprehensive global cache example demonstrates defining a global cache with paths, then using job‑specific scripts, retries, and after‑scripts:

before_script:
  - echo "before-script!!"

variables:
  DOMAIN: example.com

cache:
  paths:
   - target/

stages:
  - build
  - test
  - deploy

build:
  before_script:
    - echo "before-script in job"
  stage: build
  tags:
    - build
  only:
    - master
  script:
    - ls
    - id
    - mvn clean package -DskipTests
    - ls target
    - echo "$DOMAIN"
    - false && true ; exit_code=$?
    - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;
    - sleep 2;
  after_script:
    - echo "after script in job"

unittest:
  stage: test
  tags:
    - build
  only:
    - master
  script:
    - echo "run test"
    - echo 'test' >> target/a.txt
    - ls target
  retry:
    max: 2
    when:
      - script_failure

deploy:
  stage: deploy
  tags:
    - build
  only:
    - master
  script:
    - echo "run deploy"
    - ls target
  retry:
    max: 2
    when:
      - script_failure

after_script:
  - echo "after-script"

The pipeline logs illustrate how the first job builds the project, creates the target directory, and generates a cache. Subsequent jobs retrieve and use this cache, demonstrating the shared nature of caches across jobs.

Runner cache management commands show how to inspect and clean the cache directory on the GitLab Runner host, confirming that caches persist between pipeline runs unless explicitly removed.

In conclusion, a globally defined cache applies to all jobs that do not specify their own cache. If multiple jobs modify the same cache directory, the cache may be overwritten, so careful key management is essential for reliable CI/CD caching.