From 020a412c274f2031f05eba9c64b181a1961b89b8 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Mon, 5 Dec 2022 12:34:45 +0000 Subject: [PATCH 01/15] Readme draft for new actions --- README.md | 4 ++ restore/README.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++ save/README.md | 7 +++ 3 files changed, 128 insertions(+) create mode 100644 restore/README.md create mode 100644 save/README.md diff --git a/README.md b/README.md index 8117b58..41a7709 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ This action allows caching dependencies and build outputs to improve workflow ex See ["Caching dependencies to speed up workflows"](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows). +[Restore action](./restore/README.md) + +[Save action](./save/README.md) + ## What's New ### v3 * Added support for caching from GHES 3.5. diff --git a/restore/README.md b/restore/README.md new file mode 100644 index 0000000..d752902 --- /dev/null +++ b/restore/README.md @@ -0,0 +1,117 @@ +# Restore action + +The restore action restores cache just like the main `cache` action, except it doesn't save the cache. So for cases where users only want to restore cache and not save anything in return, this action is pretty helpful. Moreover, this action accepts the same set of inputs as the `cache` action. + +## 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` - String used while saving cache for restoring the cache +* `restore-keys` - An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key. +> **Note** +It is very important to use the same `key` and `path` that were used by either `actions/cache` or `actions/cache/save` while saving the cache. + +### 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/workarounds.md#cache-segment-restore-timeout) + +## Outputs + +* `cache-hit` - A boolean value to indicate an exact match was found for the key. +* `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`. + +## Use cases + +As this is a newly introduced action to give users more control in their workflows, below are some use cases where one can use this action. + +### Only restore cache + +In case you are using another workflow 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. + +``` +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 +``` + +Once the cache is restored, this action won't run any post step to do post-processing like `actions/cache` and the rest of the workflow will run as usual. + +### Save intermediate private build artifacts + +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. + + +#### Step 1 - Build the parent module and save it +``` +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 +``` +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 +``` + +### 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. + +``` +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 +``` \ No newline at end of file diff --git a/save/README.md b/save/README.md new file mode 100644 index 0000000..31dcb1d --- /dev/null +++ b/save/README.md @@ -0,0 +1,7 @@ +# Save action + +## Inputs + +## Outputs + +## Use cases \ No newline at end of file From 00b72c7e02e2252e9f46176b9e7c358f8ce6e90a Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Mon, 12 Dec 2022 11:36:12 +0000 Subject: [PATCH 02/15] Updated outputs of restore action --- restore/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/restore/README.md b/restore/README.md index d752902..3ee9e09 100644 --- a/restore/README.md +++ b/restore/README.md @@ -16,7 +16,8 @@ It is very important to use the same `key` and `path` that were used by either ` ## Outputs * `cache-hit` - A boolean value to indicate an exact match was found for the key. -* `key` - +* `cache-primary-key` - Cache primary key passed in the input to use in subsequent steps of the workflow +* `cache-restore-key` - Cache key restored > **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`. From 9d445b25653e34259615c308ddec492af0caffc0 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Wed, 14 Dec 2022 04:35:02 +0000 Subject: [PATCH 03/15] Added save readme --- restore/README.md | 10 +++++- save/README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 92 insertions(+), 2 deletions(-) diff --git a/restore/README.md b/restore/README.md index 3ee9e09..bb96508 100644 --- a/restore/README.md +++ b/restore/README.md @@ -115,4 +115,12 @@ steps: - name: Build run: /build.sh -``` \ No newline at end of file +``` + +## Tips + +Since this action comes with its own set of pros and cons, we are listing some of the ways by which you can tackle the limitations. + +### Reusing primary key and restored key in the save action + +One of the limitation you might experience is passing the same input in both `actions/cache/restore` and `actions/cache/save` action. To avoid this, you can make use of the `outputs` from the restore action to reuse the same primary key and also the key of the cache that was restored. This way changing any key in the restore action will automatically reflect in the subsequent actions where the same input is being used. \ No newline at end of file diff --git a/save/README.md b/save/README.md index 31dcb1d..206a867 100644 --- a/save/README.md +++ b/save/README.md @@ -1,7 +1,89 @@ # Save action +The save action saves cache just like the post step of the `cache` action, except it can be run individually now without having to call the restore step. The save action needs to be called with required inputs, the `key` with which the cache needs to be stored and the `path` that needs to be cached. + ## Inputs +* `key` - 'An explicit key for saving the cache' +* `path` - 'A list of files, directories, and wildcard patterns to cache' +* `upload-chunk-size` - 'The chunk size used to split up large files during upload, in bytes' + ## Outputs -## Use cases \ No newline at end of file +This action has no outputs. + +## Use cases + +As this is a newly introduced action to give users more control in their workflows, below are some use cases where one can use this action. + +### Only save cache + +In case you are using separate jobs for generating common artifacts and sharing them across different jobs, this action will help you with your save only needs. + +``` +steps: + - uses: actions/checkout@v3 + + - name: Install Dependencies + if: steps.cache.outputs.cache-hit != 'true' + run: /install.sh + + - name: Build common artifacts + run: /build.sh + + - uses: actions/cache/save@v3 + id: cache + with: + path: path/to/dependencies + key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }} +``` + +### Re-evaluate cache key while saving + +Some technologies like dot-net generate the lockfiles during the build time, due to which the already evaluated `${{ hashFiles('**/lockfiles') }}` hash doesn't match the actual hash. Using save action with the same key will not re-evaluate the key as hash would be calculated after the build step hence allowing the hash to be latest. + +We will also be making the restore inputted `key` available as output of `restore` action to be reused in the input of the `save` action. This way the user has to control to reuse the same key or get it re-evaluated based on their choice. + +Let's say we have a restore step that computes key at runtime. + +``` +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 +``` +uses: actions/cache/save@v3 +with: + key: steps.restore-cache.output.key +``` + +Case 2: Where the user would want to re-evaluate the key +``` +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. + +Inspired from: https://github.com/actions/cache/issues/92, https://github.com/actions/cache/issues/272, https://github.com/actions/cache/issues/849 + +``` +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') }} +``` From 81aaae062be983385232921da2f9a61fa84aa7d1 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Wed, 14 Dec 2022 04:40:58 +0000 Subject: [PATCH 04/15] Updates to save readme --- save/README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/save/README.md b/save/README.md index 206a867..95f0dc0 100644 --- a/save/README.md +++ b/save/README.md @@ -40,9 +40,9 @@ steps: ### Re-evaluate cache key while saving -Some technologies like dot-net generate the lockfiles during the build time, due to which the already evaluated `${{ hashFiles('**/lockfiles') }}` hash doesn't match the actual hash. Using save action with the same key will not re-evaluate the key as hash would be calculated after the build step hence allowing the hash to be latest. +Some technologies like dot-net generate the lockfiles during the build time, due to which the already evaluated `${{ hashFiles('**/lockfiles') }}` hash doesn't match the actual hash. Using save action with the same key will not re-evaluate the key as the hash was generated during restores. However passing the expression to re-evaluate the hash would generate a new key in the save action now as save would be called after the build step. -We will also be making the restore inputted `key` available as output of `restore` action to be reused in the input of the `save` action. This way the user has to control to reuse the same key or get it re-evaluated based on their choice. +In other words, you can reuse the output of `restore` action in the input of the `save` action to input the same key. Otherwise, you can pass the hash logic for the key (ex. `${{ hashFiles('**/lockfiles') }}`) and let the save action re-evaluate the key just before executing. Let's say we have a restore step that computes key at runtime. @@ -71,8 +71,6 @@ with: 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. -Inspired from: https://github.com/actions/cache/issues/92, https://github.com/actions/cache/issues/272, https://github.com/actions/cache/issues/849 - ``` steps: - uses: actions/checkout@v3 From 65057ce6fe7d87c4e31ca09a159ba2f4d847f837 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Wed, 14 Dec 2022 10:23:32 +0000 Subject: [PATCH 05/15] Added cache hit info in readme --- restore/README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/restore/README.md b/restore/README.md index bb96508..f47c750 100644 --- a/restore/README.md +++ b/restore/README.md @@ -16,8 +16,8 @@ It is very important to use the same `key` and `path` that were used by either ` ## Outputs * `cache-hit` - A boolean value to indicate an exact match was found for the key. -* `cache-primary-key` - Cache primary key passed in the input to use in subsequent steps of the workflow -* `cache-restore-key` - Cache key restored +* `cache-primary-key` - Cache primary key passed in the input to use in subsequent steps of the workflow. +* `cache-matched-key` - Key of the cache that was restored, it could either be the primary key on cache-hit or a partial/complete match of one of the restore keys. > **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`. @@ -123,4 +123,8 @@ Since this action comes with its own set of pros and cons, we are listing some o ### Reusing primary key and restored key in the save action -One of the limitation you might experience is passing the same input in both `actions/cache/restore` and `actions/cache/save` action. To avoid this, you can make use of the `outputs` from the restore action to reuse the same primary key and also the key of the cache that was restored. This way changing any key in the restore action will automatically reflect in the subsequent actions where the same input is being used. \ No newline at end of file +One of the limitation you might experience is passing the same input in both `actions/cache/restore` and `actions/cache/save` action. To avoid this, you can make use of the `outputs` from the restore action to reuse the same primary key and also the key of the cache that was restored. This way changing any key in the restore action will automatically reflect in the subsequent actions where the same input is being used. + +### Using restore action outputs to make save action behave just like the cache action + +The outputs `cache-primary-key` and `cache-matched-key` can be used to check if the restored cache is same as the given primary key. Alternatively, the `cache-hit` output can also be used to check if the restored was a complete match or a partially restored cache. \ No newline at end of file From 44df5ab77e4463a3aa5bb348a5b4fb56adb1858a Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Thu, 15 Dec 2022 00:06:10 +0530 Subject: [PATCH 06/15] Update restore/README.md Co-authored-by: Bishal Prasad --- restore/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/restore/README.md b/restore/README.md index f47c750..40ec566 100644 --- a/restore/README.md +++ b/restore/README.md @@ -1,6 +1,6 @@ # Restore action -The restore action restores cache just like the main `cache` action, except it doesn't save the cache. So for cases where users only want to restore cache and not save anything in return, this action is pretty helpful. Moreover, this action accepts the same set of inputs as the `cache` action. +The restore action, as the name suggest, restores a cache. It acts similar to the`cache` action except that it doesn't have a post step to save the cache. This action can provide you a granular control to only restore a cache without having to necessarily save it. It accepts the same set of inputs as the `cache` action. ## Inputs From d5c949690c66f8de4d3c0b4396fe0c63ad600369 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Thu, 15 Dec 2022 00:06:41 +0530 Subject: [PATCH 07/15] Update restore/README.md Co-authored-by: Bishal Prasad --- restore/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/restore/README.md b/restore/README.md index 40ec566..703f394 100644 --- a/restore/README.md +++ b/restore/README.md @@ -119,7 +119,6 @@ steps: ## Tips -Since this action comes with its own set of pros and cons, we are listing some of the ways by which you can tackle the limitations. ### Reusing primary key and restored key in the save action From c11ac6c2fe127c5f0f15511ccc762526275e6198 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Thu, 15 Dec 2022 00:06:56 +0530 Subject: [PATCH 08/15] Update restore/README.md Co-authored-by: Bishal Prasad --- restore/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/restore/README.md b/restore/README.md index 703f394..c9f0233 100644 --- a/restore/README.md +++ b/restore/README.md @@ -122,7 +122,7 @@ steps: ### Reusing primary key and restored key in the save action -One of the limitation you might experience is passing the same input in both `actions/cache/restore` and `actions/cache/save` action. To avoid this, you can make use of the `outputs` from the restore action to reuse the same primary key and also the key of the cache that was restored. This way changing any key in the restore action will automatically reflect in the subsequent actions where the same input is being used. +Usually you may want to use same `key` in both actions/cache/restore` and `actions/cache/save` action. To achieve this, use `outputs` from the restore action to reuse the same primary key (or the key of the cache that was restored). ### Using restore action outputs to make save action behave just like the cache action From fb5b333162587a2f3b8f62045da93c5d5b69a531 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Thu, 15 Dec 2022 00:07:06 +0530 Subject: [PATCH 09/15] Update save/README.md Co-authored-by: Bishal Prasad --- save/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/save/README.md b/save/README.md index 95f0dc0..8514a6e 100644 --- a/save/README.md +++ b/save/README.md @@ -1,6 +1,6 @@ # Save action -The save action saves cache just like the post step of the `cache` action, except it can be run individually now without having to call the restore step. The save action needs to be called with required inputs, the `key` with which the cache needs to be stored and the `path` that needs to be cached. +The save action, as the name suggest, saves a cache. It acts similar to the `cache` action except that it doesn't necessarily first do a restore. This action can provide you a granular control to only save a cache without having to necessarily restore it, or to do a restore anywhere in the workflow job and not only in post phase. ## Inputs From 686bf424a8587f432efb76ff3bd9cb0c0c9e74a2 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Thu, 15 Dec 2022 00:07:16 +0530 Subject: [PATCH 10/15] Update save/README.md Co-authored-by: Bishal Prasad --- save/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/save/README.md b/save/README.md index 8514a6e..3830b45 100644 --- a/save/README.md +++ b/save/README.md @@ -14,7 +14,6 @@ This action has no outputs. ## Use cases -As this is a newly introduced action to give users more control in their workflows, below are some use cases where one can use this action. ### Only save cache From 766d8255cd7c9476ad53132641f65a9bba8044b7 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Wed, 14 Dec 2022 18:46:21 +0000 Subject: [PATCH 11/15] Removed verbose statements --- save/README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/save/README.md b/save/README.md index 3830b45..390af0b 100644 --- a/save/README.md +++ b/save/README.md @@ -39,11 +39,9 @@ steps: ### Re-evaluate cache key while saving -Some technologies like dot-net generate the lockfiles during the build time, due to which the already evaluated `${{ hashFiles('**/lockfiles') }}` hash doesn't match the actual hash. Using save action with the same key will not re-evaluate the key as the hash was generated during restores. However passing the expression to re-evaluate the hash would generate a new key in the save action now as save would be called after the build step. +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. -In other words, you can reuse the output of `restore` action in the input of the `save` action to input the same key. Otherwise, you can pass the hash logic for the key (ex. `${{ hashFiles('**/lockfiles') }}`) and let the save action re-evaluate the key just before executing. - -Let's say we have a restore step that computes key at runtime. +Let's say we have a restore step that computes key at runtime ``` uses: actions/cache/restore@v3 From 56e956426f67ebabb48c5a23dc4141489272747a Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Wed, 14 Dec 2022 18:49:43 +0000 Subject: [PATCH 12/15] Repositioned new actions introduction --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 41a7709..33829b6 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,17 @@ This action allows caching dependencies and build outputs to improve workflow execution time. +In addition to `actions/cache` action, other two actions are also available + +[Restore action](./restore/README.md) +[Save action](./save/README.md) + [![Tests](https://github.com/actions/cache/actions/workflows/workflow.yml/badge.svg)](https://github.com/actions/cache/actions/workflows/workflow.yml) ## Documentation See ["Caching dependencies to speed up workflows"](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows). -[Restore action](./restore/README.md) - -[Save action](./save/README.md) ## What's New ### v3 From 7a139a9cec945bab027ded7ff0a376c444a37053 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Thu, 15 Dec 2022 08:59:40 +0000 Subject: [PATCH 13/15] Addressed review comments --- README.md | 1 + restore/README.md | 18 ++++++++++-------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 33829b6..048af36 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ This action allows caching dependencies and build outputs to improve workflow ex In addition to `actions/cache` action, other two actions are also available [Restore action](./restore/README.md) + [Save action](./save/README.md) [![Tests](https://github.com/actions/cache/actions/workflows/workflow.yml/badge.svg)](https://github.com/actions/cache/actions/workflows/workflow.yml) diff --git a/restore/README.md b/restore/README.md index c9f0233..7adb324 100644 --- a/restore/README.md +++ b/restore/README.md @@ -7,11 +7,6 @@ The restore action, as the name suggest, restores a cache. It acts similar to th * `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` - String used while saving cache for restoring the cache * `restore-keys` - An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key. -> **Note** -It is very important to use the same `key` and `path` that were used by either `actions/cache` or `actions/cache/save` while saving the cache. - -### 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/workarounds.md#cache-segment-restore-timeout) ## Outputs @@ -22,6 +17,9 @@ It is very important to use the same `key` and `path` that were used by either ` > **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`. +### 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/workarounds.md#cache-segment-restore-timeout) + ## Use cases As this is a newly introduced action to give users more control in their workflows, below are some use cases where one can use this action. @@ -120,10 +118,14 @@ steps: ## Tips -### Reusing primary key and restored key in the save action +#### Reusing primary key and restored key in the save action Usually you may want to use same `key` in both actions/cache/restore` and `actions/cache/save` action. To achieve this, use `outputs` from the restore action to reuse the same primary key (or the key of the cache that was restored). -### Using restore action outputs to make save action behave just like the cache action +#### Using restore action outputs to make save action behave just like the cache action -The outputs `cache-primary-key` and `cache-matched-key` can be used to check if the restored cache is same as the given primary key. Alternatively, the `cache-hit` output can also be used to check if the restored was a complete match or a partially restored cache. \ No newline at end of file +The outputs `cache-primary-key` and `cache-matched-key` can be used to check if the restored cache is same as the given primary key. Alternatively, the `cache-hit` output can also be used to check if the restored was a complete match or a partially restored cache. + +#### Ensuring proper restores and save happen across the actions + +It is very important to use the same `key` and `path` that were used by either `actions/cache` or `actions/cache/save` while saving the cache. Learn more about cache key [naming](https://github.com/actions/cache#creating-a-cache-key) and [versioning](https://github.com/actions/cache#cache-version) here. From da311f75a6037f2cb80a8cd867da1dba0f93072c Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Thu, 15 Dec 2022 09:01:49 +0000 Subject: [PATCH 14/15] nit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 048af36..6210ddc 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This action allows caching dependencies and build outputs to improve workflow execution time. -In addition to `actions/cache` action, other two actions are also available +In addition to this `cache` action, other two actions are also available [Restore action](./restore/README.md) From 05c9b49ea4c9743a2748017519724e29c6776756 Mon Sep 17 00:00:00 2001 From: Sankalp Kotewar <98868223+kotewar@users.noreply.github.com> Date: Thu, 15 Dec 2022 09:05:17 +0000 Subject: [PATCH 15/15] nit: added language to code blocks --- restore/README.md | 8 ++++---- save/README.md | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/restore/README.md b/restore/README.md index 7adb324..0c60cc2 100644 --- a/restore/README.md +++ b/restore/README.md @@ -28,7 +28,7 @@ As this is a newly introduced action to give users more control in their workflo In case you are using another workflow 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. -``` +```yaml steps: - uses: actions/checkout@v3 @@ -57,7 +57,7 @@ In case of multi-module projects, where the built artifact of one project needs #### Step 1 - Build the parent module and save it -``` +```yaml steps: - uses: actions/checkout@v3 @@ -72,7 +72,7 @@ steps: ``` #### Step 2 - Restore the built artifact from cache using the same key and path -``` +```yaml steps: - uses: actions/checkout@v3 @@ -97,7 +97,7 @@ steps: 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 diff --git a/save/README.md b/save/README.md index 390af0b..4d98fd1 100644 --- a/save/README.md +++ b/save/README.md @@ -19,7 +19,7 @@ This action has no outputs. In case you are using separate jobs for generating common artifacts and sharing them across different jobs, this action will help you with your save only needs. -``` +```yaml steps: - uses: actions/checkout@v3 @@ -43,7 +43,7 @@ With save action, the key can now be re-evaluated while executing the action. Th Let's say we have a restore step that computes key at runtime -``` +```yaml uses: actions/cache/restore@v3 id: restore-cache with: @@ -51,14 +51,14 @@ with: ``` 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.output.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)}} @@ -68,7 +68,7 @@ with: 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 .