mirror of
https://code.forgejo.org/actions/cache.git
synced 2025-04-21 16:23:56 +08:00
Cache recipes for cache, restore and save actions (#1055)
* Added outline and cache basics * Update CACHING.md * Added info about key and restore keys * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Review comments and some snippets * Updated doc with comments * Formatted sub headings * Markdown linting * Added paths * Fixed heading * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Update CACHING.md Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com> * Updated paths * Renamed file and added readme reference * Fixed heading of a section * Update README.md * Moved back section to strategies * Reverted to older version * Fixed broken link Co-authored-by: Bishal Prasad <bishal-pdmsft@github.com>
This commit is contained in:
Sankalp Kotewar
GitHub
parent
87396fe6b4
commit
9183691e97
2 changed files with 392 additions and 41 deletions
136
README.md
136
README.md
|
|
@ -14,9 +14,10 @@ In addition to this `cache` action, other two actions are also available
|
|||
|
||||
See ["Caching dependencies to speed up workflows"](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows).
|
||||
|
||||
|
||||
## What's New
|
||||
|
||||
### v3
|
||||
|
||||
* Added support for caching from GHES 3.5.
|
||||
* Fixed download issue for files > 2GB during restore.
|
||||
* Updated the minimum runner version support from node 12 -> node 16.
|
||||
|
|
@ -35,34 +36,39 @@ Refer [here](https://github.com/actions/cache/blob/v2/README.md) for previous ve
|
|||
## Usage
|
||||
|
||||
### Pre-requisites
|
||||
Create a workflow `.yml` file in your repositories `.github/workflows` directory. An [example workflow](#example-workflow) is available below. For more information, reference the GitHub Help Documentation for [Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file).
|
||||
|
||||
Create a workflow `.yml` file in your repositories `.github/workflows` directory. An [example workflow](#example-cache-workflow) is available below. For more information, reference the GitHub Help Documentation for [Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file).
|
||||
|
||||
If you are using this inside a container, a POSIX-compliant `tar` needs to be included and accessible in the execution path.
|
||||
|
||||
### Inputs
|
||||
|
||||
* `path` - A list of files, directories, and wildcard patterns to cache and restore. See [`@actions/glob`](https://github.com/actions/toolkit/tree/main/packages/glob) for supported patterns.
|
||||
* `key` - An explicit key for restoring and saving the cache
|
||||
* `key` - An explicit key for restoring and saving the cache. Refer [creating a cache key](#creating-a-cache-key).
|
||||
* `restore-keys` - An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key.
|
||||
* `enableCrossOsArchive` - An optional boolean when enabled, allows Windows runners to save or restore caches that can be restored or saved respectively on other platforms. Default: false
|
||||
|
||||
#### Environment Variables
|
||||
|
||||
* `SEGMENT_DOWNLOAD_TIMEOUT_MINS` - Segment download timeout (in minutes, default `60`) to abort download of the segment if not completed in the defined number of minutes. [Read more](https://github.com/actions/cache/blob/main/tips-and-workarounds.md#cache-segment-restore-timeout)
|
||||
|
||||
### Outputs
|
||||
|
||||
* `cache-hit` - A boolean value to indicate an exact match was found for the key.
|
||||
* `cache-hit` - A boolean value to indicate an exact match was found for the key.
|
||||
|
||||
> Note: `cache-hit` will be set to `true` only when cache hit occurs for the exact `key` match. For a partial key match via `restore-keys` or a cache miss, it will be set to `false`.
|
||||
|
||||
See [Skipping steps based on cache-hit](#skipping-steps-based-on-cache-hit) for info on using this output
|
||||
|
||||
### Cache scopes
|
||||
|
||||
The cache is scoped to the key, [version](#cache-version) and branch. The default branch cache is available to other branches.
|
||||
|
||||
See [Matching a cache key](https://help.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-key) for more info.
|
||||
|
||||
### Example workflow
|
||||
### Example cache workflow
|
||||
|
||||
#### Restoring and saving cache using a single action
|
||||
|
||||
```yaml
|
||||
name: Caching Primes
|
||||
|
|
@ -91,7 +97,49 @@ jobs:
|
|||
run: /primes.sh -d prime-numbers
|
||||
```
|
||||
|
||||
> Note: You must use the `cache` action in your workflow before you need to use the files that might be restored from the cache. If the provided `key` matches an existing cache, a new cache is not created and if the provided `key` doesn't match an existing cache, a new cache is automatically created provided the job completes successfully.
|
||||
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
|
||||
|
||||
```yaml
|
||||
name: Caching Primes
|
||||
|
||||
on: push
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Restore cached Primes
|
||||
id: cache-primes-restore
|
||||
- uses: actions/cache/restore@v3
|
||||
with:
|
||||
path: |
|
||||
path/to/dependencies
|
||||
some/other/dependencies
|
||||
key: ${{ runner.os }}-primes
|
||||
.
|
||||
. //intermediate workflow steps
|
||||
.
|
||||
- name: Save Primes
|
||||
id: cache-primes-save
|
||||
- uses: actions/cache/save@v3
|
||||
with:
|
||||
path: |
|
||||
path/to/dependencies
|
||||
some/other/dependencies
|
||||
key: ${{ steps.cache-primes-restore.outputs.cache-primary-key }}
|
||||
```
|
||||
|
||||
> **Note**
|
||||
> You must use the `cache` or `restore` action in your workflow before you need to use the files that might be restored from the cache. If the provided `key` matches an existing cache, a new cache is not created and if the provided `key` doesn't match an existing cache, a new cache is automatically created provided the job completes successfully.
|
||||
|
||||
## Caching Strategies
|
||||
|
||||
With introduction of two new actions `restore` and `save`, a lot of caching use cases can now be achieved. Please refer the [caching strategies](./caching-strategies.md) document for understanding how you can use the actions strategically to achieve the desired goal.
|
||||
|
||||
## Implementation Examples
|
||||
|
||||
|
|
@ -99,31 +147,31 @@ Every programming language and framework has its own way of caching.
|
|||
|
||||
See [Examples](examples.md) for a list of `actions/cache` implementations for use with:
|
||||
|
||||
- [C# - NuGet](./examples.md#c---nuget)
|
||||
- [Clojure - Lein Deps](./examples.md#clojure---lein-deps)
|
||||
- [D - DUB](./examples.md#d---dub)
|
||||
- [Deno](./examples.md#deno)
|
||||
- [Elixir - Mix](./examples.md#elixir---mix)
|
||||
- [Go - Modules](./examples.md#go---modules)
|
||||
- [Haskell - Cabal](./examples.md#haskell---cabal)
|
||||
- [Haskell - Stack](./examples.md#haskell---stack)
|
||||
- [Java - Gradle](./examples.md#java---gradle)
|
||||
- [Java - Maven](./examples.md#java---maven)
|
||||
- [Node - npm](./examples.md#node---npm)
|
||||
- [Node - Lerna](./examples.md#node---lerna)
|
||||
- [Node - Yarn](./examples.md#node---yarn)
|
||||
- [OCaml/Reason - esy](./examples.md#ocamlreason---esy)
|
||||
- [PHP - Composer](./examples.md#php---composer)
|
||||
- [Python - pip](./examples.md#python---pip)
|
||||
- [Python - pipenv](./examples.md#python---pipenv)
|
||||
- [R - renv](./examples.md#r---renv)
|
||||
- [Ruby - Bundler](./examples.md#ruby---bundler)
|
||||
- [Rust - Cargo](./examples.md#rust---cargo)
|
||||
- [Scala - SBT](./examples.md#scala---sbt)
|
||||
- [Swift, Objective-C - Carthage](./examples.md#swift-objective-c---carthage)
|
||||
- [Swift, Objective-C - CocoaPods](./examples.md#swift-objective-c---cocoapods)
|
||||
- [Swift - Swift Package Manager](./examples.md#swift---swift-package-manager)
|
||||
- [Swift - Mint](./examples.md#swift---mint)
|
||||
* [C# - NuGet](./examples.md#c---nuget)
|
||||
* [Clojure - Lein Deps](./examples.md#clojure---lein-deps)
|
||||
* [D - DUB](./examples.md#d---dub)
|
||||
* [Deno](./examples.md#deno)
|
||||
* [Elixir - Mix](./examples.md#elixir---mix)
|
||||
* [Go - Modules](./examples.md#go---modules)
|
||||
* [Haskell - Cabal](./examples.md#haskell---cabal)
|
||||
* [Haskell - Stack](./examples.md#haskell---stack)
|
||||
* [Java - Gradle](./examples.md#java---gradle)
|
||||
* [Java - Maven](./examples.md#java---maven)
|
||||
* [Node - npm](./examples.md#node---npm)
|
||||
* [Node - Lerna](./examples.md#node---lerna)
|
||||
* [Node - Yarn](./examples.md#node---yarn)
|
||||
* [OCaml/Reason - esy](./examples.md#ocamlreason---esy)
|
||||
* [PHP - Composer](./examples.md#php---composer)
|
||||
* [Python - pip](./examples.md#python---pip)
|
||||
* [Python - pipenv](./examples.md#python---pipenv)
|
||||
* [R - renv](./examples.md#r---renv)
|
||||
* [Ruby - Bundler](./examples.md#ruby---bundler)
|
||||
* [Rust - Cargo](./examples.md#rust---cargo)
|
||||
* [Scala - SBT](./examples.md#scala---sbt)
|
||||
* [Swift, Objective-C - Carthage](./examples.md#swift-objective-c---carthage)
|
||||
* [Swift, Objective-C - CocoaPods](./examples.md#swift-objective-c---cocoapods)
|
||||
* [Swift - Swift Package Manager](./examples.md#swift---swift-package-manager)
|
||||
* [Swift - Mint](./examples.md#swift---mint)
|
||||
|
||||
## Creating a cache key
|
||||
|
||||
|
|
@ -167,6 +215,7 @@ A repository can have up to 10GB of caches. Once the 10GB limit is reached, olde
|
|||
Using the `cache-hit` output, subsequent steps (such as install or build) can be skipped when a cache hit occurs on the key. It is recommended to install the missing/updated dependencies in case of a partial key match when the key is dependent on the `hash` of the package file.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
|
@ -184,11 +233,11 @@ steps:
|
|||
|
||||
> Note: The `id` defined in `actions/cache` must match the `id` in the `if` statement (i.e. `steps.[ID].outputs.cache-hit`)
|
||||
|
||||
|
||||
## Cache Version
|
||||
Cache version is a hash [generated](https://github.com/actions/toolkit/blob/500d0b42fee2552ae9eeb5933091fe2fbf14e72d/packages/cache/src/internal/cacheHttpClient.ts#L73-L90) 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 can't be restored on `ubuntu-latest` as cache `Version`s are different.
|
||||
|
||||
> Pro tip: [List caches](https://docs.github.com/en/rest/actions/cache#list-github-actions-caches-for-a-repository) API can be used to get the version of a cache. This can be helpful to troubleshoot cache miss due to version.
|
||||
Cache version is a hash [generated](https://github.com/actions/toolkit/blob/500d0b42fee2552ae9eeb5933091fe2fbf14e72d/packages/cache/src/internal/cacheHttpClient.ts#L73-L90) 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 can't be restored on `ubuntu-latest` as cache `Version`s are different.
|
||||
|
||||
> Pro tip: [List caches](https://docs.github.com/en/rest/actions/cache#list-github-actions-caches-for-a-repository) API can be used to get the version of a cache. This can be helpful to troubleshoot cache miss due to version.
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
|
@ -239,22 +288,27 @@ jobs:
|
|||
if: steps.cache-primes.outputs.cache-hit != 'true'
|
||||
run: ./generate-primes -d prime-numbers
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Known practices and workarounds
|
||||
|
||||
Following are some of the known practices/workarounds which community has used to fulfill specific requirements. You may choose to use them if suits your use case. Note these are not necessarily the only or the recommended solution.
|
||||
|
||||
- [Cache segment restore timeout](./tips-and-workarounds.md#cache-segment-restore-timeout)
|
||||
- [Update a cache](./tips-and-workarounds.md#update-a-cache)
|
||||
- [Use cache across feature branches](./tips-and-workarounds.md#use-cache-across-feature-branches)
|
||||
- [Cross OS cache](./tips-and-workarounds.md#cross-os-cache)
|
||||
- [Force deletion of caches overriding default cache eviction policy](./tips-and-workarounds.md#force-deletion-of-caches-overriding-default-cache-eviction-policy)
|
||||
* [Cache segment restore timeout](./tips-and-workarounds.md#cache-segment-restore-timeout)
|
||||
* [Update a cache](./tips-and-workarounds.md#update-a-cache)
|
||||
* [Use cache across feature branches](./tips-and-workarounds.md#use-cache-across-feature-branches)
|
||||
* [Cross OS cache](./tips-and-workarounds.md#cross-os-cache)
|
||||
* [Force deletion of caches overriding default cache eviction policy](./tips-and-workarounds.md#force-deletion-of-caches-overriding-default-cache-eviction-policy)
|
||||
|
||||
#### Windows environment variables
|
||||
Please note that Windows environment variables (like `%LocalAppData%`) will NOT be expanded by this action. Instead, prefer using `~` in your paths which will expand to HOME directory. For example, instead of `%LocalAppData%`, use `~\AppData\Local`. For a list of supported default environment variables, see [this](https://docs.github.com/en/actions/learn-github-actions/environment-variables) page.
|
||||
### Windows environment variables
|
||||
|
||||
Please note that Windows environment variables (like `%LocalAppData%`) will NOT be expanded by this action. Instead, prefer using `~` in your paths which will expand to HOME directory. For example, instead of `%LocalAppData%`, use `~\AppData\Local`. For a list of supported default environment variables, see [this](https://docs.github.com/en/actions/learn-github-actions/environment-variables) page.
|
||||
|
||||
## Contributing
|
||||
|
||||
We would love for you to contribute to `actions/cache`, pull requests are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
|
||||
|
||||
## License
|
||||
|
||||
The scripts and documentation in this project are released under the [MIT License](LICENSE)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue