ci: namespace fixture cache keys

Author: huntharo

.github/workflows/ci.yml

@@ -13,10 +13,9 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v6
+      - uses: ./
         with:
           node-version: 22.x
-          package-manager-cache: false
 
       - name: Run unit tests
         run: npm test
@@ -55,6 +54,7 @@ jobs:
         uses: ./
         with:
           working-directory: ${{ matrix.fixture }}
+          cache-key-suffix: fixture-tests
           lookup-only: "true"
 
       - name: Assert resolved action outputs
@@ -110,6 +110,7 @@ jobs:
         uses: ./
         with:
           working-directory: ${{ matrix.fixture }}
+          cache-key-suffix: fixture-tests
 
       - name: Assert restore behavior
         shell: bash

README.md

@@ -54,6 +54,7 @@ steps:
 | `node-version` | `22.x` | Node.js version to install with `actions/setup-node` |
 | `package-manager` | `""` | Explicit override for `npm`, `pnpm`, or `yarn` |
 | `working-directory` | `"."` | Repository-relative directory containing `package.json` and the lockfile |
+| `cache-key-suffix` | `""` | Optional suffix appended to the dependency cache key when you want to namespace cache entries |
 | `lookup-only` | `"false"` | When `true`, only checks whether the cache exists and skips downloading it |
 
 ## Outputs

action.yml

@@ -11,6 +11,9 @@ inputs:
   working-directory:
     description: "Repository-relative directory containing package.json and lockfile"
     default: "."
+  cache-key-suffix:
+    description: "Optional suffix appended to the dependency cache key for namespacing"
+    default: ""
   lookup-only:
     description: "If true, only checks if the dependency cache exists and skips download. Does not change save cache behavior"
     default: "false"
@@ -62,6 +65,7 @@ runs:
         node "$GITHUB_ACTION_PATH/scripts/resolve-cache-paths.mjs" \
           --cwd "$GITHUB_WORKSPACE" \
           --working-directory "${{ inputs.working-directory }}" \
+          --cache-key-suffix "${{ inputs.cache-key-suffix }}" \
           --github-output "$GITHUB_OUTPUT"
 
     - name: Resolve package manager
@@ -83,7 +87,7 @@ runs:
       uses: actions/cache@v5
       with:
         path: ${{ steps.resolve-cache-paths.outputs.cachePaths }}
-        key: node-modules-${{ inputs.node-version }}-${{ runner.os }}-${{ runner.arch }}-${{ steps.resolve-cache-paths.outputs.workingDirectoryKey }}-${{ steps.resolve-package-manager.outputs.managerCacheKey }}-${{ steps.resolve-package-manager.outputs.lockfileSha }}
+        key: node-modules-${{ inputs.node-version }}-${{ runner.os }}-${{ runner.arch }}-${{ steps.resolve-cache-paths.outputs.workingDirectoryKey }}-${{ steps.resolve-package-manager.outputs.managerCacheKey }}-${{ steps.resolve-package-manager.outputs.lockfileSha }}${{ steps.resolve-cache-paths.outputs.cacheKeySuffixSegment }}
         lookup-only: ${{ inputs.lookup-only }}
 
     - name: Install dependencies

package-lock.json

@@ -7,6 +7,7 @@ export function parseArgs(argv) {
   const args = {
     cwd: process.cwd(),
     workingDirectory: '.',
+    cacheKeySuffix: '',
     githubOutput: process.env.GITHUB_OUTPUT ?? '',
   };
 
@@ -19,6 +20,9 @@ export function parseArgs(argv) {
     } else if (arg === '--working-directory') {
       args.workingDirectory = argv[index + 1] ?? '.';
       index += 1;
+    } else if (arg === '--cache-key-suffix') {
+      args.cacheKeySuffix = argv[index + 1] ?? '';
+      index += 1;
     } else if (arg === '--github-output') {
       args.githubOutput = argv[index + 1] ?? '';
       index += 1;
@@ -76,6 +80,15 @@ export function buildWorkingDirectoryKey(workingDirectory) {
   return `${slug}-${digest}`;
 }
 
+export function normalizeCacheKeySuffix(cacheKeySuffix) {
+  const normalized = cacheKeySuffix.trim();
+  if (normalized === '') {
+    return '';
+  }
+
+  return normalized.replace(/[^A-Za-z0-9_.-]+/g, '-');
+}
+
 export function buildCachePaths(workingDirectory) {
   const base = workingDirectory === '.' ? '' : `${workingDirectory}/`;
   return [
@@ -86,8 +99,9 @@ export function buildCachePaths(workingDirectory) {
   ];
 }
 
-export function buildResult({ cwd, workingDirectory }) {
+export function buildResult({ cwd, workingDirectory, cacheKeySuffix = '' }) {
   const resolvedWorkingDirectory = resolveWorkingDirectory(cwd, workingDirectory);
+  const normalizedCacheKeySuffix = normalizeCacheKeySuffix(cacheKeySuffix);
 
   return {
     absoluteWorkingDirectory: resolvedWorkingDirectory.absoluteWorkingDirectory,
@@ -96,6 +110,9 @@ export function buildResult({ cwd, workingDirectory }) {
       resolvedWorkingDirectory.workingDirectory,
     ),
     cachePaths: buildCachePaths(resolvedWorkingDirectory.workingDirectory),
+    cacheKeySuffix: normalizedCacheKeySuffix,
+    cacheKeySuffixSegment:
+      normalizedCacheKeySuffix === '' ? '' : `-${normalizedCacheKeySuffix}`,
   };
 }
 
@@ -122,6 +139,7 @@ export function main(argv = process.argv.slice(2)) {
   const result = buildResult({
     cwd: args.cwd,
     workingDirectory: args.workingDirectory,
+    cacheKeySuffix: args.cacheKeySuffix,
   });
 
   writeGithubOutput(args.githubOutput, result);

scripts/resolve-cache-paths.mjs

@@ -8,6 +8,7 @@ import {
   buildCachePaths,
   buildResult,
   buildWorkingDirectoryKey,
+  normalizeCacheKeySuffix,
   resolveWorkingDirectory,
 } from '../scripts/resolve-cache-paths.mjs';
 
@@ -67,6 +68,12 @@ test('buildWorkingDirectoryKey generates a stable root key and nested slug', ()
   );
 });
 
+test('normalizeCacheKeySuffix preserves safe values and normalizes separators', () => {
+  assert.equal(normalizeCacheKeySuffix('fixture-tests'), 'fixture-tests');
+  assert.equal(normalizeCacheKeySuffix(' fixture tests / ci '), 'fixture-tests-ci');
+  assert.equal(normalizeCacheKeySuffix('   '), '');
+});
+
 test('buildCachePaths scopes cache globs to the resolved working directory', () => {
   assert.deepEqual(buildCachePaths('.'), [
     'node_modules',
@@ -90,10 +97,13 @@ test('buildResult combines normalized working-directory and cache metadata', ()
     const result = buildResult({
       cwd: tempDir,
       workingDirectory: 'fixtures/npm-basic',
+      cacheKeySuffix: 'fixture tests',
     });
 
     assert.equal(result.workingDirectory, 'fixtures/npm-basic');
     assert.match(result.workingDirectoryKey, /^fixtures__npm-basic-[a-f0-9]{8}$/);
     assert.equal(result.cachePaths[0], 'fixtures/npm-basic/node_modules');
+    assert.equal(result.cacheKeySuffix, 'fixture-tests');
+    assert.equal(result.cacheKeySuffixSegment, '-fixture-tests');
   });
 });