allow replacing stale cache

README.md

@@ -107,6 +107,29 @@ Default `true`.
   ```
 </details>
 
+### `cache-replace`
+
+Before saving each cache, delete any prior entries with the same prefix on the current ref. Frees quota by removing superseded caches immediately instead of waiting for GitHub's LRU eviction. Requires `actions: write` permission on the workflow token. Only takes effect when `cache-save: true`.
+
+Default `false`.
+
+<details>
+  <summary>Examples</summary>
+
+  #### Clean up superseded caches on the default branch
+
+  ```yaml
+  permissions:
+    actions: write
+  steps:
+    - uses: bazel-contrib/setup-bazel@0.19.0
+      with:
+        disk-cache: ${{ github.workflow }}
+        cache-save: ${{ github.ref == 'refs/heads/main' }}
+        cache-replace: ${{ github.ref == 'refs/heads/main' }}
+  ```
+</details>
+
 ### `disk-cache`
 
 Enable [`disk_cache`][2] and store it on GitHub based on contents of `BUILD` files.

action.yml

@@ -17,6 +17,10 @@ inputs:
     description: Whether to save caches. Set to false for pull requests to allow restores but prevent saves.
     required: false
     default: "true"
+  cache-replace:
+    description: Delete prior caches with the same prefix before saving. Requires actions write permission.
+    required: false
+    default: "false"
   cache-version:
     description: Version of all caches
     required: false

config.js

@@ -6,6 +6,7 @@ import * as github from '@actions/github'
 
 const bazeliskVersion = core.getInput('bazelisk-version')
 const cacheSave = core.getBooleanInput('cache-save')
+const cacheReplace = core.getBooleanInput('cache-replace')
 const cacheVersion = core.getInput('cache-version')
 const moduleRoot = core.getInput('module-root')
 
@@ -141,6 +142,7 @@ core.exportVariable('BAZELISK_GITHUB_TOKEN', token)
 export default {
   baseCacheKey,
   cacheSave,
+  cacheReplace,
   cacheRestoreTimeoutMs,
   bazeliskCache: {
     enabled: core.getBooleanInput('bazelisk-cache'),