From 806c1bbc966dc0edb943336f7c341fd8fc6d0089 Mon Sep 17 00:00:00 2001
From: mlugg <mlugg@mlugg.co.uk>
Date: Mon, 10 Mar 2025 16:12:40 +0000
Subject: [PATCH] Add option to customize cache key

This *shouldn't* be necessary, but the way matrix strategies work in
Actions means we literally cannot automatically differentiate jobs in
the same workflow with different matrix variable values. So, if the user
is using a matrix to customize anything other than the OS, they'll need
to specify this.

Resolves: #18
---
 README.md  | 6 ++++++
 action.yml | 4 ++++
 common.js  | 4 +++-
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d64c8bc..a2eb8dd 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,13 @@ If necessary, the caching of the global Zig cache directory can be disabled by s
 `use-cache: false`. Don't do this without reason: preserving the Zig cache will typically speed things up
 and decrease the load on GitHub's runners.
 
+If you are using a [matrix strategy][matrix] for your workflow, you may need to populate the `cache-key` option
+with all of your matrix variables to ensure that every job is correctly cached. Unfortunately, GitHub does not
+provide any means for the Action to automatically distinguish jobs in a matrix. However, variables which select
+the runner OS can be omitted from the `cache-key`, since the runner OS is included in the cache key by default.
+
 [mach-nominated]: https://machengine.org/about/nominated-zig/
+[matrix]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow
 
 ## Details
 
diff --git a/action.yml b/action.yml
index a6f3b23..bf78457 100644
--- a/action.yml
+++ b/action.yml
@@ -12,6 +12,10 @@ inputs:
     description: 'Whether to cache the global Zig cache directory.'
     required: true
     default: true
+  cache-key:
+    description: 'Additional cache key component to include when caching the global Zig cache directory. When using a matrix strategy, this should include the matrix variables to ensure all jobs are cached. Matrix variables which decide the OS can be omitted, since the OS is always included in the cache key.'
+    required: false
+    default: ''
 runs:
   using: 'node20'
   main: 'main.js'
diff --git a/common.js b/common.js
index c5e7cf4..8125319 100644
--- a/common.js
+++ b/common.js
@@ -135,7 +135,9 @@ async function getTarballExt() {
 async function getCachePrefix() {
   const tarball_name = await getTarballName();
   const job_name = github.context.job.replaceAll(/[^\w]/g, "_");
-  return `setup-zig-cache-${job_name}-${tarball_name}-`;
+  const user_key = core.getInput('cache-key');
+
+  return `setup-zig-cache-${job_name}-${tarball_name}-${user_key}-`;
 }
 
 async function getZigCachePath() {