Merge 783accdc1c into 638ed79f9d

Add note on runner versions

README.md

@@ -19,16 +19,19 @@ See ["Caching dependencies to speed up workflows"](https://docs.github.com/en/ac
 
 The cache backend service has been rewritten from the ground up for improved performance and reliability. [actions/cache](https://github.com/actions/cache) now integrates with the new cache service (v2) APIs.
 
-The new service will gradually roll out as of **February 1st, 2025**. The legacy service will also be sunset on the same date. Changes in these release are **fully backward compatible**.
+The new service will gradually roll out as of **February 1st, 2025**. The legacy service will also be sunset on the same date. Changes in these releases are **fully backward compatible**.
 
 **We are deprecating some versions of this action**. We recommend upgrading to version `v4` or `v3` as soon as possible before **February 1st, 2025.** (Upgrade instructions below).
 
-If you are using pinned SHAs, please use the SHAs of versions `v4.2.0` or `v3.4.0`
+If you are using pinned SHAs, please use the SHAs of versions `v4.2.0` or `v3.4.0`.
 
 If you do not upgrade, all workflow runs using any of the deprecated [actions/cache](https://github.com/actions/cache) will fail.
 
 Upgrading to the recommended versions will not break your workflows.
 
+> **Additionally, if you are managing your own GitHub runners, you must update your runner version to `2.231.0` or newer to ensure compatibility with the new cache service.**  
+> Failure to update both the action version and your runner version may result in workflow failures after the migration date.
+
 Read more about the change & access the migration guide: [reference to the announcement](https://github.com/actions/cache/discussions/1510).
 
 ### v4
@@ -86,6 +89,8 @@ If you are using a `self-hosted` Windows runner, `GNU tar` and `zstd` are requir
 * `cache-hit` - A string value to indicate an exact match was found for the key.
   * If there's a cache hit, this will be 'true' or 'false' to indicate if there's an exact match for `key`.
   * If there's a cache miss, this will be an empty string.
+* `cache-primary-key` - Cache primary key passed in the input to use in subsequent steps of the workflow.
+* `cache-matched-key` - Key of the cache that was restored, it could either be the primary key on cache-hit or a partial/complete match of one of the restore keys.
 
 See [Skipping steps based on cache-hit](#skipping-steps-based-on-cache-hit) for info on using this output
 

__tests__/restore.test.ts

@@ -149,7 +149,7 @@ test("restore with cache found for key", async () => {
     const infoMock = jest.spyOn(core, "info");
     const failedMock = jest.spyOn(core, "setFailed");
     const stateMock = jest.spyOn(core, "saveState");
-    const setCacheHitOutputMock = jest.spyOn(core, "setOutput");
+    const setOutputMock = jest.spyOn(core, "setOutput");
     const restoreCacheMock = jest
         .spyOn(cache, "restoreCache")
         .mockImplementationOnce(() => {
@@ -173,8 +173,10 @@ test("restore with cache found for key", async () => {
     expect(stateMock).toHaveBeenCalledWith("CACHE_RESULT", key);
     expect(stateMock).toHaveBeenCalledTimes(2);
 
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(1);
-    expect(setCacheHitOutputMock).toHaveBeenCalledWith("cache-hit", "true");
+    expect(setOutputMock).toHaveBeenCalledTimes(3);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-hit", "true");
+    expect(setOutputMock).toHaveBeenCalledWith("cache-primary-key", key);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-matched-key", key);
 
     expect(infoMock).toHaveBeenCalledWith(`Cache restored from key: ${key}`);
     expect(failedMock).toHaveBeenCalledTimes(0);
@@ -194,7 +196,7 @@ test("restore with cache found for restore key", async () => {
     const infoMock = jest.spyOn(core, "info");
     const failedMock = jest.spyOn(core, "setFailed");
     const stateMock = jest.spyOn(core, "saveState");
-    const setCacheHitOutputMock = jest.spyOn(core, "setOutput");
+    const setOutputMock = jest.spyOn(core, "setOutput");
     const restoreCacheMock = jest
         .spyOn(cache, "restoreCache")
         .mockImplementationOnce(() => {
@@ -218,8 +220,10 @@ test("restore with cache found for restore key", async () => {
     expect(stateMock).toHaveBeenCalledWith("CACHE_RESULT", restoreKey);
     expect(stateMock).toHaveBeenCalledTimes(2);
 
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(1);
-    expect(setCacheHitOutputMock).toHaveBeenCalledWith("cache-hit", "false");
+    expect(setOutputMock).toHaveBeenCalledTimes(3);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-hit", "false");
+    expect(setOutputMock).toHaveBeenCalledWith("cache-primary-key", key);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-matched-key", restoreKey);
     expect(infoMock).toHaveBeenCalledWith(
         `Cache restored from key: ${restoreKey}`
     );
@@ -239,7 +243,7 @@ test("Fail restore when fail on cache miss is enabled and primary + restore keys
 
     const failedMock = jest.spyOn(core, "setFailed");
     const stateMock = jest.spyOn(core, "saveState");
-    const setCacheHitOutputMock = jest.spyOn(core, "setOutput");
+    const setOutputMock = jest.spyOn(core, "setOutput");
     const restoreCacheMock = jest
         .spyOn(cache, "restoreCache")
         .mockImplementationOnce(() => {
@@ -260,7 +264,8 @@ test("Fail restore when fail on cache miss is enabled and primary + restore keys
     );
 
     expect(stateMock).toHaveBeenCalledWith("CACHE_KEY", key);
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(0);
+    expect(setOutputMock).toHaveBeenCalledTimes(1);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-primary-key", key);
 
     expect(failedMock).toHaveBeenCalledWith(
         `Failed to restore cache entry. Exiting as fail-on-cache-miss is set. Input key: ${key}`
@@ -282,7 +287,7 @@ test("restore when fail on cache miss is enabled and primary key doesn't match r
     const infoMock = jest.spyOn(core, "info");
     const failedMock = jest.spyOn(core, "setFailed");
     const stateMock = jest.spyOn(core, "saveState");
-    const setCacheHitOutputMock = jest.spyOn(core, "setOutput");
+    const setOutputMock = jest.spyOn(core, "setOutput");
     const restoreCacheMock = jest
         .spyOn(cache, "restoreCache")
         .mockImplementationOnce(() => {
@@ -306,8 +311,10 @@ test("restore when fail on cache miss is enabled and primary key doesn't match r
     expect(stateMock).toHaveBeenCalledWith("CACHE_RESULT", restoreKey);
     expect(stateMock).toHaveBeenCalledTimes(2);
 
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(1);
-    expect(setCacheHitOutputMock).toHaveBeenCalledWith("cache-hit", "false");
+    expect(setOutputMock).toHaveBeenCalledTimes(3);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-hit", "false");
+    expect(setOutputMock).toHaveBeenCalledWith("cache-primary-key", key);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-matched-key", restoreKey);
 
     expect(infoMock).toHaveBeenCalledWith(
         `Cache restored from key: ${restoreKey}`

__tests__/restoreImpl.test.ts

@@ -112,7 +112,7 @@ test("restore on GHES with AC available ", async () => {
     const infoMock = jest.spyOn(core, "info");
     const failedMock = jest.spyOn(core, "setFailed");
     const stateMock = jest.spyOn(core, "saveState");
-    const setCacheHitOutputMock = jest.spyOn(core, "setOutput");
+    const setOutputMock = jest.spyOn(core, "setOutput");
     const restoreCacheMock = jest
         .spyOn(cache, "restoreCache")
         .mockImplementationOnce(() => {
@@ -133,8 +133,10 @@ test("restore on GHES with AC available ", async () => {
     );
 
     expect(stateMock).toHaveBeenCalledWith("CACHE_KEY", key);
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(1);
-    expect(setCacheHitOutputMock).toHaveBeenCalledWith("cache-hit", "true");
+    expect(setOutputMock).toHaveBeenCalledTimes(3);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-hit", "true");
+    expect(setOutputMock).toHaveBeenCalledWith("cache-primary-key", key);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-matched-key", key);
 
     expect(infoMock).toHaveBeenCalledWith(`Cache restored from key: ${key}`);
     expect(failedMock).toHaveBeenCalledTimes(0);
@@ -334,7 +336,7 @@ test("restore with cache found for key", async () => {
     const infoMock = jest.spyOn(core, "info");
     const failedMock = jest.spyOn(core, "setFailed");
     const stateMock = jest.spyOn(core, "saveState");
-    const setCacheHitOutputMock = jest.spyOn(core, "setOutput");
+    const setOutputMock = jest.spyOn(core, "setOutput");
     const restoreCacheMock = jest
         .spyOn(cache, "restoreCache")
         .mockImplementationOnce(() => {
@@ -355,8 +357,10 @@ test("restore with cache found for key", async () => {
     );
 
     expect(stateMock).toHaveBeenCalledWith("CACHE_KEY", key);
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(1);
-    expect(setCacheHitOutputMock).toHaveBeenCalledWith("cache-hit", "true");
+    expect(setOutputMock).toHaveBeenCalledTimes(3);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-hit", "true");
+    expect(setOutputMock).toHaveBeenCalledWith("cache-primary-key", key);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-matched-key", key);
 
     expect(infoMock).toHaveBeenCalledWith(`Cache restored from key: ${key}`);
     expect(failedMock).toHaveBeenCalledTimes(0);
@@ -376,7 +380,7 @@ test("restore with cache found for restore key", async () => {
     const infoMock = jest.spyOn(core, "info");
     const failedMock = jest.spyOn(core, "setFailed");
     const stateMock = jest.spyOn(core, "saveState");
-    const setCacheHitOutputMock = jest.spyOn(core, "setOutput");
+    const setOutputMock = jest.spyOn(core, "setOutput");
     const restoreCacheMock = jest
         .spyOn(cache, "restoreCache")
         .mockImplementationOnce(() => {
@@ -397,8 +401,10 @@ test("restore with cache found for restore key", async () => {
     );
 
     expect(stateMock).toHaveBeenCalledWith("CACHE_KEY", key);
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(1);
-    expect(setCacheHitOutputMock).toHaveBeenCalledWith("cache-hit", "false");
+    expect(setOutputMock).toHaveBeenCalledTimes(3);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-hit", "false");
+    expect(setOutputMock).toHaveBeenCalledWith("cache-primary-key", key);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-matched-key", restoreKey);
     expect(infoMock).toHaveBeenCalledWith(
         `Cache restored from key: ${restoreKey}`
     );
@@ -417,7 +423,7 @@ test("restore with lookup-only set", async () => {
     const infoMock = jest.spyOn(core, "info");
     const failedMock = jest.spyOn(core, "setFailed");
     const stateMock = jest.spyOn(core, "saveState");
-    const setCacheHitOutputMock = jest.spyOn(core, "setOutput");
+    const setOutputMock = jest.spyOn(core, "setOutput");
     const restoreCacheMock = jest
         .spyOn(cache, "restoreCache")
         .mockImplementationOnce(() => {
@@ -441,8 +447,10 @@ test("restore with lookup-only set", async () => {
     expect(stateMock).toHaveBeenCalledWith("CACHE_RESULT", key);
     expect(stateMock).toHaveBeenCalledTimes(2);
 
-    expect(setCacheHitOutputMock).toHaveBeenCalledTimes(1);
-    expect(setCacheHitOutputMock).toHaveBeenCalledWith("cache-hit", "true");
+    expect(setOutputMock).toHaveBeenCalledTimes(3);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-hit", "true");
+    expect(setOutputMock).toHaveBeenCalledWith("cache-primary-key", key);
+    expect(setOutputMock).toHaveBeenCalledWith("cache-matched-key", key);
 
     expect(infoMock).toHaveBeenCalledWith(
         `Cache found and can be restored from key: ${key}`

__tests__/stateProvider.test.ts

@@ -54,7 +54,7 @@ test("StateProvider saves states", async () => {
     expect(cacheStateValue).toBe(cacheMatchedKey);
     expect(getStateMock).toHaveBeenCalledTimes(2);
     expect(saveStateMock).toHaveBeenCalledTimes(2);
-    expect(setOutputMock).toHaveBeenCalledTimes(0);
+    expect(setOutputMock).toHaveBeenCalledTimes(2);
 });
 
 test("NullStateProvider saves outputs", async () => {

action.yml

@@ -37,6 +37,10 @@ inputs:
 outputs:
   cache-hit:
     description: 'A boolean value to indicate an exact match was found for the primary key'
+  cache-primary-key:
+    description: 'A resolved cache key for which cache match was attempted'
+  cache-matched-key:
+    description: 'Key of the cache that was restored, it could either be the primary key on cache-hit or a partial/complete match of one of the restore keys'
 runs:
   using: 'node20'
   main: 'dist/restore/index.js'

dist/restore-only/index.js

@@ -66238,21 +66238,22 @@ class StateProviderBase {
 class StateProvider extends StateProviderBase {
     constructor() {
         super(...arguments);
-        this.setState = core.saveState;
+        this.setState = (key, value) => { core.saveState(key, value); stateToOutput(key, value); };
         this.getState = core.getState;
     }
 }
 exports.StateProvider = StateProvider;
-class NullStateProvider extends StateProviderBase {
-    constructor() {
-        super(...arguments);
-        this.stateToOutputMap = new Map([
+const stateToOutputMap = new Map([
     [constants_1.State.CacheMatchedKey, constants_1.Outputs.CacheMatchedKey],
     [constants_1.State.CachePrimaryKey, constants_1.Outputs.CachePrimaryKey]
 ]);
-        this.setState = (key, value) => {
-            core.setOutput(this.stateToOutputMap.get(key), value);
-        };
+function stateToOutput(key, value) {
+    core.setOutput(stateToOutputMap.get(key), value);
+}
+class NullStateProvider extends StateProviderBase {
+    constructor() {
+        super(...arguments);
+        this.setState = stateToOutput;
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         this.getState = (key) => "";
     }

dist/restore/index.js

@@ -66238,21 +66238,22 @@ class StateProviderBase {
 class StateProvider extends StateProviderBase {
     constructor() {
         super(...arguments);
-        this.setState = core.saveState;
+        this.setState = (key, value) => { core.saveState(key, value); stateToOutput(key, value); };
         this.getState = core.getState;
     }
 }
 exports.StateProvider = StateProvider;
-class NullStateProvider extends StateProviderBase {
-    constructor() {
-        super(...arguments);
-        this.stateToOutputMap = new Map([
+const stateToOutputMap = new Map([
     [constants_1.State.CacheMatchedKey, constants_1.Outputs.CacheMatchedKey],
     [constants_1.State.CachePrimaryKey, constants_1.Outputs.CachePrimaryKey]
 ]);
-        this.setState = (key, value) => {
-            core.setOutput(this.stateToOutputMap.get(key), value);
-        };
+function stateToOutput(key, value) {
+    core.setOutput(stateToOutputMap.get(key), value);
+}
+class NullStateProvider extends StateProviderBase {
+    constructor() {
+        super(...arguments);
+        this.setState = stateToOutput;
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         this.getState = (key) => "";
     }

dist/save-only/index.js

@@ -66251,21 +66251,22 @@ class StateProviderBase {
 class StateProvider extends StateProviderBase {
     constructor() {
         super(...arguments);
-        this.setState = core.saveState;
+        this.setState = (key, value) => { core.saveState(key, value); stateToOutput(key, value); };
         this.getState = core.getState;
     }
 }
 exports.StateProvider = StateProvider;
-class NullStateProvider extends StateProviderBase {
-    constructor() {
-        super(...arguments);
-        this.stateToOutputMap = new Map([
+const stateToOutputMap = new Map([
     [constants_1.State.CacheMatchedKey, constants_1.Outputs.CacheMatchedKey],
     [constants_1.State.CachePrimaryKey, constants_1.Outputs.CachePrimaryKey]
 ]);
-        this.setState = (key, value) => {
-            core.setOutput(this.stateToOutputMap.get(key), value);
-        };
+function stateToOutput(key, value) {
+    core.setOutput(stateToOutputMap.get(key), value);
+}
+class NullStateProvider extends StateProviderBase {
+    constructor() {
+        super(...arguments);
+        this.setState = stateToOutput;
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         this.getState = (key) => "";
     }

dist/save/index.js

@@ -66251,21 +66251,22 @@ class StateProviderBase {
 class StateProvider extends StateProviderBase {
     constructor() {
         super(...arguments);
-        this.setState = core.saveState;
+        this.setState = (key, value) => { core.saveState(key, value); stateToOutput(key, value); };
         this.getState = core.getState;
     }
 }
 exports.StateProvider = StateProvider;
-class NullStateProvider extends StateProviderBase {
-    constructor() {
-        super(...arguments);
-        this.stateToOutputMap = new Map([
+const stateToOutputMap = new Map([
     [constants_1.State.CacheMatchedKey, constants_1.Outputs.CacheMatchedKey],
     [constants_1.State.CachePrimaryKey, constants_1.Outputs.CachePrimaryKey]
 ]);
-        this.setState = (key, value) => {
-            core.setOutput(this.stateToOutputMap.get(key), value);
-        };
+function stateToOutput(key, value) {
+    core.setOutput(stateToOutputMap.get(key), value);
+}
+class NullStateProvider extends StateProviderBase {
+    constructor() {
+        super(...arguments);
+        this.setState = stateToOutput;
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         this.getState = (key) => "";
     }

src/stateProvider.ts

@@ -28,19 +28,22 @@ class StateProviderBase implements IStateProvider {
 }
 
 export class StateProvider extends StateProviderBase {
-    setState = core.saveState;
+    setState = (key: string, value: string) => {
+        core.saveState(key, value);
+        stateToOutput(key, value);
+    };
     getState = core.getState;
 }
 
-export class NullStateProvider extends StateProviderBase {
-    stateToOutputMap = new Map<string, string>([
+const stateToOutputMap = new Map<string, string>([
     [State.CacheMatchedKey, Outputs.CacheMatchedKey],
     [State.CachePrimaryKey, Outputs.CachePrimaryKey]
 ]);
-
-    setState = (key: string, value: string) => {
-        core.setOutput(this.stateToOutputMap.get(key) as string, value);
-    };
+function stateToOutput(key: string, value: string) {
+    core.setOutput(stateToOutputMap.get(key) as string, value);
+}
+export class NullStateProvider extends StateProviderBase {
+    setState = stateToOutput;
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     getState = (key: string) => "";
 }