Fix issues with custom cache eviction (#135)

* Keep latest and default branch cache entries

* Record skipped cache IDs

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 99
+    labels:
+      - "dependencies"
+      - "github-actions"

.github/workflows/CI.yml

@@ -0,0 +1,280 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'action.yml'
+      - 'handle_caches.jl'
+      - '.github/**'
+  pull_request:
+    paths:
+      - 'action.yml'
+      - 'handle_caches.jl'
+      - '.github/**'
+
+# needed to allow julia-actions/cache to delete old caches that it has created
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  generate-prefix:
+    runs-on: ubuntu-latest
+    outputs:
+      cache-prefix: ${{ steps.name.outputs.cache-prefix }}
+    steps:
+    - name: Generate random cache-prefix
+      id: name
+      run: |
+        cache_prefix=$(head -n 100 </dev/urandom | shasum -a 256 | cut -d ' ' -f 1)
+        echo "cache-prefix=$cache_prefix" >>"$GITHUB_OUTPUT"
+
+  test-save:
+    needs: generate-prefix
+    runs-on: ${{ matrix.os }}
+    outputs:
+      cache-name: ${{ steps.cache-name.outputs.cache-name }}
+    strategy:
+      matrix:
+        nested:
+          - name: matrix
+            invalid-chars: ","  # Use invalid characters in job matrix to ensure we escape them
+        version:
+          - "1.0"
+          - "1"
+          - "nightly"
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macOS-latest
+        exclude:
+          # Test Julia "1.0" on Linux only
+          - version: "1.0"
+            os: windows-latest
+          - version: "1.0"
+            os: macOS-latest
+      fail-fast: false
+    env:
+      JULIA_DEPOT_PATH: /tmp/julia-depot
+    steps:
+    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+    - name: Set cache-name
+      id: cache-name
+      shell: bash
+      run: |
+        echo "cache-name=${{ needs.generate-prefix.outputs.cache-prefix }}-${{ github.job }}" >>"$GITHUB_OUTPUT"
+    - uses: julia-actions/setup-julia@v2
+      with:
+        version: ${{ matrix.version }}
+    - name: Save cache
+      id: cache
+      uses: ./
+      with:
+        cache-name: ${{ steps.cache-name.outputs.cache-name }}
+        delete-old-caches: required
+    - name: Check no artifacts dir
+      shell: julia --color=yes {0}
+      run: |
+        dir = joinpath(first(DEPOT_PATH), "artifacts")
+        @assert !isdir(dir)
+    - name: Install a small binary
+      shell: julia --color=yes {0}
+      run: |
+        using Pkg
+        if VERSION >= v"1.3"
+            Pkg.add(PackageSpec(name="pandoc_jll", version="3"))
+        else
+            Pkg.add(PackageSpec(name="Scratch", version="1"))
+            using Scratch
+            get_scratch!("test")
+        end
+
+  test-restore:
+    needs: test-save
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        nested:
+          - name: matrix
+            invalid-chars: ","  # Use invalid characters in job matrix to ensure we escape them
+        version:
+          - "1.0"
+          - "1"
+          - "nightly"
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macOS-latest
+        exclude:
+          # Test Julia "1.0" on Linux only
+          - version: "1.0"
+            os: windows-latest
+          - version: "1.0"
+            os: macOS-latest
+      fail-fast: false
+    env:
+      JULIA_DEPOT_PATH: /tmp/julia-depot
+    steps:
+    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+    - uses: julia-actions/setup-julia@v2
+      with:
+        version: ${{ matrix.version }}
+    - name: Restore cache
+      id: cache
+      uses: ./
+      with:
+        cache-name: ${{ needs.test-save.outputs.cache-name }}
+        # Cannot require a successful cache delete on forked PRs as the permissions for actions is limited to read
+        delete-old-caches: ${{ github.event.pull_request.head.repo.fork && 'false' || 'required' }}
+    - name: Test cache-hit output
+      shell: julia --color=yes {0}
+      run: |
+        @show ENV["cache-hit"]
+        @assert ENV["cache-hit"] == "true"
+      env:
+        cache-hit: ${{ steps.cache.outputs.cache-hit }}
+    - name: Check existance or emptiness of affected dirs
+      shell: julia --color=yes {0}
+      run: |
+        # These dirs should exist as they've been cached
+        artifacts_dir = joinpath(first(DEPOT_PATH), "artifacts")
+        if VERSION >= v"1.3"
+            @assert !isempty(readdir(artifacts_dir))
+        else
+            @assert !isdir(artifacts_dir)
+        end
+        packages_dir = joinpath(first(DEPOT_PATH), "packages")
+        @assert !isempty(readdir(packages_dir))
+        compiled_dir = joinpath(first(DEPOT_PATH), "compiled")
+        @assert !isempty(readdir(compiled_dir))
+        scratchspaces_dir = joinpath(first(DEPOT_PATH), "scratchspaces")
+        @assert !isempty(readdir(scratchspaces_dir))
+        logs_dir = joinpath(first(DEPOT_PATH), "logs")
+        @assert !isempty(readdir(logs_dir))
+
+  # Do tests with no matrix also given the matrix is auto-included in cache key
+  test-save-nomatrix:
+    needs: generate-prefix
+    runs-on: ubuntu-latest
+    outputs:
+      cache-name: ${{ steps.cache-name.outputs.cache-name }}
+    steps:
+    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+    - name: Set cache-name
+      id: cache-name
+      run: |
+        echo "cache-name=${{ needs.generate-prefix.outputs.cache-prefix }}-${{ github.job }}" >>"$GITHUB_OUTPUT"
+    - name: Save cache
+      id: cache
+      uses: ./
+      with:
+        cache-name: ${{ steps.cache-name.outputs.cache-name }}
+        delete-old-caches: required
+    - name: Check no artifacts dir
+      shell: julia --color=yes {0}
+      run: |
+        dir = joinpath(first(DEPOT_PATH), "artifacts")
+        @assert !isdir(dir)
+    - name: Install a small binary
+      shell: julia --color=yes {0}
+      run: |
+        using Pkg
+        if VERSION >= v"1.3"
+            Pkg.add(PackageSpec(name="pandoc_jll", version="3"))
+        else
+            Pkg.add(PackageSpec(name="Scratch", version="1"))
+            using Scratch
+            get_scratch!("test")
+        end
+
+  test-restore-nomatrix:
+    needs: test-save-nomatrix
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+    - name: Restore cache
+      id: cache
+      uses: ./
+      with:
+        cache-name: ${{ needs.test-save-nomatrix.outputs.cache-name }}
+        # Cannot require a successful cache delete on forked PRs as the permissions for actions is limited to read
+        delete-old-caches: ${{ github.event.pull_request.head.repo.fork && 'false' || 'required' }}
+    - name: Test cache-hit output
+      shell: julia --color=yes {0}
+      run: |
+        @show ENV["cache-hit"]
+        @assert ENV["cache-hit"] == "true"
+      env:
+        cache-hit: ${{ steps.cache.outputs.cache-hit }}
+    - name: Check existance or emptiness of affected dirs
+      shell: julia --color=yes {0}
+      run: |
+        # These dirs should exist as they've been cached
+        artifacts_dir = joinpath(first(DEPOT_PATH), "artifacts")
+        if VERSION >= v"1.3"
+            @assert !isempty(readdir(artifacts_dir))
+        else
+            @assert !isdir(artifacts_dir)
+        end
+        packages_dir = joinpath(first(DEPOT_PATH), "packages")
+        @assert !isempty(readdir(packages_dir))
+        compiled_dir = joinpath(first(DEPOT_PATH), "compiled")
+        @assert !isempty(readdir(compiled_dir))
+        scratchspaces_dir = joinpath(first(DEPOT_PATH), "scratchspaces")
+        @assert !isempty(readdir(scratchspaces_dir))
+        logs_dir = joinpath(first(DEPOT_PATH), "logs")
+        @assert !isempty(readdir(logs_dir))
+
+  test-save-cloned-registry:
+    needs: generate-prefix
+    runs-on: ubuntu-latest
+    outputs:
+      cache-name: ${{ steps.cache-name.outputs.cache-name }}
+    steps:
+    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+    - name: Set cache-name
+      id: cache-name
+      run: |
+        echo "cache-name=${{ needs.generate-prefix.outputs.cache-prefix }}-${{ github.job }}" >>"$GITHUB_OUTPUT"
+    - name: Save cache
+      uses: ./
+      with:
+        cache-name: ${{ steps.cache-name.outputs.cache-name }}
+        # Cannot require a successful cache delete on forked PRs as the permissions for actions is limited to read
+        delete-old-caches: ${{ github.event.pull_request.head.repo.fork && 'false' || 'required' }}
+    - name: Add General registry clone
+      shell: julia --color=yes {0}
+      run: |
+        using Pkg
+        Pkg.Registry.add("General")
+      env:
+        JULIA_PKG_SERVER: ""
+    # Set the registry worktree to an older state to simulate the cache storing an old version of the registry.
+    - name: Use outdated General worktree
+      run: git -C ~/.julia/registries/General reset --hard HEAD~20
+
+  test-restore-cloned-registry:
+    needs: test-save-cloned-registry
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+    - name: Add General registry clone
+      shell: julia --color=yes {0}
+      run: |
+        using Pkg
+        Pkg.Registry.add("General")
+      env:
+        JULIA_PKG_SERVER: ""
+    - name: Restore cache
+      uses: ./
+      with:
+        cache-name: ${{ needs.test-save-cloned-registry.outputs.cache-name }}
+        # Cannot require a successful cache delete on forked PRs as the permissions for actions is limited to read
+        delete-old-caches: ${{ github.event.pull_request.head.repo.fork && 'false' || 'required' }}
+    - name: Test registry is not corrupt
+      shell: julia --color=yes {0}
+      run: |
+        using Pkg
+        Pkg.Registry.update()

README.md

@@ -1,63 +1,130 @@
-# cache-artifacts
-A shortcut action to cache Julia artifacts.
+# julia-actions/cache Action
 
-Using this action is equivalent to including the following step in your workflows:
-
-```yaml
-- uses: actions/cache@v1
-  env:
-    cache-name: cache-artifacts
-  with:
-    path: ~/.julia/artifacts
-    key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
-    restore-keys: |
-      ${{ runner.os }}-test-${{ env.cache-name }}-
-      ${{ runner.os }}-test-
-      ${{ runner.os }}-
-```
+A shortcut action to cache Julia depot contents to reduce GitHub Actions running time.
 
 ## Usage
 
-### Inputs
+An example workflow that uses this action might look like this:
 
 ```yaml
-- uses: julia-actions/cache-artifacts@v1
-  with:
-    # The cache name is used as part of the cache key.
-    # It is equivalent to the cache-name environment variable in the snippet above.
-    #
-    # Default: cache-artifacts
-    cache-name: ''
+name: CI
+
+on: [push, pull_request]
+
+# needed to allow julia-actions/cache to delete old caches that it has created
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: julia-actions/setup-julia@v2
+    - uses: julia-actions/cache@v2
+    - uses: julia-actions/julia-buildpkg@v1
+    - uses: julia-actions/julia-runtest@v1
 ```
 
+By default all depot directories called out below are cached.
+
+### Requirements
+
+- `jq`: This action uses [`jq`](https://github.com/jqlang/jq) to parse JSON. For GitHub-hosted runners, `jq` is installed by default. On self-hosted runners and custom containers, if `jq` is not already available, this action will automatically use [`dcarbone/install-jq-action`](https://github.com/dcarbone/install-jq-action) to install `jq` (Note: `dcarbone/install-jq-action` requires that `curl` is installed; this may not always be the case in custom containers and self-hosted runners).
+- `bash`: This action requires `bash`. For GitHub-hosted runners `bash` is installed by default. Self-hosted runners will need to ensure that `bash` is installed and available on the `PATH`.
+
+### Optional Inputs
+
+- `cache-name` - The cache key prefix. Defaults to `julia-cache;workflow=${{ github.workflow }};job=${{ github.job }}`. The key body automatically includes the OS and, unless disabled with `include-matrix`, the matrix vars. Include any other parameters/details in this prefix to ensure one unique cache key per concurrent job type.
+- `include-matrix` - Whether to include the matrix values when constructing the cache key. Defaults to `true`.
+- `depot` - Path to a Julia [depot](https://pkgdocs.julialang.org/v1/glossary/) directory where cached data will be saved to and restored from. Defaults to the first depot in [`JULIA_DEPOT_PATH`](https://docs.julialang.org/en/v1/manual/environment-variables/#JULIA_DEPOT_PATH) if specified. Otherwise, defaults to `~/.julia`.
+- `cache-artifacts` - Whether to cache the depot's `artifacts` directory. Defaults to `true`.
+- `cache-packages` - Whether to cache the depot's `packages` directory. Defaults to `true`.
+- `cache-registries` - Whether to cache the depot's `registries` directory. Defaults to `true`.
+- `cache-compiled` - Whether to cache the depot's `compiled` directory. Defaults to `true`.
+- `cache-scratchspaces` - Whether to cache the depot's `scratchspaces` directory. Defaults to `true`.
+- `cache-logs` - Whether to cache the depot's `logs` directory. Defaults to `true`. Helps auto-`Pkg.gc()` keep the cache small.
+- `delete-old-caches` - Whether to delete old caches for the given key. Defaults to `true`.
+- `token` - A [GitHub PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). Defaults to `github.token`. Requires `repo` scope to enable the deletion of old caches.
+
 ### Outputs
 
-```yaml
-outputs:
-  # A boolean value to indicate an exact match was found for the primary key.
-  # Forwarded from actions/cache, check its documentation for more info.
-  cache-hit: ''
-```
+- `cache-hit` - A boolean value to indicate an exact match was found for the primary key. Returns \"\" when the key is new. Forwarded from actions/cache.
+
+## How It Works
+
+This action is a wrapper around <https://github.com/actions/cache>.
+In summary, this action stores the files in the aforementioned paths in one compressed file when running for the first time.
+This cached file is then restored upon the second run, and afterwards resaved under a new key, and the previous cache deleted.
+The benefit of caching is that downloading one big file is quicker than downloading many different files from many different locations
+and precompiling them.
+
+By default, this action removes caches that were previously made by jobs on the same branch with the same restore key.
+GitHub automatically removes old caches after a certain period or when the repository cache allocation is full.
+It is, however, more efficient to explicitly remove old caches to improve caching for less frequently run jobs.
+
+### Cache keys
+
+The cache key that the cache will be saved as is based on:
+- The `cache-name` input
+- All variables in the `matrix` (unless disabled via `include-matrix: 'false'`)
+- The `runner.os` (may be in the matrix too, but included for safety)
+- The run id
+- The run attempt number
+
+> [!NOTE]
+> If there is job concurrency that is not fully defined by a matrix you should ensure that `cache-name` is 
+> unique for each concurrent job, otherwise caching may not be effective.
+
+### Cache Retention
+
+This action automatically deletes old caches that match the first 4 fields of the above key:
+- The `cache-name` input
+- All variables in the `matrix` (unless disabled via `include-matrix: 'false'`)
+- The `runner.os` (may be in the matrix too, but included for safety)
+
+Which means your caches files will not grow needlessly. GitHub also deletes cache files after
+[7 days of not being accessed](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy), and there is a limit of 10 GB for the total size of cache files associated to each repository.
+
+> [!NOTE]
+> To allow deletion of caches you will likely need to [grant the following permissions](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs)
+> to the `GITHUB_TOKEN` by adding this to your GitHub actions workflow:
+> ```yaml
+> permissions:
+>   actions: write
+>   contents: read
+> ```
+> (Note this won't work for fork PRs but should once merged)
+> Or provide a token with `repo` scope via the `token` input option.
+> See https://cli.github.com/manual/gh_cache_delete
+
+To disable deletion set input `delete-old-caches: 'false'`.
+
+### Cache Garbage Collection
+
+Caches are restored and re-saved after every run, retaining the state of the depot throughout runs.
+Their size will be regulated like a local depot automatically by the automatic `Pkg.gc()` functionality that
+clears out old content, which is made possible because the `/log` contents are cached.
 
 ## Third Party Notice
 
 This action is built around [`actions/cache`](https://github.com/actions/cache/) and includes parts of that action. `actions/cache` has been released under the following licence:
 
-
 > The MIT License (MIT)
-> 
+>
 > Copyright (c) 2018 GitHub, Inc. and contributors
-> 
+>
 > Permission is hereby granted, free of charge, to any person obtaining a copy
 > of this software and associated documentation files (the "Software"), to deal
 > in the Software without restriction, including without limitation the rights
 > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 > copies of the Software, and to permit persons to whom the Software is
 > furnished to do so, subject to the following conditions:
-> 
+>
 > The above copyright notice and this permission notice shall be included in
 > all copies or substantial portions of the Software.
-> 
+>
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

action.yml

@@ -1,6 +1,6 @@
-name: 'Cache Julia Artifacts'
-description: 'Cache Julia artifacts using actions/cache'
-author: 'Sascha Mann'
+name: 'Cache Julia artifacts, packages and registry'
+description: 'Cache Julia using actions/cache'
+author: 'Sascha Mann, Rik Huijzer, and contributors'
 
 branding:
   icon: 'archive'
@@ -8,27 +8,172 @@ branding:
 
 inputs:
   cache-name:
-    description: 'Name used as part of the cache keys'
-    default: 'cache-artifacts'
+    description: >-
+      The cache key prefix. The key body automatically includes the OS and, unless disabled, the matrix vars.
+      Include any other parameters/details in this prefix to ensure one unique cache key per concurrent job type.
+    default: julia-cache;workflow=${{ github.workflow }};job=${{ github.job }}
+  include-matrix:
+    description: Whether to include the matrix values when constructing the cache key.
+    default: 'true'
+  depot:
+    description: Path to a Julia depot directory where cached data will be saved to and restored from.
+    default: ''
+  cache-artifacts:
+    description: Whether to cache the depot's `artifacts` directory.
+    default: 'true'
+  cache-packages:
+    description: Whether to cache the depot's `packages` directory.
+    default: 'true'
+  cache-registries:
+    description: Whether to cache the depot's `registries` directory.
+    default: 'true'
+  cache-compiled:
+    description: Whether to cache the depot's `compiled` directory.
+    default: 'true'
+  cache-scratchspaces:
+    description: Whether to cache the depot's `scratchspaces` directory.
+    default: 'true'
+  cache-logs:
+    description: Whether to cache the depot's `logs` directory. This helps automatic `Pkg.gc()` keep the cache size down.
+    default: 'true'
+  delete-old-caches:
+    description: Whether to delete old caches for the given key.
+    default: 'true'
+  token:
+    description: A GitHub PAT. Requires `repo` scope to enable the deletion of old caches.
+    default: ${{ github.token }}
 
 outputs:
   cache-hit:
-    description: 'A boolean value to indicate an exact match was found for the primary key. Forwarded from actions/cache'
+    description: A boolean value to indicate an exact match was found for the primary key. Returns "" when the key is new. Forwarded from actions/cache.
+    value: ${{ steps.hit.outputs.cache-hit }}
 
 runs:
   using: 'composite'
   steps:
-    - uses: actions/cache@937d24475381cd9c75ae6db12cb4e79714b926ed
+    - name: Install jq
+      uses: dcarbone/install-jq-action@8867ddb4788346d7c22b72ea2e2ffe4d514c7bcb
+      with:
+        force: false  # Skip install when an existing `jq` is present
+
+    - id: paths
+      run: |
+        if [ -n "${{ inputs.depot }}" ]; then
+            depot="${{ inputs.depot }}"
+        elif [ -n "$JULIA_DEPOT_PATH" ]; then
+            # Use the first depot path
+            depot=$(echo $JULIA_DEPOT_PATH | cut -d$PATH_DELIMITER -f1)
+        else
+            depot="~/.julia"
+        fi
+        echo "depot=$depot" | tee -a "$GITHUB_OUTPUT"
+
+        cache_paths=()
+        artifacts_path="${depot}/artifacts"
+        [ "${{ inputs.cache-artifacts }}" = "true" ] && cache_paths+=("$artifacts_path")
+        packages_path="${depot}/packages"
+        [ "${{ inputs.cache-packages }}" = "true" ] && cache_paths+=("$packages_path")
+        registries_path="${depot}/registries"
+        if [ "${{ inputs.cache-registries }}" = "true" ]; then
+            if [ ! -d "${registries_path/#\~/$HOME}" ]; then
+                cache_paths+=("$registries_path")
+            else
+                echo "::warning::Julia depot registries already exist. Skipping restoring of cached registries to avoid potential merge conflicts when updating. Please ensure that \`julia-actions/cache\` precedes any workflow steps which add registries."
+            fi
+        fi
+        compiled_path="${depot}/compiled"
+        [ "${{ inputs.cache-compiled }}" = "true" ] && cache_paths+=("$compiled_path")
+        scratchspaces_path="${depot}/scratchspaces"
+        [ "${{ inputs.cache-scratchspaces }}" = "true" ] && cache_paths+=("$scratchspaces_path")
+        logs_path="${depot}/logs"
+        [ "${{ inputs.cache-logs }}" = "true" ] && cache_paths+=("$logs_path")
+        {
+            echo "cache-paths<<EOF"
+            printf "%s\n" "${cache_paths[@]}"
+            echo "EOF"
+        } | tee -a "$GITHUB_OUTPUT"
+      shell: bash
+      env:
+        PATH_DELIMITER: ${{ runner.OS == 'Windows' && ';' || ':' }}
+
+    - name: Generate Keys
+      id: keys
+      run: |
+        # `matrix_key` joins all of matrix keys/values (including nested objects) to ensure that concurrent runs each use a unique cache key.
+        # When `matrix` isn't set for the job then `MATRIX_JSON=null`.
+        if [ "${{ inputs.include-matrix }}" == "true" ] && [ "$MATRIX_JSON" != "null" ]; then
+          matrix_key=$(echo "$MATRIX_JSON" | jq 'paths(type != "object") as $p | ($p | join("-")) + "=" + (getpath($p) | tostring)' | jq -rs 'join(";") | . + ";"')
+        fi
+        restore_key="${{ inputs.cache-name }};os=${{ runner.os }};${matrix_key}"
+        # URL encode any restricted characters:
+        # https://github.com/actions/toolkit/blob/5430c5d84832076372990c7c27f900878ff66dc9/packages/cache/src/cache.ts#L38-L43
+        restore_key=$(sed 's/,/%2C/g' <<<"${restore_key}")
+        key="${restore_key}run_id=${{ github.run_id }};run_attempt=${{ github.run_attempt }}"
+        echo "restore-key=${restore_key}" >> $GITHUB_OUTPUT
+        echo "key=${key}" >> $GITHUB_OUTPUT
+      shell: bash
+      env:
+        MATRIX_JSON: ${{ toJSON(matrix) }}
+
+    - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
       id: cache
       with:
-        path: ~/.julia/artifacts
-        key: ${{ runner.os }}-test-${{ inputs.cache-name }}-${{ hashFiles('**/Project.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-test-${{ inputs.cache-name }}-
-          ${{ runner.os }}-test-
-          ${{ runner.os }}-
+        path: |
+          ${{ steps.paths.outputs.cache-paths }}
+        key: ${{ steps.keys.outputs.key }}
+        restore-keys: ${{ steps.keys.outputs.restore-key }}
+        enableCrossOsArchive: false
 
-    - run: echo "::set-output name=cache-hit::$CACHE_HIT"
+    # if it wasn't restored make the depot anyway as a signal that this action ran
+    # for other julia actions to check, like https://github.com/julia-actions/julia-buildpkg/pull/41
+    - name: make depot if not restored, then list depot directory sizes
+      run: |
+        mkdir -p ${{ steps.paths.outputs.depot }}
+        du -shc ${{ steps.paths.outputs.depot }}/* || true
+      shell: bash
+
+    # GitHub actions cache entries are immutable and cannot be updated. In order to have both the Julia
+    # depot cache be up-to-date and avoid storing redundant cache entries we'll manually cleanup old
+    # cache entries before the new cache is saved. However, we need to be careful with our manual
+    # cleanup as otherwise we can cause cache misses for jobs which would have normally had a cache hit.
+    # Some scenarios to keep in mind include:
+    #
+    # - Job failures result in the post-action for `actions/cache` being skipped. If we delete all cache
+    #   entries for the branch we may have no cache entry available for the next run.
+    # - We should avoid deleting old cache entries for the default branch since these entries serve as
+    #   the fallback if no earlier cache entry exists on a branch. We can rely on GitHub's default cache
+    #   eviction policy here which will remove the oldest cache entry first.
+    #
+    # References:
+    # - https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache
+    # - https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy
+
+    # Not windows
+    - uses: pyTooling/Actions/with-post-step@e9d0dc3dba9fda45f195946858708f60c0240caf # v1.0.5
+      if: ${{ inputs.delete-old-caches != 'false' &&
+              github.ref != format('refs/heads/{0}', github.event.repository.default_branch) &&
+              runner.OS != 'Windows' }}
+      with:
+        # seems like there has to be a `main` step in this action. Could list caches for info if we wanted
+        # main:  julia ${{ github.action_path }}/handle_caches.jl "${{ github.repository }}" "list"
+        main: echo ""
+        post: julia $GITHUB_ACTION_PATH/handle_caches.jl rm "${{ github.repository }}" "${{ steps.keys.outputs.restore-key }}" "${{ github.ref }}" "${{ inputs.delete-old-caches != 'required' }}"
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+
+    # Windows (because this action uses command prompt on windows)
+    - uses: pyTooling/Actions/with-post-step@e9d0dc3dba9fda45f195946858708f60c0240caf # v1.0.5
+      if: ${{ inputs.delete-old-caches != 'false' &&
+              github.ref != format('refs/heads/{0}', github.event.repository.default_branch) &&
+              runner.OS == 'Windows' }}
+      with:
+        main: echo ""
+        post: cd %GITHUB_ACTION_PATH% && julia handle_caches.jl rm "${{ github.repository }}" "${{ steps.keys.outputs.restore-key }}" "${{ github.ref }}" "${{ inputs.delete-old-caches != 'required' }}"
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+
+    - id: hit
+      run: echo "cache-hit=$CACHE_HIT" >> $GITHUB_OUTPUT
       env:
         CACHE_HIT: ${{ steps.cache.outputs.cache-hit }}
       shell: bash

devdocs/making_a_new_release.md

@@ -0,0 +1,56 @@
+# Making a new release
+
+In this guide, as an example, `v2.2.0` refers to the version number of the new release that you want to make.
+
+## Part 1: Use the Git CLI to create and push the Git tags
+
+Step 1: Create a new lightweight tag of the form `vMAJOR.MINOR.PATCH`.
+
+```bash
+git clone git@github.com:julia-actions/cache.git
+cd cache
+git fetch --all --tags
+
+git checkout main
+
+git --no-pager log -1
+# Take note of the commit hash here.
+
+# Now, create a new lightweight tag of the form `vMAJOR.MINOR.PATCH`.
+#
+# Replace `commit_hash` with the commit hash that you obtained from the
+# `git log -1` step.
+#
+# Replace `v2.2.0` with the actual version number that you want to use.
+git tag v2.2.0 commit_hash
+```
+
+Step 2: Once you've created the new release, you need to update the `v2` tag to point to the new release. For example, suppose that the previous release was `v2.1.0`, and suppose that you just created the new release `v2.2.0`. You need to update the `v2` tag so that it points to `v2.2.0`. Here are the commands:
+
+```bash
+# Create/update the new v2 tag locally, where the new v2 tag will point to the
+# release that you created in the previous step.
+#
+# Make sure to change `v2.2.0` to the actual value for the tag that you just
+# created in the previous step.
+#
+# The `-f` flag forcibly overwrites the old
+# `v2` tag (if it exists).
+git tag -f v2 v2.2.0
+```
+
+Step 3: Now you need to push the tags:
+
+```bash
+# Regular-push the new `v2.2.0` tag:
+git push origin tag v2.2.0
+
+# Force-push the new v2 tag:
+git push origin tag v2 --force
+```
+
+## Part 2: Create the GitHub Release
+
+Go to the [Releases](https://github.com/julia-actions/cache/releases) section of this repo and create a new release (using the GitHub web interface).
+
+For the "choose a tag" drop-down field, select the `v2.2.0` tag that you created and pushed in Part 1 of this guide.

handle_caches.jl

@@ -0,0 +1,85 @@
+using Pkg, Dates
+function handle_caches()
+    subcommand = ARGS[1]
+
+    if subcommand == "list"
+        repo = ARGS[2]
+        println("Listing existing caches")
+        run(`gh cache list --limit 100 --repo $repo`)
+    elseif subcommand == "rm"
+        repo, restore_key, ref = ARGS[2:4]
+        allow_failure = ARGS[5] == "true"
+
+        page = 1
+        per_page = 100
+        skipped = String[]
+        deleted = String[]
+        failed = String[]
+        while 1 <= page <= 5 # limit to avoid accidental rate limiting
+            # https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28#list-github-actions-caches-for-a-repository
+            # Note: The `key` field matches on the full key or a prefix.
+            cmd = ```
+                gh api -X GET /repos/$repo/actions/caches
+                    --field per_page=$per_page
+                    --field page=$page
+                    --field ref=$ref
+                    --field key=$restore_key
+                    --field sort=last_accessed_at
+                    --field direction=desc
+                    --jq '.actions_caches[].id'
+                ```
+            ids = split(read(cmd, String); keepempty=false)
+
+            # Avoid deleting the latest used cache entry. This is particularly important for
+            # job failures where a new cache entry will not be saved after this.
+            page == 1 && !isempty(ids) && push!(skipped, popfirst!(ids))
+
+            for id in ids
+                try
+                    run(`gh cache delete $id --repo $repo`)
+                    push!(deleted, id)
+                catch e
+                    @error e
+                    push!(failed, id)
+                end
+            end
+
+            page = length(ids) == per_page ? page + 1 : -1
+        end
+        if isempty(skipped) && isempty(deleted) && isempty(failed)
+            println("No existing caches found on ref `$ref` matching restore key `$restore_key`")
+        else
+            if !isempty(failed)
+                println("Failed to delete $(length(failed)) existing caches on ref `$ref` matching restore key `$restore_key`")
+                println.(failed)
+                @info """
+                    To delete caches you need to grant the following to the default `GITHUB_TOKEN` by adding
+                    this to your workflow:
+                    ```
+                    permissions:
+                      actions: write
+                      contents: read
+                    ```
+                    (Note this won't work for fork PRs but should once merged)
+                    Or provide a token with `repo` scope via the `token` input option.
+                    See https://cli.github.com/manual/gh_cache_delete
+                    """
+                allow_failure || exit(1)
+            end
+            if !isempty(deleted)
+                println("Deleted $(length(deleted)) caches on ref `$ref` matching restore key `$restore_key`")
+                println.(deleted)
+            end
+        end
+    else
+        throw(ArgumentError("Unexpected subcommand: $subcommand"))
+    end
+end
+
+try
+    # do a gc with the standard 7-day delay
+    Pkg.gc()
+    handle_caches()
+catch e
+    @error "An error occurred while managing existing caches" e
+end