tespkg · froggleston · Oct 9, 2025 · Oct 9, 2025
diff --git a/README.md b/README.md
@@ -116,6 +116,27 @@ To check if cache hits and size is not zero without downloading:
 `restore-keys` works similar to how github's `@actions/cache@v2` works: It search each item in `restore-keys`
 as prefix in object names and use the latest one
 
+To restore from the cache using a `restore-key` prefix if the `key` restore fails:
+
+```yaml
+      - uses: tespkg/actions-cache/restore@v1
+        with:
+          accessKey: "Q3AM3UQ867SPQQA43P2F" # required
+          secretKey: "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG" # required
+          bucket: actions-cache # required
+          # actions/cache compatible properties: https://github.com/actions/cache
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+            ${{ runner.os }}-
+          path: |
+            node_modules
+```
+
+If a match is found using one of the `restore-keys` options, then `cache-hit` will be FALSE but the 
+`cache-matched-key` output will be set to the key that matched. See the 
+[actions/cache](https://github.com/actions/cache/blob/main/restore/README.md#outputs) notes.
+
 ## Amazon S3 permissions
 
 When using this with Amazon S3, the following permissions are necessary:

diff --git a/action.yml b/action.yml
@@ -57,6 +57,8 @@ outputs:
     description: "A boolean value to indicate an exact match was found for the primary key"
   cache-size:
     description: "A integer value denoting the size of the cache object found (measured in bytes)"
+  cache-matched-key:
+    description: "The key of the cache object found, if any"
 runs:
   using: node20
   main: "dist/restore/index.js"

diff --git a/dist/restore/index.js b/dist/restore/index.js
@@ -109661,6 +109661,7 @@ function restoreCache() {
                 const cacheHit = matchingKey === key;
                 (0, utils_1.setCacheHitOutput)(cacheHit);
                 (0, utils_1.setCacheSizeOutput)(obj.size);
+                (0, utils_1.setCacheMatchedKeyOutput)(matchingKey);
                 if (lookupOnly) {
                     if (cacheHit && obj.size > 0) {
                         core.info(`Cache Hit. NOT Downloading cache from s3 because lookup-only is set. bucket: ${bucket}, object: ${obj.name}`);
@@ -109692,6 +109693,7 @@ function restoreCache() {
                         const fallbackMatchingKey = yield cache.restoreCache(paths, key, restoreKeys);
                         if (fallbackMatchingKey) {
                             (0, utils_1.setCacheHitOutput)(fallbackMatchingKey === key);
+                            (0, utils_1.setCacheMatchedKeyOutput)(fallbackMatchingKey);
                             core.info("Fallback cache restored successfully");
                         }
                         else {
@@ -109772,7 +109774,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.saveCache = exports.isExactKeyMatch = exports.saveMatchedKey = exports.listObjects = exports.findObject = exports.setCacheSizeOutput = exports.setCacheHitOutput = exports.formatSize = exports.getInputAsInt = exports.getInputAsArray = exports.getInputAsBoolean = exports.newMinio = exports.getInput = exports.isGhes = void 0;
+exports.saveCache = exports.isExactKeyMatch = exports.saveMatchedKey = exports.listObjects = exports.findObject = exports.setCacheMatchedKeyOutput = exports.setCacheSizeOutput = exports.setCacheHitOutput = exports.formatSize = exports.getInputAsInt = exports.getInputAsArray = exports.getInputAsBoolean = exports.newMinio = exports.getInput = exports.isGhes = void 0;
 const utils = __importStar(__nccwpck_require__(1518));
 const core = __importStar(__nccwpck_require__(2186));
 const minio = __importStar(__nccwpck_require__(8308));
@@ -109846,6 +109848,10 @@ function setCacheSizeOutput(cacheSize) {
     core.setOutput("cache-size", cacheSize.toString());
 }
 exports.setCacheSizeOutput = setCacheSizeOutput;
+function setCacheMatchedKeyOutput(cacheMatchedKey) {
+    core.setOutput("cache-matched-key", cacheMatchedKey);
+}
+exports.setCacheMatchedKeyOutput = setCacheMatchedKeyOutput;
 function findObject(mc, bucket, key, restoreKeys, compressionMethod) {
     return __awaiter(this, void 0, void 0, function* () {
         core.debug("Key: " + JSON.stringify(key));

diff --git a/dist/save/index.js b/dist/save/index.js
@@ -109687,7 +109687,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.saveCache = exports.isExactKeyMatch = exports.saveMatchedKey = exports.listObjects = exports.findObject = exports.setCacheSizeOutput = exports.setCacheHitOutput = exports.formatSize = exports.getInputAsInt = exports.getInputAsArray = exports.getInputAsBoolean = exports.newMinio = exports.getInput = exports.isGhes = void 0;
+exports.saveCache = exports.isExactKeyMatch = exports.saveMatchedKey = exports.listObjects = exports.findObject = exports.setCacheMatchedKeyOutput = exports.setCacheSizeOutput = exports.setCacheHitOutput = exports.formatSize = exports.getInputAsInt = exports.getInputAsArray = exports.getInputAsBoolean = exports.newMinio = exports.getInput = exports.isGhes = void 0;
 const utils = __importStar(__nccwpck_require__(1518));
 const core = __importStar(__nccwpck_require__(2186));
 const minio = __importStar(__nccwpck_require__(8308));
@@ -109761,6 +109761,10 @@ function setCacheSizeOutput(cacheSize) {
     core.setOutput("cache-size", cacheSize.toString());
 }
 exports.setCacheSizeOutput = setCacheSizeOutput;
+function setCacheMatchedKeyOutput(cacheMatchedKey) {
+    core.setOutput("cache-matched-key", cacheMatchedKey);
+}
+exports.setCacheMatchedKeyOutput = setCacheMatchedKeyOutput;
 function findObject(mc, bucket, key, restoreKeys, compressionMethod) {
     return __awaiter(this, void 0, void 0, function* () {
         core.debug("Key: " + JSON.stringify(key));

diff --git a/dist/saveOnly/index.js b/dist/saveOnly/index.js
@@ -109687,7 +109687,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.saveCache = exports.isExactKeyMatch = exports.saveMatchedKey = exports.listObjects = exports.findObject = exports.setCacheSizeOutput = exports.setCacheHitOutput = exports.formatSize = exports.getInputAsInt = exports.getInputAsArray = exports.getInputAsBoolean = exports.newMinio = exports.getInput = exports.isGhes = void 0;
+exports.saveCache = exports.isExactKeyMatch = exports.saveMatchedKey = exports.listObjects = exports.findObject = exports.setCacheMatchedKeyOutput = exports.setCacheSizeOutput = exports.setCacheHitOutput = exports.formatSize = exports.getInputAsInt = exports.getInputAsArray = exports.getInputAsBoolean = exports.newMinio = exports.getInput = exports.isGhes = void 0;
 const utils = __importStar(__nccwpck_require__(1518));
 const core = __importStar(__nccwpck_require__(2186));
 const minio = __importStar(__nccwpck_require__(8308));
@@ -109761,6 +109761,10 @@ function setCacheSizeOutput(cacheSize) {
     core.setOutput("cache-size", cacheSize.toString());
 }
 exports.setCacheSizeOutput = setCacheSizeOutput;
+function setCacheMatchedKeyOutput(cacheMatchedKey) {
+    core.setOutput("cache-matched-key", cacheMatchedKey);
+}
+exports.setCacheMatchedKeyOutput = setCacheMatchedKeyOutput;
 function findObject(mc, bucket, key, restoreKeys, compressionMethod) {
     return __awaiter(this, void 0, void 0, function* () {
         core.debug("Key: " + JSON.stringify(key));

diff --git a/restore/action.yml b/restore/action.yml
@@ -57,6 +57,8 @@ outputs:
     description: "A boolean value to indicate an exact match was found for the primary key"
   cache-size:
     description: "A integer value denoting the size of the cache object found (measured in bytes)"
+  cache-matched-key:
+    description: "The key of the cache object found, if any"
 runs:
   using: node20
   main: "../dist/restore/index.js"

diff --git a/src/restore.ts b/src/restore.ts
@@ -13,6 +13,7 @@ import {
   newMinio,
   setCacheHitOutput,
   setCacheSizeOutput,
+  setCacheMatchedKeyOutput,
   saveMatchedKey,
   getInput,
 } from "./utils";
@@ -66,6 +67,7 @@ async function restoreCache() {
       const cacheHit = matchingKey === key;
       setCacheHitOutput(cacheHit);
       setCacheSizeOutput(obj.size);
+      setCacheMatchedKeyOutput(matchingKey);
       if (lookupOnly) {
         if (cacheHit && obj.size > 0) {
           core.info(
@@ -106,6 +108,7 @@ async function restoreCache() {
           );
           if (fallbackMatchingKey) {
             setCacheHitOutput(fallbackMatchingKey === key);
+            setCacheMatchedKeyOutput(fallbackMatchingKey);
             core.info("Fallback cache restored successfully");
           } else {
             core.info("Fallback cache restore failed");

diff --git a/src/utils.ts b/src/utils.ts
@@ -97,6 +97,10 @@ export function setCacheSizeOutput(cacheSize: number): void {
   core.setOutput("cache-size", cacheSize.toString())
 }
 
+export function setCacheMatchedKeyOutput(cacheMatchedKey: string): void {
+  core.setOutput("cache-matched-key", cacheMatchedKey)
+}
+
 type FindObjectResult = {
   item: minio.BucketItem;
   matchingKey: string;