Overview

CircleCI's built-in caching system helps speed up your builds by storing dependencies and other files between job runs. Cache keys are template-formatted strings that determine when your cache should be updated. This article explains how to create effective cache keys, manually rebuild caches, and understand cache expiration in CircleCI.

Understanding Cache Keys

Basic Cache Key Structure

A cache key uses a template format that typically includes:

A descriptive prefix (like your app name)
A checksum of dependency files
Optional versioning components

Example:

myapp-{{ checksum "package-lock.json" }}

This generates a cache key like:

myapp-+KlBebDceJh_zOWQIAJDLEkdkKoeldAldkaKiallQ

This cache will automatically update whenever you modify your package-lock.json file, ensuring your dependencies stay current.

Cache Expiration and Deletion

Automatic Cache Expiration

CircleCI caches cannot be deleted manually or on-demand. Instead, each cache has an automatic expiration date set when it's created.

To view or modify your cache retention period:

Navigate to your organization's Plan page
Go to the Usage Controls section
Review the current retention period settings

When Caches Expire

Caches are automatically removed after the retention period expires
The retention period varies based on your CircleCI plan
Expired caches are permanently deleted and cannot be recovered

Manually Rebuilding Caches

Using Version Prefixes

To force a cache rebuild without waiting for file changes, add a version prefix to your cache key using environment variables.
Step 1: Set a Cache Version Environment Variable

Go to your project settings in the CircleCI web app
Navigate to Environment Variables
Add a new variable: CACHE_VERSION=v1

Step 2: Update Your Config

Modify your cache key template to include the version:

myapp-{{ .Environment.CACHE_VERSION }}-{{ checksum "package-lock.json" }}

This expands to:

myapp-v1-+KlBebDceJh_zOWQIAJDLEkdkKoeldAldkaKiallQ

Step 3: Increment When Needed

When you need to rebuild your cache:

Return to your project's environment variables
Update CACHE_VERSION to v2(or the next version number)
Your next build will create a fresh cache with the new key

Best Practices for Cache Versioning

Use semantic versioning (v1, v2, v3) for clarity
Document version changes in your team's workflow
Consider using date-based versions (2024-01-15) for time-sensitive rebuilds
Keep version names short to avoid overly long cache keys

Troubleshooting Cache Issues

Common Cache Problems

Stale dependencies:Increment your cache version to force a rebuild
Build failures after dependency updates: Check if your lock files have changed
Slow builds: Verify your cache keys are properly configured