From 6b9f3f8fba71af0e7e20bb24754aec46f2196b71 Mon Sep 17 00:00:00 2001 From: Danila Danko Date: Tue, 13 Feb 2024 23:19:27 +0300 Subject: [PATCH] refactor: format using prettier --- README.md | 382 +++++++++++++++++++++++----------------------- restore/README.md | 2 +- save/README.md | 6 +- 3 files changed, 197 insertions(+), 193 deletions(-) diff --git a/README.md b/README.md index a2c0873f..85273efc 100644 --- a/README.md +++ b/README.md @@ -6,48 +6,49 @@ This action is based on [actions/cache](https://github.com/actions/cache). ## What it can -* Restore and save the Nix store on `Linux` and `macOS` runners. -* Restore and save other directories on `Linux`, `macOS`, and `Windows` runners. -* Collect garbage in the Nix store before saving a new cache. -* Merge caches produced by several jobs. -* Purge caches created or last accessed at least the given time ago. +- Restore and save the Nix store on `Linux` and `macOS` runners. +- Restore and save other directories on `Linux`, `macOS`, and `Windows` runners. +- Collect garbage in the Nix store before saving a new cache. +- Merge caches produced by several jobs. +- Purge caches created or last accessed at least the given time ago. ## A typical job 1. The [nix-quick-install-action](https://github.com/nixbuild/nix-quick-install-action) installs Nix and makes `/nix/store` owned by an unpriviliged user. 1. `Restore` phase: - 1. The `cache-nix-action` tries to restore a cache whose key is the same as the primary key. - 1. When it can't restore, the `cache-nix-action` tries to restore a cache whose key matches a prefix in a given list of key prefixes. + 1. The `cache-nix-action` tries to restore a cache whose key is the same as the primary key. - 1. The `cache-nix-action` restores all caches whose keys match some of the prefixes in another given list of key prefixes. + 1. When it can't restore, the `cache-nix-action` tries to restore a cache whose key matches a prefix in a given list of key prefixes. + + 1. The `cache-nix-action` restores all caches whose keys match some of the prefixes in another given list of key prefixes. 1. Other job steps run. 1. `Post Restore` phase: - 1. The `cache-nix-action` purges caches whose keys are the same as the primary key and that were created more than a given time ago. + 1. The `cache-nix-action` purges caches whose keys are the same as the primary key and that were created more than a given time ago. - 1. When there's no cache whose key is the same as the primary key, the `cache-nix-action` collects garbage in the Nix store and saves a new cache. + 1. When there's no cache whose key is the same as the primary key, the `cache-nix-action` collects garbage in the Nix store and saves a new cache. - 1. The `cache-nix-action` purges caches whose keys match some of the given prefixes in a given list of key prefixes and that were created more than a given time ago relative to the start of the `Post Restore` phase. + 1. The `cache-nix-action` purges caches whose keys match some of the given prefixes in a given list of key prefixes and that were created more than a given time ago relative to the start of the `Post Restore` phase. ## Limitations -* Requires `nix-quick-install-action`. -* Supports only `Linux` and `macOS` runners for Nix store caching. -* `GitHub` allows only `10GB` of caches and then removes the least recently used entries (see its [eviction policy](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy)). Workarounds: - * [Purge old caches](#purge-old-caches) - * [Merge caches](#merge-caches) -* Nix store size is limited by a runner storage size ([link](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)). Workaround: - * The [jlumbroso/free-disk-space](https://github.com/jlumbroso/free-disk-space) action frees `~30GB` of disk space in several minutes. -* Caches are isolated for restoring between refs ([link](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)). Workaround: - * Provide caches for PRs on the default or base branches. -* For purging, a workflow requires the permission `actions: write` and the `token` must have a `repo` scope ([link](https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28#delete-github-actions-caches-for-a-repository-using-a-cache-key)). -* Purges caches scoped to the current [GITHUB_REF](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables). -* Purges caches by keys without considering caches versions (see [Cache version](#cache-version)). -* Runs `tar ... --skip-old-files ...` to not overwrite existing files when restoring a cache (see [this comment](https://github.com/nix-community/cache-nix-action/issues/9#issuecomment-1871311709)). +- Requires `nix-quick-install-action`. +- Supports only `Linux` and `macOS` runners for Nix store caching. +- `GitHub` allows only `10GB` of caches and then removes the least recently used entries (see its [eviction policy](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy)). Workarounds: + - [Purge old caches](#purge-old-caches) + - [Merge caches](#merge-caches) +- Nix store size is limited by a runner storage size ([link](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)). Workaround: + - The [jlumbroso/free-disk-space](https://github.com/jlumbroso/free-disk-space) action frees `~30GB` of disk space in several minutes. +- Caches are isolated for restoring between refs ([link](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)). Workaround: + - Provide caches for PRs on the default or base branches. +- For purging, a workflow requires the permission `actions: write` and the `token` must have a `repo` scope ([link](https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28#delete-github-actions-caches-for-a-repository-using-a-cache-key)). +- Purges caches scoped to the current [GITHUB_REF](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables). +- Purges caches by keys without considering caches versions (see [Cache version](#cache-version)). +- Runs `tar ... --skip-old-files ...` to not overwrite existing files when restoring a cache (see [this comment](https://github.com/nix-community/cache-nix-action/issues/9#issuecomment-1871311709)). ## Comparison with alternative approaches @@ -55,8 +56,8 @@ See [Caching Approaches](#caching-approaches). ## Additional actions -* [Restore action](./restore/README.md) -* [Save action](./save/README.md) +- [Restore action](./restore/README.md) +- [Save action](./save/README.md) ## Example steps @@ -83,11 +84,11 @@ See [Caching Approaches](#caching-approaches). purge-primary-key: never ``` -* `nix-quick-install-action` loads `nixConfig` from `flake.nix` and writes to [nix.conf](https://nixos.org/manual/nix/unstable/command-ref/conf-file.html) (see [action.yml](https://github.com/nixbuild/nix-quick-install-action/blob/master/action.yml) in `the nix-quick-install` repo). -* Due to `gc-max-store-size-linux: 1073741824`, on `Linux` runners, garbage in the Nix store is collected until store size reaches `1GB` or until there's no garbage to collect. -* Since `gc-max-store-size-macos` isn't set to a number, on `macOS` runners, no garbage is collected in the Nix store. -* The `cache-nix-action` purges caches: - * (with a key prefix `cache-${{ matrix.os }}-`) **AND** (created more than `42` seconds ago **OR** last accessed more than `42` seconds ago). +- `nix-quick-install-action` loads `nixConfig` from `flake.nix` and writes to [nix.conf](https://nixos.org/manual/nix/unstable/command-ref/conf-file.html) (see [action.yml](https://github.com/nixbuild/nix-quick-install-action/blob/master/action.yml) in `the nix-quick-install` repo). +- Due to `gc-max-store-size-linux: 1073741824`, on `Linux` runners, garbage in the Nix store is collected until store size reaches `1GB` or until there's no garbage to collect. +- Since `gc-max-store-size-macos` isn't set to a number, on `macOS` runners, no garbage is collected in the Nix store. +- The `cache-nix-action` purges caches: + - (with a key prefix `cache-${{ runner.os }}-`) **AND** (created more than `42` seconds ago **OR** last accessed more than `42` seconds ago). ### Example workflow @@ -143,7 +144,7 @@ See [action.yml](action.yml). ### Troubleshooting -* Use [action-tmate](https://github.com/mxschmitt/action-tmate) to debug on a runner via SSH. +- Use [action-tmate](https://github.com/mxschmitt/action-tmate) to debug on a runner via SSH. ### Garbage collection parameters @@ -188,21 +189,22 @@ These distances affect the restore and save speed. ### GitHub Actions -* [DeterminateSystems/magic-nix-cache-action](https://github.com/DeterminateSystems/magic-nix-cache-action) -* [nix-community/cache-nix-action](https://github.com/nix-community/cache-nix-action) +- [DeterminateSystems/magic-nix-cache-action](https://github.com/DeterminateSystems/magic-nix-cache-action) +- [nix-community/cache-nix-action](https://github.com/nix-community/cache-nix-action) #### cache-nix-action **Pros**: -* Free. -* Uses `GitHub Actions Cache` and works fast. -* Easy to set up. -* Allows to save a store of at most a given size (see [Garbage collection parameters](#garbage-collection-parameters)). -* Allows to save outputs from garbage collection (see [Garbage collection](#garbage-collection)). -* When there's a cache hit, restoring from a GitHub Actions cache can be faster than downloading multiple paths from binary caches. - * You can compare run times of jobs with and without store caching in [Actions](https://github.com/nix-community/cache-nix-action/actions/workflows/ci.yaml). - * Open a run and click on the time under `Total duration`. +- Free. +- Easy to set up. +- Uses `GitHub Actions Cache` and works fast. +- Doesn't require repository secrets. +- Allows to save a store of at most a given size (see [Garbage collection parameters](#garbage-collection-parameters)). +- Allows to save outputs from garbage collection (see [Garbage collection](#garbage-collection)). +- When there's a cache hit, restoring from a GitHub Actions cache can be faster than downloading multiple paths from binary caches. + - You can compare run times of jobs with and without store caching in [Actions](https://github.com/nix-community/cache-nix-action/actions/workflows/ci.yaml). + - Open a run and click on the time under `Total duration`. **Cons**: see [Limitations](#limitations) @@ -210,18 +212,18 @@ These distances affect the restore and save speed. **Pros** ([link](https://github.com/DeterminateSystems/magic-nix-cache#why-use-the-magic-nix-cache)): -* Free. -* Uses `GitHub Actions Cache` and works fast. -* Easy to set up. -* Restores and saves paths selectively. +- Free. +- Easy to set up. +- Uses `GitHub Actions Cache` and works fast. +- Restores and saves paths selectively. **Cons**: -* Collects telemetry ([link](https://github.com/DeterminateSystems/magic-nix-cache)) -* May trigger rate limit errors ([link](https://github.com/DeterminateSystems/magic-nix-cache#usage-notes)). -* Follows the GitHub Actions Cache semantics ([link](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)). - * Caches are isolated between branches ([link](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)). -* Saves a cache for each path in a store and quickly litters `Caches`. +- Collects telemetry ([link](https://github.com/DeterminateSystems/magic-nix-cache)) +- May trigger rate limit errors ([link](https://github.com/DeterminateSystems/magic-nix-cache#usage-notes)). +- Follows the GitHub Actions Cache semantics ([link](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)). + - Caches are isolated between branches ([link](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)). +- Saves a cache for each path in a store and quickly litters `Caches`. #### actions/cache @@ -231,11 +233,11 @@ If used with [install-nix-action](https://github.com/cachix/install-nix-action) **Pros**: -* Quick restore and save `/tmp/nix`. +- Quick restore and save `/tmp/nix`. **Cons**: -* Slow [nix copy](https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-copy.html) from `/tmp/nix` to `/nix/store`. +- Slow [nix copy](https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-copy.html) from `/tmp/nix` to `/nix/store`. If used with [install-nix-action](https://github.com/cachix/install-nix-action) and this [trick](https://github.com/cachix/install-nix-action/issues/56#issuecomment-1030697681), it's similar to the [cache-nix-action](#cache-nix-action), but slower ([link](https://github.com/ryantm/nix-installer-action-benchmark)). @@ -243,21 +245,21 @@ If used with [install-nix-action](https://github.com/cachix/install-nix-action) See [binary cache](https://nixos.org/manual/nix/unstable/glossary.html#gloss-binary-cache), [HTTP Binary Cache Store](https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-help-stores.html#http-binary-cache-store). -* [cachix](https://www.cachix.org/) -* [attic](https://github.com/zhaofengli/attic) +- [cachix](https://www.cachix.org/) +- [attic](https://github.com/zhaofengli/attic) **Pros**: -* Restore and save paths selectively. -* Provide least recently used garbage collection strategies ([cachix](https://docs.cachix.org/garbage-collection?highlight=garbage), [attic](https://github.com/zhaofengli/attic#goals)). -* Don't cache paths available from the NixOS cache ([cachix](https://docs.cachix.org/garbage-collection?highlight=upstream)). -* Allow to share paths between projects ([cachix](https://docs.cachix.org/getting-started#using-binaries-with-nix)). +- Restore and save paths selectively. +- Provide least recently used garbage collection strategies ([cachix](https://docs.cachix.org/garbage-collection?highlight=garbage), [attic](https://github.com/zhaofengli/attic#goals)). +- Don't cache paths available from the NixOS cache ([cachix](https://docs.cachix.org/garbage-collection?highlight=upstream)). +- Allow to share paths between projects ([cachix](https://docs.cachix.org/getting-started#using-binaries-with-nix)). **Cons**: -* Have limited free storage ([cachix](https://www.cachix.org/pricing) gives 5GB for open-source projects). -* Need good bandwidth for receiving and pushing paths over the Internet. -* Can be down. +- Have limited free storage ([cachix](https://www.cachix.org/pricing) gives 5GB for open-source projects). +- Need good bandwidth for receiving and pushing paths over the Internet. +- Can be down. ## Garbage collection @@ -270,14 +272,14 @@ Produce a cache once, use it multiple times. Don't collect garbage. Advantages: -* Unnecessary paths are saved to a cache only during a new save. +- Unnecessary paths are saved to a cache only during a new save. Disadvantages: -* Unnecessary paths can accumulate between new saves. - * A job at the firs run produces a path `A` and saves a cache. - * The job at the second run restores the cache, produces a path `B`, and saves a cache. The cache has both `A` and `B`. - * etc. +- Unnecessary paths can accumulate between new saves. + - A job at the firs run produces a path `A` and saves a cache. + - The job at the second run restores the cache, produces a path `B`, and saves a cache. The cache has both `A` and `B`. + - etc. ### Garbage collection approach 2 @@ -285,44 +287,45 @@ Collect garbage before saving a cache. Advantages: -* Automatically keep cache at a minimal/limited size +- Automatically keep cache at a minimal/limited size Disadvantages: -* No standard way to gc only old paths. +- No standard way to gc only old paths. ### Save a path from garbage collection -* Use `nix profile install` to save installables from garbage collection. - * Get store paths of `inputs` via `nix flake archive` (see [comment](https://github.com/NixOS/nix/issues/4250#issuecomment-1146878407)). - * Get outputs via `nix flake show --json | jq '.packages."x86_64-linux"|keys[]'| xargs -I {}` on `x86_64-linux` (see this [issue](https://github.com/NixOS/nix/issues/7165)). -* Keep inputs (see this [issue](https://github.com/NixOS/nix/issues/4250) and this [issue](https://github.com/NixOS/nix/issues/6895)). -* Start [direnv](https://github.com/nix-community/nix-direnv) in background. +- Use `nix profile install` to save installables from garbage collection. + - Get store paths of `inputs` via `nix flake archive` (see [comment](https://github.com/NixOS/nix/issues/4250#issuecomment-1146878407)). + - Get outputs via `nix flake show --json | jq '.packages."x86_64-linux"|keys[]'| xargs -I {}` on `x86_64-linux` (see this [issue](https://github.com/NixOS/nix/issues/7165)). +- Keep inputs (see this [issue](https://github.com/NixOS/nix/issues/4250) and this [issue](https://github.com/NixOS/nix/issues/6895)). +- Start [direnv](https://github.com/nix-community/nix-direnv) in background. ### Garbage collection approaches -* Use [nix-heuristic-gc](https://github.com/risicle/nix-heuristic-gc) for cache eviction via `atime`. -* gc via gc roots [nix-cache-cut](https://github.com/astro/nix-cache-cut). -* gc based on time [cache-gc](https://github.com/lheckemann/cache-gc). +- Use [nix-heuristic-gc](https://github.com/risicle/nix-heuristic-gc) for cache eviction via `atime`. +- gc via gc roots [nix-cache-cut](https://github.com/astro/nix-cache-cut). +- gc based on time [cache-gc](https://github.com/lheckemann/cache-gc). ## Contribute -* Improve README. -* Report errors, suggest improvements in issues. -* Upgrade code. - * Read about [JavaScript actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions?learn=create_actions&learnProduct=actions#javascript-actions) - * See main files: - * [restoreImpl.ts](./src/restoreImpl.ts) - * [saveImpl.ts](./src/saveImpl.ts) -* Upgrade docs. - * Edit [action.nix](./action.nix). - * Update `action.yml`-s and `README.md`-s: +- Improve README. +- Report errors, suggest improvements in issues. +- Upgrade code. + - Read about [JavaScript actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions?learn=create_actions&learnProduct=actions#javascript-actions) + - See main files: + - [restoreImpl.ts](./src/restoreImpl.ts) + - [saveImpl.ts](./src/saveImpl.ts) +- Upgrade docs. + + - Edit [action.nix](./action.nix). + - Update `action.yml`-s and `README.md`-s: ```console nix run .#write ``` -* Update [actions-toolkit](./actions-toolkit). It was added via `git subtree`. See [tutorial](https://www.atlassian.com/git/tutorials/git-subtree). +- Update [actions-toolkit](./actions-toolkit). It was added via `git subtree`. See [tutorial](https://www.atlassian.com/git/tutorials/git-subtree). # Cache action @@ -336,21 +339,21 @@ See ["Caching dependencies to speed up workflows"](https://docs.github.com/en/ac ### v3 -* Added support for caching in GHES 3.5+. -* Fixed download issue for files > 2GB during restore. -* Updated the minimum runner version support from node 12 -> node 16. -* Fixed avoiding empty cache save when no files are available for caching. -* Fixed tar creation error while trying to create tar with path as `~/` home folder on `ubuntu-latest`. -* Fixed zstd failing on amazon linux 2.0 runners. -* Fixed cache not working with github workspace directory or current directory. -* Fixed the download stuck problem by introducing a timeout of 1 hour for cache downloads. -* Fix zstd not working for windows on gnu tar in issues. -* Allowing users to provide a custom timeout as input for aborting download of a cache segment using an environment variable `SEGMENT_DOWNLOAD_TIMEOUT_MINS`. Default is 10 minutes. -* New actions are available for granular control over caches - [restore](restore/action.yml) and [save](save/action.yml). -* Added option to fail job on cache miss. See [Exit workflow on cache miss](./restore/README.md#exit-workflow-on-cache-miss) for more info. -* Fix zstd not being used after zstd version upgrade to 1.5.4 on hosted runners -* Added option to lookup cache without downloading it. -* Reduced segment size to 128MB and segment timeout to 10 minutes to fail fast in case the cache download is stuck. +- Added support for caching in GHES 3.5+. +- Fixed download issue for files > 2GB during restore. +- Updated the minimum runner version support from node 12 -> node 16. +- Fixed avoiding empty cache save when no files are available for caching. +- Fixed tar creation error while trying to create tar with path as `~/` home folder on `ubuntu-latest`. +- Fixed zstd failing on amazon linux 2.0 runners. +- Fixed cache not working with github workspace directory or current directory. +- Fixed the download stuck problem by introducing a timeout of 1 hour for cache downloads. +- Fix zstd not working for windows on gnu tar in issues. +- Allowing users to provide a custom timeout as input for aborting download of a cache segment using an environment variable `SEGMENT_DOWNLOAD_TIMEOUT_MINS`. Default is 10 minutes. +- New actions are available for granular control over caches - [restore](restore/action.yml) and [save](save/action.yml). +- Added option to fail job on cache miss. See [Exit workflow on cache miss](./restore/README.md#exit-workflow-on-cache-miss) for more info. +- Fix zstd not being used after zstd version upgrade to 1.5.4 on hosted runners +- Added option to lookup cache without downloading it. +- Reduced segment size to 128MB and segment timeout to 10 minutes to fail fast in case the cache download is stuck. See the [v2 README.md](https://github.com/actions/cache/blob/v2/README.md) for older updates. @@ -366,7 +369,7 @@ If you are using a `self-hosted` Windows runner, `GNU tar` and `zstd` are requir #### Environment Variables -* `SEGMENT_DOWNLOAD_TIMEOUT_MINS` - Segment download timeout (in minutes, default `10`) 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) +- `SEGMENT_DOWNLOAD_TIMEOUT_MINS` - Segment download timeout (in minutes, default `10`) 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) ### Cache scopes @@ -388,21 +391,21 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v3 - - name: Cache Primes - id: cache-primes - uses: actions/cache@v3 - with: - primary-key: ${{ runner.os }}-primes - paths: prime-numbers + - name: Cache Primes + id: cache-primes + uses: actions/cache@v3 + with: + primary-key: ${{ runner.os }}-primes + paths: prime-numbers - - name: Generate Prime Numbers - if: steps.cache-primes.outputs.cache-hit != 'true' - run: /generate-primes.sh -d prime-numbers + - name: Generate Prime Numbers + if: steps.cache-primes.outputs.cache-hit != 'true' + run: /generate-primes.sh -d prime-numbers - - name: Use Prime Numbers - run: /primes.sh -d prime-numbers + - name: Use Prime Numbers + run: /primes.sh -d prime-numbers ``` The `cache` action provides a `cache-hit` output which is set to `true` when the cache is restored using the primary `key` and `false` when the cache is restored using `restore-keys` or no cache is restored. @@ -419,27 +422,27 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - - name: Restore cached Primes - id: cache-primes-restore - uses: nix-community/cache-nix-action/restore@v5 - with: - primary-key: ${{ runner.os }}-primes - paths: | - path/to/dependencies - some/other/dependencies - - # other steps - - - name: Save Primes - id: cache-primes-save - uses: nix-community/cache-nix-action/save@v5 - with: - primary-key: ${{ steps.cache-primes-restore.outputs.cache-primary-key }} - paths: | - path/to/dependencies - some/other/dependencies + - uses: actions/checkout@v3 + + - name: Restore cached Primes + id: cache-primes-restore + uses: nix-community/cache-nix-action/restore@v5 + with: + primary-key: ${{ runner.os }}-primes + paths: | + path/to/dependencies + some/other/dependencies + + # other steps + + - name: Save Primes + id: cache-primes-save + uses: nix-community/cache-nix-action/save@v5 + with: + primary-key: ${{ steps.cache-primes-restore.outputs.cache-primary-key }} + paths: | + path/to/dependencies + some/other/dependencies ``` > **Note** @@ -455,31 +458,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 @@ -488,27 +491,27 @@ A cache key can include any of the contexts, functions, literals, and operators For example, using the [`hashFiles`](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles) function allows you to create a new cache when dependencies change. ```yaml - - uses: nix-community/cache-nix-action@v5 - with: - primary-key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }} - paths: | - path/to/dependencies - some/other/dependencies +- uses: nix-community/cache-nix-action@v5 + with: + primary-key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }} + paths: | + path/to/dependencies + some/other/dependencies ``` Additionally, you can use arbitrary command output in a cache key, such as a date or software version: ```yaml - # http://man7.org/linux/man-pages/man1/date.1.html - - name: Get Date - id: get-date - run: echo "date=$(/bin/date -u "+%Y%m%d")" >> $GITHUB_OUTPUT - shell: bash +# http://man7.org/linux/man-pages/man1/date.1.html +- name: Get Date + id: get-date + run: echo "date=$(/bin/date -u "+%Y%m%d")" >> $GITHUB_OUTPUT + shell: bash - - uses: nix-community/cache-nix-action@v5 - with: - primary-key: ${{ runner.os }}-${{ steps.get-date.outputs.date }}-${{ hashFiles('**/lockfiles') }} - paths: path/to/dependencies +- uses: nix-community/cache-nix-action@v5 + with: + primary-key: ${{ runner.os }}-${{ steps.get-date.outputs.date }}-${{ hashFiles('**/lockfiles') }} + paths: path/to/dependencies ``` See [Using contexts to create cache keys](https://help.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows#using-contexts-to-create-cache-keys) @@ -613,18 +616,18 @@ Default value of this timeout is 10 minutes and can be customized by specifying A cache today is immutable and cannot be updated. But some use cases require the cache to be saved even though there was a hit during the `Restore phase`. To do so, always purge old versions of that cache: - ```yaml - - name: update cache on every commit - uses: actions/cache@v3 - with: - primary-key: primes-${{ runner.os }} - paths: prime-numbers - purge: true - purge-primary-key: always - ``` +```yaml +- name: update cache on every commit + uses: actions/cache@v3 + with: + primary-key: primes-${{ runner.os }} + paths: prime-numbers + purge: true + purge-primary-key: always +``` + +Please note that this will create a new cache on every run and hence will consume the cache [quota](./README.md#cache-limits). - Please note that this will create a new cache on every run and hence will consume the cache [quota](./README.md#cache-limits). - ## Use cache across feature branches Reusing cache across feature branches is not allowed today to provide cache [isolation](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache). However if both feature branches are from the default branch, a good way to achieve this is to ensure that the default branch has a cache. This cache will then be consumable by both feature branches. @@ -634,6 +637,7 @@ Reusing cache across feature branches is not allowed today to provide cache [iso Caches have [branch scope restriction](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache) in place. This means that if caches for a specific branch are using a lot of storage quota, it may result into more frequently used caches from `default` branch getting thrashed. For example, if there are many pull requests happening on a repo and are creating caches, these cannot be used in default branch scope but will still occupy a lot of space till they get cleaned up by [eviction policy](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy). But sometime we want to clean them up on a faster cadence so as to ensure default branch is not thrashing. In order to achieve this, [gh-actions-cache cli](https://github.com/actions/gh-actions-cache/) can be used to delete caches for specific branches. This workflow uses `gh-actions-cache` to delete all the caches created by a branch. +
Example @@ -660,7 +664,7 @@ jobs: - name: Cleanup run: | gh extension install actions/gh-actions-cache - + REPO=${{ github.repository }} BRANCH=refs/pull/${{ github.event.pull_request.number }}/merge diff --git a/restore/README.md b/restore/README.md index 1bb64c7c..1e27cc79 100644 --- a/restore/README.md +++ b/restore/README.md @@ -41,7 +41,7 @@ The restore action restores a cache. It works similarly to the `cache` action ex ### Environment Variables -* `SEGMENT_DOWNLOAD_TIMEOUT_MINS` - Segment download timeout (in minutes, default `10`) 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) +- `SEGMENT_DOWNLOAD_TIMEOUT_MINS` - Segment download timeout (in minutes, default `10`) 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) ## Use cases diff --git a/save/README.md b/save/README.md index 910173cd..10d85f0c 100644 --- a/save/README.md +++ b/save/README.md @@ -68,7 +68,7 @@ Let's say we have a restore step that computes a key at runtime. uses: actions/cache/restore@v3 id: restore-cache with: - key: cache-${{ hashFiles('**/lockfiles') }} + key: cache-${{ hashFiles('**/lockfiles') }} ``` #### Case 1 - Where a user would want to reuse the key as it is @@ -76,7 +76,7 @@ with: ```yaml uses: actions/cache/save@v3 with: - key: ${{ steps.restore-cache.outputs.cache-primary-key }} + key: ${{ steps.restore-cache.outputs.cache-primary-key }} ``` #### Case 2 - Where the user would want to re-evaluate the key @@ -84,7 +84,7 @@ with: ```yaml uses: actions/cache/save@v3 with: - key: npm-cache-${{hashfiles(package-lock.json)}} + key: npm-cache-${{hashfiles(package-lock.json)}} ``` ### Always save cache