actions/cache
2
0
Fork 0
mirror of https://github.com/actions/cache.git synced 2025-04-01 19:06:35 +00:00
Code Issues Projects Releases Packages Wiki Activity

Review comments and some snippets

Browse source
This commit is contained in:
Sankalp Kotewar 2023-01-05 19:38:09 +00:00 • committed by GitHub
parent c6d92eb236
commit 666171c100
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 189 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

246
CACHING.md
View file

@ -34,23 +34,32 @@ jobs:
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:
```yaml
key: ${{ runner.os }}-cache
```
Cache key by Workflow run id/attempt:
```yaml
key: cache-${{ github.run_id }}-${{ github.run_attempt }}
```
Cache key by commit id:
```yaml
key: cache-${{ github.sha }}
```
Cache key by lockfile:
**Cache key by lockfile**
One of the most common use case is to use hash for lockfile as key. This way same cache will be restored for same lockfiles until there's any change in the lockfile/dependencies.
```yaml
key: cache-${{ hashFiles('**/lockfiles') }}
```
Cache key by combination of multiple options:
**Cache key by Operating system**
Caches can be stored separately for different Operating Systems. This can be used in combination with hashfiles in case multiple caches are being generated per OS.
```yaml
key: ${{ runner.os }}-cache
```
**Cache key by Workflow run id/attempt**
Caches scoped to the particular workflow run id or run attempt can be stored and referred by using the run id/attempt
```yaml
key: cache-${{ github.run_id }}-${{ github.run_attempt }}
```
**Cache key by commit id**
For very short term or isolated use cases, where cache is supposed to be short lived, commit sha can be used.
```yaml
key: cache-${{ github.sha }}
```
**Cache key by combination of multiple options**
Cache key can be formed by combination of more than one metadata, evaluated info.
```yaml
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
```
@ -87,49 +96,130 @@ Whenever a cache is saved, the repository `branch` where it was generated is als
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](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-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](#scope)). If the cache doesn't exist or a partial match is found, the cache is saved in the `post` step.
**Usage**
```yaml
- uses: actions/cache@v3
```
### Sample workflow for cache action
## Restore action
The [restore](https://github.com/actions/cache/tree/main/restore) action allows restoring cache for given key/path combination. The restore action works similar to the `actions/cache` action, except it doesn't save the cache by itself like the `cache` action does.
This action is useful in cases where we only need to restore the cache and not save it.
**Usage**
```yaml
- uses: actions/cache/restore@v3
with:
path: |
path/to/dependencies
some/other/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
```
### Sample workflow for restore action
<!-- Explain how the outputs differ depending on caches found, not found or partially found -->
### Restore only on cache hit (else fail the workflow)
The `restore` action provides three outputs, `cache-hit`, `cache-primary-key` and `cache-matched-key`, more details [here](https://github.com/actions/cache/blob/main/restore/README.md#outputs).
### Make cache read only / Reuse cache from centralized job
In case you are using a centralized job to create and save your cache that can be reused by other jobs in your repository, this action will take care of your restore only needs and make the cache read-only.
```yaml
steps:
- uses: actions/checkout@v3
- uses: actions/cache/restore@v3
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
- name: Install Dependencies
if: steps.cache.outputs.cache-hit != 'true'
run: /install.sh
- name: Build
run: /build.sh
- name: Publish package to public
run: /publish.sh
```
### Exit workflow on cache miss
You can use the output of this action to exit the workflow on cache miss. This way you can restrict your workflow to only initiate the build when `cache-hit` occurs, in other words, cache with exact key is found.
```yaml
steps:
- uses: actions/checkout@v3
- uses: actions/cache/restore@v3
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
- name: Check cache hit
if: steps.cache.outputs.cache-hit != 'true'
run: exit 1
- name: Build
run: /build.sh
```
## Save action
**Usage**
```yaml
- uses: actions/cache/restore@v3
- uses: actions/cache/save@v3
with:
path: |
path/to/dependencies
some/other/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
```
### Sample workflow for save action
<!-- Explain the different ways of taking the inputs here
Saving with hardcoded key - Basic save
Saving with key outputted from restore action
Saving with key re-evaluated at save step
-->
### Re-evaluate cache key while saving
With save action, the key can now be re-evaluated while executing the action. This helps in cases where the lockfiles are generated during the build.
Let's say we have a restore step that computes key at runtime
```yaml
uses: actions/cache/restore@v3
id: restore-cache
with:
key: cache-${{ hashFiles('**/lockfiles') }}
```
Case 1: Where an user would want to reuse the key as it is
```yaml
uses: actions/cache/save@v3
with:
key: ${{ steps.restore-cache.outputs.key }}
```
Case 2: Where the user would want to re-evaluate the key
```yaml
uses: actions/cache/save@v3
with:
key: npm-cache-${{hashfiles(package-lock.json)}}
```
### Always save cache
There are instances where some flaky test cases would fail the entire workflow and users would get frustrated because the builds would run for hours and the cache couldn't get saved as the workflow failed in between. For such use-cases, users would now have the ability to use `actions/cache/save` action to save the cache by using `if: always()` condition. This way the cache will always be saved if generated, or a warning will be thrown that nothing is found on the cache path. Users can also use the `if` condition to only execute the `actions/cache/save` action depending on the output of the previous steps. This way they get more control on when to save the cache.
```yaml
steps:
- uses: actions/checkout@v3
.
. // restore if need be
.
- name: Build
run: /build.sh
- uses: actions/cache/save@v3
if: always() // or any other condition to invoke the save action
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
```
## Restore followed by save
@ -142,30 +232,72 @@ Restore save example with advanced controls
- Fail workflow on cache miss
- Force rewrite cache by deleting cache between steps using cli
-->
### Using Cache action
The [cache](https://github.com/actions/cache/tree/main#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](#scope)). If cache is not found for the given `key` input, then cache is restored using [restore keys](#restore-keys) . If the cache doesn't exist or is restored using `restore-keys`, the cache is saved in the `post` step of this action.
**Usage**
```yaml
- uses: actions/cache@v3
with:
path: |
path/to/dependencies
some/other/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
```
The `cache` action provides one output `cache-hit` which is set to `true` when cache is restored using primary key and `false` when cache is restored using `restore-keys` or no cache is restored.
### Using combination of restore and save actions
## Save followed by restore
<!--
- Use case for saving first and restoring across child/subsequent jobs
- A complex workflow with save and restore actions called multiple times.
- Save cache on any failure.
-->
## Storage & CLI
### Save intermediate private build artifacts
<!--
Mention about the storage quota
UI - how it can be used to view the storage info
CLI - how it can be used in workflows to take care of the cache storage and management
-->
In case of multi-module projects, where the built artifact of one project needs to be reused in subsequent child modules, the need of rebuilding the parent module again and again with every build can be eliminated. The `actions/cache` or `actions/cache/save` action can be used to build and save the parent module artifact once, and restored multiple times while building the child modules.
## Optimisation
<!--
1. Key optimisation examples - create good keys to get more cache match.
2. Storage optimisation examples - avoid recreation of caches whenever not needed.
3. Branch optimisation examples where cache can be restored from default branches but need not be stored for feature branches
4. Cross OS?
-->
#### Step 1 - Build the parent module and save it
```yaml
steps:
- uses: actions/checkout@v3
- name: Build
run: /build-parent-module.sh
- uses: actions/cache/save@v3
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
```
#### Step 2 - Restore the built artifact from cache using the same key and path
```yaml
steps:
- uses: actions/checkout@v3
- uses: actions/cache/restore@v3
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
- name: Install Dependencies
if: steps.cache.outputs.cache-hit != 'true'
run: /install.sh
- name: Build
run: /build-child-module.sh
- name: Publish package to public
run: /publish.sh
```
## Snippets