Add COURSIER_CACHE_ACTION_CACHE_VERSION env var for manual cache invalidation (#808)

* Initial plan

* Add COURSIER_CACHE_VERSION env var for manual cache invalidation

Co-authored-by: alexarchambault <7063723+alexarchambault@users.noreply.github.com>

* Rename COURSIER_CACHE_VERSION to COURSIER_CACHE_ACTION_CACHE_VERSION

Co-authored-by: alexarchambault <7063723+alexarchambault@users.noreply.github.com>

* README: add step-level env var example alongside workflow-level example

Co-authored-by: alexarchambault <7063723+alexarchambault@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: alexarchambault <7063723+alexarchambault@users.noreply.github.com>
Co-authored-by: Alexandre Archambault <alexarchambault@users.noreply.github.com>

Author: Copilot

README.md

@@ -124,6 +124,37 @@ Default: `false`
 
 Set `true` to skip saving and restoring the Ammonite cache, regardless of whether the repository contains `.sc` scripts.
 
+## Cache invalidation
+
+To manually invalidate the cache without changing your build files, set the `COURSIER_CACHE_ACTION_CACHE_VERSION`
+environment variable in your workflow. Changing its value produces a different cache key across all
+cache types, so the old cache is ignored and a fresh one is created.
+
+The variable can be set at the workflow level so that it applies to every step:
+
+```yaml
+env:
+  COURSIER_CACHE_ACTION_CACHE_VERSION: 1   # increment this value to invalidate the cache
+
+steps:
+  - uses: actions/checkout@v5
+  - uses: coursier/cache-action@v7
+```
+
+Or it can be scoped to only the `coursier/cache-action` step:
+
+```yaml
+steps:
+  - uses: actions/checkout@v5
+  - uses: coursier/cache-action@v7
+    env:
+      COURSIER_CACHE_ACTION_CACHE_VERSION: 1   # increment this value to invalidate the cache
+```
+
+This is equivalent to passing the version as `extraHashedContent`, but more convenient because it
+can be set globally for the whole workflow (or even as a repository variable / secret) without
+touching the individual step configuration.
+
 ## Outputs
 
 * `cache-hit-coursier` - A boolean value to indicate a match was found for the coursier cache

src/restore.ts

@@ -323,6 +323,18 @@ async function run(): Promise<void> {
   const extraMillHashedContent = readExtraKeys('extraMillHashedContent')
   const extraAmmoniteHashedContent = readExtraKeys('extraAmmoniteHashedContent')
 
+  const cacheVersion = process.env['COURSIER_CACHE_ACTION_CACHE_VERSION'] ?? ''
+  if (cacheVersion.length > 0) {
+    core.info(
+      `Cache invalidation: COURSIER_CACHE_ACTION_CACHE_VERSION is set to '${cacheVersion}', appending to all cache keys.`
+    )
+  }
+
+  const effectiveExtraHashedContent =
+    cacheVersion.length > 0
+      ? `${extraHashedContent}\n${cacheVersion}`
+      : extraHashedContent
+
   const extraKey = readExtraKeys('extraKey')
   const extraCoursierKey = readExtraKeys('extraCoursierKey')
   const extraSbtKey = readExtraKeys('extraSbtKey')
@@ -379,7 +391,7 @@ async function run(): Promise<void> {
   const coursierHashedContent: Record<string, string> = {
     sbt: extraSbtHashedContent,
     mill: extraMillHashedContent,
-    other: extraHashedContent,
+    other: effectiveExtraHashedContent,
     coursier: extraCoursierHashedContent
   }
   if (!ignoreAmmonite) {
@@ -405,7 +417,7 @@ async function run(): Promise<void> {
       matrix,
       JSON.stringify({
         sbt: extraSbtHashedContent,
-        other: extraHashedContent
+        other: effectiveExtraHashedContent
       }),
       disableFallback
     )
@@ -420,7 +432,7 @@ async function run(): Promise<void> {
       matrix,
       JSON.stringify({
         mill: extraMillHashedContent,
-        other: extraHashedContent
+        other: effectiveExtraHashedContent
       }),
       disableFallback
     )
@@ -443,7 +455,7 @@ async function run(): Promise<void> {
       matrix,
       JSON.stringify({
         amm: extraAmmoniteHashedContent,
-        other: extraHashedContent
+        other: effectiveExtraHashedContent
       }),
       disableFallback
     )