How to Manage Cache Keys in CircleCI

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:

1. Navigate to your organization's Plan page
2. Go to the Usage Controls section
3. 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

When to Rebuild Caches

• After major dependency updates
• When switching between branches with different dependencies
• If you suspect cache corruption
• During troubleshooting build issues
   

Additional Resources

For more detailed information about CircleCI caching:

• Caching Data Documentation
• Caching Strategies Guide
• Optimizing CircleCI Builds
       

Need additional help? Contact our support team through the CircleCI web app or visit our Community Forum for community-driven solutions