Introduction
GitHub Actions provide two ways of storing files: caching for things like dependencies
and artifacts
for the results of a job, such as logs or binaries. Although they sound similar, they are used for different purposes. So, we will use caching to speed up our workflow runs.
Another thing to know is that cache access will be restricted to only a few branches: the current branch
, the base branch
for pull requests
, and the default branch
. Caches created in unrelated branches won't be available, but that's not something that will affect us in most cases, since we usually operate on either current or base branches.
Proper use of caching can help reduce build times, especially for projects whose dependencies do not change very often.
Choosing the Right Cache Key
We can create metadata-based cache keys, such as OS or commit hashes, that let us only reuse dependencies when absolutely needed. We can also make use of restore keys to get near matches for caches that help minimize rebuild times.
Generally speaking, for such workflows running on multi-OS environments, it is also a good practice to isolate the caches per-OS to avoid cross-platform unnecessary rebuilds. Sometimes we might even use temporary caches valid for only one run, which is useful when we do not need long-term reuse.
- uses: actions/cache@v4
with:
path: path/to/dependencies
# generate a cache key based on the hash of lockfiles
key: cache-${{ hashFiles('**/lockfiles') }}
- uses: actions/cache@v4
with:
path: path/to/dependencies
key: cache-${{ hashFiles('**/lockfiles') }}
# restore keys for closest matches. This minimizes the time spent downloading newer dependencies
restore-keys: |
cache-npm-
- uses: actions/cache@v4
with:
path: path/to/dependencies
#key: cache-${{ hashFiles('**/lockfiles') }}
# OS-specific caches to avoid unnecessary rebuilds across different platforms
key: ${{ runner.os }}-cache
restore-keys: |
cache-npm-
- uses: actions/cache@v4
with:
path: path/to/dependencies
#key: cache-${{ hashFiles('**/lockfiles') }}
#key: ${{ runner.os }}-cache
# short-lived caches for one-time use
key: cache-${{ github.run_id }}-${{ github.run_attempt }}
restore-keys: |
cache-npm-
We can also share caches across jobs, centralizing cache creation to save time, and ensure caches are saved even if a build fails by using the always()
condition.
# Centralized cache reuse
- id: cache-primes-save
uses: actions/cache/save@v4 # Save cache
with:
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
- uses: actions/cache/restore@v4 # Restore cache
with:
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
# Save cache after build failure
- uses: actions/cache@v4
with:
path: path/to/dependencies
key: cache-${{ hashFiles('**/lockfiles') }}
if: always()
GitHub Actions Package Manager Caching Examples
I've assembled some sample caching for the various package managers in use: npm
, pip
, Maven
, and NuGet
. The following configuration should avoid the redownload of dependencies in each workflow run. For example, we do not cache node_modules in the case of npm in order to avoid the case where different Node versions will create problems.
Instead, we cache npm
itself dynamically. Pip's cache must be different depending on the OS, and we do the same on Maven
and NuGet
for their respective repository paths and lock files.
# Cache npm dependencies
- uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
# Cache pip dependencies
- uses: actions/cache@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
# Cache Maven dependencies
- uses: actions/cache@v4
with:
path: ~/.m2/repository
key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
# Cache NuGet dependencies
- uses: actions/cache@v4
with:
path: ~/.nuget/packages
key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
restore-keys: ${{ runner.os }}-nuget-
Conclusion
Caching in GitHub Actions means how to optimize the continuous integration workflow by basically avoiding duplicate tasks, for example, re-downloading the dependencies. Carefully selecting metadata, operating system, or lock file-based cache keys, finding close matches with restore keys, and keeping the number less will highly reduce build times. Keep separate caches at different operating systems and use transient caches for one-time build.
Monitoring GitHub Actions Workflows
CICube is a GitHub Actions monitoring tool that provides you with detailed insights into your workflows to further optimize your CI/CD pipeline. With CICube, you will be able to track your workflow runs, understand where the bottlenecks are, and tease out the best from your build times. Go to cicube.io now and create a free account to better optimize your GitHub Actions workflows!