6.5 KiB
Cache Recipes
This document focuses on gathering all the common use cases that will help the users of actions/cache
- Know the use cases that can be tackled and sample workflows on how to tackle them
- Optimise their workflows to use the cache inputs and outputs better
Actions Cache Basics
The cache action works using the following set of inputs and outputs as mentioned here. However these inputs are self explaining below are some ways in which the inputs can be used in a better way.
Keys
A key, also referred as primary key is a value with which cache is restored or saved. If cache is not found with the primary key, the same key is used to save the cache in the actions/cache action.
Static keys
- uses: actions/cache@v3
with:
key: static-key
In your workflows, you can use keys in a hardcoded manner. This way the same key will be saved once and restored till its evicted. In case the key gets evicted, cache with same key will be created again and saved.
Dynamic keys
jobs:
build:
runs-on: ubuntu-latest
- uses: actions/cache@v3
with:
key: ${{ runner.os }}-cache
In your workflows, if you wish to create OS specific caches, or caches based on the lockfiles, commit SHA, workflow run id, etc. then you can generate the keys dynamically at run-time. Below are some of the ways to use dynamically generated keys
Cache key by Operating system:
key: ${{ runner.os }}-cache
Cache key by Workflow run id/attempt:
key: cache-${{ github.run_id }}-${{ github.run_attempt }}
Cache key by commit id:
key: cache-${{ github.sha }}
Cache key by lockfile:
key: cache-${{ hashFiles('**/lockfiles') }}
Cache key by combination of multiple options:
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
The GitHub Context can be used to create keys using the workflows metadata.
Restore keys
Restore keys are a set of keys that are looked for when cache with primary key is not found. The first matching cache is downloaded when restore keys are provided.
The restore keys can be provided as a complete name, or a prefix, read more here on how a cache key is matched using restore keys.
Paths
The path(s) in the cache action define(s) the path/directory that needs to be cached. The directory can reside on the runner or containers inside runners. The path to dependencies can either be a fix path or a glob pattern that's matched with existing directory structure and evaluated at runtime. Refer @actions/glob to get more information about the patterns.
Examples:
Version
Cache version is a hash generated for a combination of compression tool used (Gzip, Zstd, etc. based on the runner OS) and the path of directories being cached. If two caches have different versions, they are identified as unique caches while matching. This for example, means that a cache created on windows-latest runner may not be restored on ubuntu-latest as cache versions could be different.
TL;DR Version = hash(Compression tool, Path(s) to be cached)
Branch
Whenever a cache is saved, the repository branch where it was generated is also stored along with it. This is done mainly to avoid caches from feature branches to interact with jobs running on the default branch.
Scope
The cache is scoped to a key, version and branch. The default branch cache is accessible to all other branches, but not the other way round. This means if you have a cache with key matching (completely or partially) and (exact) version in the default branch, you will be able to restore the cache in any of the branches. However if you create a cache in a feature branch, it cannot be restored in any other branch. Refer matching the key for more info on how keys are matched and restored.
Cache action
The cache action allows caching dependencies and build outputs to improve workflow execution time.
It has a main step and a post step. In the main step, the cache is restored if it exists for the input key, path combination (refer scope). If the cache doesn't exist or a partial match is found, the cache is saved in the post step.
Usage
- uses: actions/cache@v3
Sample workflow for cache action
Restore action
Usage
- uses: actions/cache/restore@v3
Sample workflow for restore action
Restore only on cache hit (else fail the workflow)
Make cache read only / Reuse cache from centralized job
Save action
Usage
- uses: actions/cache/restore@v3