Merge 42e6e83ca6 into 9fa7e61ec7

* fix: update force deletion docs due a recent deprecation

* fix: applied josh's suggestions

---------

Co-authored-by: Josh Gross <joshmgross@github.com>

caching-strategies.md

@@ -102,7 +102,7 @@ The [GitHub Context](https://docs.github.com/en/actions/learn-github-actions/con
 
 While setting paths for caching dependencies it is important to give correct path depending on the hosted runner you are using or whether the action is running in a container job. Assigning different `path` for save and restore will result in cache miss.
 
-Below are GiHub hosted runner specific paths one should take care of when writing a workflow which saves/restores caches across OS.
+Below are GitHub hosted runner specific paths one should take care of when writing a workflow which saves/restores caches across OS.
 
 #### Ubuntu Paths
 

examples.md

@@ -41,6 +41,9 @@
 - [Swift - Swift Package Manager](#swift---swift-package-manager)
 - [Swift - Mint](#swift---mint)
 - [* - Bazel](#---bazel)
+- [Common use cases](#common-use-cases)
+  - [Restore-only caches](#restore-only-caches)
+  - [Automatically detect cached paths](#automatically-detect-cached-paths)
 
 ## Bun
 
@@ -712,3 +715,32 @@ steps:
       ${{ runner.os }}-bazel-
 - run: bazelisk test //...
 ```
+##  Common use cases
+
+### Restore-only caches
+If there are several builds on the same repo it might make sense to create a cache in one build and use it in the
+others. The action [actions/cache/restore](https://github.com/actions/cache/blob/main/restore/README.md#only-restore-cache)
+should be used in this case.
+
+### Automatically detect cached paths
+[Defining outputs for jobs](https://docs.github.com/en/actions/using-jobs/defining-outputs-for-jobs) can be used to
+automatically detect paths to cache and use them to configure `actions/cache` action.
+
+```yaml
+- name: Get Go cached paths
+  id: find-cached-paths
+  run: |
+    echo "cache=$(go env GOCACHE)" >> $GITHUB_ENV
+    echo "modcache=$(go env GOMODCACHE)" >> $GITHUB_ENV
+
+- name: Set up cache
+  uses: actions/cache@v3
+  needs: find-cached-paths
+  with:
+    path: |
+      ${{ env.cache }}
+      ${{ env.modcache }}
+    key: setup-go-${{ runner.os }}-go-${{ hashFiles('go.sum go.mod') }}
+    restore-keys: |
+      setup-go-${{ runner.os }}-go-
+```

save/README.md

@@ -79,8 +79,10 @@ To avoid saving a cache that already exists, the `cache-hit` output from a resto
 The `cache-primary-key` output from the restore step should also be used to ensure
 the cache key does not change during the build if it's calculated based on file contents.
 
+Here's an example where we imagine we're calculating a lot of prime numbers and want to cache them:
+
 ```yaml
-name: Always Caching Primes
+name: Always Caching Prime Numbers
 
 on: push
 
@@ -91,23 +93,23 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - name: Restore cached Primes
-      id: cache-primes-restore
+    - name: Restore cached Prime Numbers
+      id: cache-prime-numbers-restore
       uses: actions/cache/restore@v4
       with:
-        key: ${{ runner.os }}-primes
+        key: ${{ runner.os }}-prime-numbers
         path: |
           path/to/dependencies
           some/other/dependencies
 
     # Intermediate workflow steps
 
-    - name: Always Save Primes
-      id: cache-primes-save
-      if: always() && steps.cache-primes-restore.outputs.cache-hit != 'true'
+    - name: Always Save Prime Numbers
+      id: cache-prime-numbers-save
+      if: always() && steps.cache-prime-numbers-restore.outputs.cache-hit != 'true'
       uses: actions/cache/save@v4
       with:
-        key: ${{ steps.cache-primes-restore.outputs.cache-primary-key }}
+        key: ${{ steps.cache-prime-numbers-restore.outputs.cache-primary-key }}
         path: |
           path/to/dependencies
           some/other/dependencies

tips-and-workarounds.md

@@ -37,9 +37,8 @@ From `v3.2.3` cache is cross-os compatible when `enableCrossOsArchive` input is
 
 ## Force deletion of caches overriding default cache eviction policy
 
-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.
+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.
 
-This workflow uses `gh-actions-cache` to delete all the caches created by a branch.
 <details>
   <summary>Example</summary>
 
@@ -60,29 +59,23 @@ jobs:
       actions: write
       contents: read
     steps:
-      - name: Check out code
-        uses: actions/checkout@v4
-
       - name: Cleanup
         run: |
-          gh extension install actions/gh-actions-cache
-          
-          REPO=${{ github.repository }}
-          BRANCH=refs/pull/${{ github.event.pull_request.number }}/merge
-
           echo "Fetching list of cache key"
-          cacheKeysForPR=$(gh actions-cache list -R $REPO -B $BRANCH | cut -f 1 )
+          cacheKeysForPR=$(gh cache list --ref $BRANCH --limit 100 --json id --jq '.[].id')
 
-          ## Setting this to not fail the workflow while deleting cache keys. 
+          ## Setting this to not fail the workflow while deleting cache keys.
           set +e
           echo "Deleting caches..."
           for cacheKey in $cacheKeysForPR
           do
-              gh actions-cache delete $cacheKey -R $REPO -B $BRANCH --confirm
+              gh cache delete $cacheKey
           done
           echo "Done"
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          BRANCH: refs/pull/${{ github.event.pull_request.number }}/merge
 ```
 
 </details>