Skip to main content
Mapagam

Implementing Caching Strategies

1. Defining Cache Configuration

Property Description Values Notes
cache.key Cache key to use for caching string or object Used to identify the cache uniquely. Can be a string or an object with files and prefix.
cache.paths Paths to cache array of string Directories or files to cache. Supports glob patterns.
cache.uncompressed Whether to compress cache true or false Defaults to false. Set to true to disable compression.
cache.ttl Time-to-live for cache string Example: 1 day, 30 minutes. Defaults to 7 days.

Example: Basic Cache Configuration

cache:
  key: "${CI_COMMIT_REF_SLUG}"
  paths:
    - node_modules/
    - .npm/

Example: Cache with TTL

cache:
  key: "${CI_COMMIT_REF_SLUG}"
  paths:
    - vendor/
  ttl: "1 hour"

2. Setting Cache Paths

Property Values Description
cache.key string Defines the cache key used to retrieve and store the cache. Can include variables like $CI_COMMIT_REF_NAME or $CI_JOB_NAME.
cache.paths array of strings List of files and directories to cache. Supports wildcards like node_modules/ or **/*.log.
cache.uncompressed boolean If true, disables compression of the cache. Defaults to false.

Example: Basic Cache Configuration

cache:
  key: $CI_COMMIT_REF_NAME
  paths:
    - node_modules/
    - .npm/

Example: Cache with Wildcards

cache:
  key: $CI_COMMIT_REF_NAME
  paths:
    - dist/
    - build/
    - logs/**/*.log

3. Using Cache Keys

Cache Key Description Examples
cache:key Defines the cache key for a job's cache cache:key: $CI_JOB_NAME
cache:key:files Cache key based on files in the project cache:key:files: $CI_COMMIT_REF_NAME
cache:key:prefix Prefix for cache keys to avoid collisions cache:key:prefix: $CI_PROJECT_ID

Example: Using Cache Keys in a Job

job_with_cache:
  script:
    - npm install
  cache:
    key: $CI_COMMIT_REF_NAME
    paths:
      - node_modules/
Note: Cache keys are case-sensitive and must be unique per job to prevent conflicts.

4. Creating Dynamic Cache Keys

Cache Key Component Description Example
cache.key Defines the cache key pattern used to store and retrieve cache entries cache.key: $CI_COMMIT_REF_SLUG
cache.paths Specifies the directories or files to cache cache.paths: [node_modules/]
cache.uncompressed Controls whether to compress cache entries (default: true) cache.uncompressed: false

Example: Using GitLab CI Variables in Cache Keys

cache:
  key: $CI_COMMIT_REF_SLUG
  paths:
    - node_modules/

Example: Dynamic Cache Key with Build Dependencies

cache:
  key: $CI_COMMIT_REF_SLUG-$CI_COMMIT_SHORT_SHA
  paths:
    - vendor/
Note: Cache keys must be unique per branch or commit to avoid conflicts. Using $CI_COMMIT_REF_SLUG ensures that each branch has its own cache.

5. Using Cache Key Prefix

Property Description Example
cache.key Defines the cache key prefix used for caching artifacts in GitLab CI/CD. cache.key: $CI_COMMIT_REF_SLUG
cache.paths Specifies the directories or files to cache. cache.paths: [node_modules/]
cache.uncompressed Controls whether to compress the cache. Default is true. cache.uncompressed: false

Example: Cache Key Prefix with Branch Name

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - node_modules/

Example: Cache Key with Build Type

cache:
  key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
  paths:
    - dist/

6. Setting Cache Policy

Policy Description Usage
cache.key Defines the cache key for restoring and storing cache cache: section in job configuration
cache.paths List of files/directories to cache cache: section in job configuration
cache.uncompressed Cache files in uncompressed format (default: true) cache: section in job configuration
cache.ttl Time-to-live for cache entries (default: 1 week) cache: section in job configuration

Example: Basic Cache Configuration

job_name:
  cache:
    key: "${CI_COMMIT_REF_SLUG}"
    paths:
      - node_modules/
      - .npm/

Example: Cache with TTL

job_name:
  cache:
    key: "${CI_COMMIT_REF_SLUG}"
    paths:
      - vendor/
    ttl: 1 day

7. Configuring Cache Fallback

Option Values Description
cache.key string Defines the cache key used to store and retrieve cache entries. Can include variables like $CI_COMMIT_REF_NAME or $CI_COMMIT_SHORT_SHA.
cache.paths array List of files and directories to cache. Supports wildcards like node_modules/.
cache.uncompressed boolean If true, disables compression of the cache. Defaults to false.
cache.fallback_keys array Defines fallback cache keys to use if the primary key does not exist. Allows for cache reuse across branches or tags.

Example: Configuring Cache Fallback

cache:
  key: "$CI_COMMIT_REF_NAME"
  paths:
    - node_modules/
  fallback_keys:
    - "master"
    - "release-*"
Note: Cache fallback keys are useful for reusing cache across different branches or tags when the primary key is not found.

8. Using Distributed Cache

Example: Configuring GitLab CI to use a Redis cache

cache:
  key: "${CI_COMMIT_REF_SLUG}"
  paths:
    - node_modules/
  policy: pull-push
  service: redis://redis-cache:6379

job_name:
  script:
    - npm install
Property Description Values Notes
cache.key Cache key to use for cache lookup and storage ${CI_COMMIT_REF_SLUG} Unique identifier for cache
cache.paths List of paths to cache node_modules/ Directories to include in cache
cache.policy Cache policy to use pull-push, pull, push pull-push is default
cache.service Cache service URL to use redis://redis-cache:6379 URL to distributed cache service
Note: Distributed caching is supported in GitLab CI/CD v15.0+.
Warning: Ensure cache service is accessible from all runners.

9. Optimizing Cache for Dependencies

Cache Key Pattern Description Example
cache.key Defines the cache key for dependencies dependencies-${CI_COMMIT_REF_SLUG}
cache.paths Paths to cache and restore node_modules/
cache.uncompressed Whether to compress cache (default: true) false

Example: Caching Node.js Dependencies

cache:
  key: "node-modules-${CI_COMMIT_REF_SLUG}"
  paths:
    - node_modules/
  uncompressed: false
Note: Use cache.key with a unique identifier to avoid cache collisions.
Warning: Caching large directories can slow down job execution.
Cache Strategy Use Case Best Practice
cache.key Versioned cache keys Include branch or tag in key
cache.paths Directories to cache Only cache necessary paths
cache.uncompressed Compression control Disable for large files

10. Clearing Cache

Cache Type Command Notes
Pipeline Cache gitlab-runner cache clear Clears the runner's local cache directory
Shared Cache gitlab-runner cache clear --shared Clears shared cache across runners
Specific Cache Key gitlab-runner cache clear --key <cache-key> Clears cache for a specific key

Example: Clearing Pipeline Cache

gitlab-runner cache clear
# Output:
# Cache cleared successfully
Note: Clearing cache may cause longer build times as dependencies will need to be re-downloaded.

Was this article helpful?

Related Cheat Sheets