mirror of
https://github.com/jdx/mise-action.git
synced 2026-05-14 22:00:34 +00:00
fix(cache): isolate cache keys per working_directory in monorepos (#360)
Problem
-------
mise-action hashes ALL mise config files in the repo to compute a single
default cache key. In a monorepo with multiple projects (e.g.,
apps/frontend, apps/backend), this causes cache pollution:
1. Job A runs for apps/frontend, installs only frontend tools
2. Cache is saved with a key based on ALL configs
3. Job B runs for apps/backend, gets cache HIT (same key)
4. Job B finds frontend tools but not backend tools
5. Job B has to install all tools because they are missing from cache
Additionally, any change to an unrelated project config would bust the
cache for all projects.
Solution
--------
When working_directory is set, compute the default cache key using only
the config files that affect that directory (detected via `mise config
ls --json`) instead of globbing all configs in the repo.
This required separating binary and tools caching:
- Binary cache: restored first so mise is available for `mise config ls`
- Tools cache: default key computed after mise is installed
Key Implementation Details
--------------------------
1. Cache separation:
- restoreMiseBinaryCache/saveMiseBinaryCache for the mise binary
- restoreToolsCache/saveToolsCache for the full mise directory
- Binary cache key: `{prefix}-binary-{platform}-{version}-{dirHash}`
- Tools default cache key: based on config file contents for
working_directory
2. Binary backup during tools cache restore: The tools cache includes
bin/, which could overwrite the binary that setupMise() just installed.
We use withBinaryBackup() to backup the binary before restoring the
tools cache and restore it afterward.
An alternative approach would be to only cache installs/ and shims/
instead of the full miseDir(), but that would change the caching
behavior for existing users. Using withBinaryBackup() retains the
original caching behavior while preventing the binary from being
overwritten.
3. Binary cache key includes mise_dir hash: Prevents cache collision
when users change mise_dir between runs. Without this, a cache hit could
restore the binary to the wrong location.
4. Explicit mise binary path: Uses full path to mise binary instead of
relying on PATH lookup, avoiding potential race conditions with
core.addPath().
5. Lock file handling:
- .toml files: look for corresponding .lock file
- .tool-versions: look for mise.lock in the same directory
6. Graceful degradation: If `mise config ls` fails when
working_directory is set, caching is disabled with a warning rather
than:
- Failing the action entirely, or
- Falling back to glob patterns (which would reintroduce the bug)
Backward Compatibility
----------------------
- working_directory not set: No change, uses existing glob of all
configs
- working_directory set: Default cache key based on `mise config ls`
output
Note on cache_key input: The `cache_key` input now only controls the
tools cache key. The binary cache key is always computed automatically
based on platform, version, and mise_dir. This is generally better since
the binary cache is version-stable and does not need custom key logic.
Test Coverage
-------------
Added test-monorepo-cache.yml with 8 test scenarios:
- install-backend/restore-frontend: Verify cache isolation
- install-frontend/unrelated-change-no-bust: Verify unrelated changes do
not bust cache
- parent-config-change: Verify parent config changes bust child cache
- lock-file-change: Verify lock file changes bust cache
- install-default-mise-dir/restore-custom-mise-dir: Verify mise_dir in
cache key
Final Note
----------
Currently, the default tool cache key includes the mise version. This
was in place prior, so it was left intact. With this change and the
splitting of the mise version cache from the tool cache, we could safely
remove the mise version from the tool cache key. Left this for a
subsequent change if desired.
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Fixes cache key pollution in monorepos by scoping tool cache keys to
the `working_directory`'s config hierarchy and separating binary vs.
tools caching.
>
> - New cache flow: `restoreMiseBinaryCache/saveMiseBinaryCache` (key:
`{prefix}-binary-{platform}-{version}-{dirHash}`) runs before
installation; `restoreToolsCache/saveToolsCache` uses a default key
derived from `mise config ls --json` for the specified
`working_directory`
> - Uses explicit `mise` binary path and preserves it during tools cache
restore via `withBinaryBackup` to avoid overwrites
> - Default tools key still supports template inputs; includes lockfile
handling and guards to disable caching on failures
> - `mise_dir` hash included in binary cache key to prevent cross-dir
collisions
> - Adds `.github/workflows/test-monorepo-cache.yml` with scenarios
verifying monorepo cache isolation, unrelated-config no-bust,
parent-config change bust, lockfile change bust, identical-content
different-path isolation, and `mise_dir`-key differentiation
> - Updates compiled `dist/` artifacts; minor docs entry `AGENTS.md`
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
434d5feca5. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
This commit is contained in:
Chad McElligott
GitHub
parent
23096c7b0b
commit
891faa7084
5 changed files with 691 additions and 81 deletions
219
.github/workflows/test-monorepo-cache.yml
vendored
Normal file
219
.github/workflows/test-monorepo-cache.yml
vendored
Normal file
|
|
@ -0,0 +1,219 @@
|
|||
# Test monorepo cache isolation: when working_directory is set, each directory
|
||||
# should get its own cache key based on its config hierarchy, not all configs
|
||||
# in the repo. This prevents cache pollution between unrelated projects.
|
||||
name: "test-monorepo-cache"
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
env:
|
||||
# Simulates a monorepo with:
|
||||
# - Root config with shared tool (actionlint)
|
||||
# - Frontend with its own tool (shfmt)
|
||||
# - Backend with its own tool (shellcheck)
|
||||
# Frontend and backend both inherit the root config.
|
||||
SETUP_MONOREPO: |
|
||||
mkdir -p apps/frontend apps/backend
|
||||
echo '[tools]' > mise.toml
|
||||
echo 'actionlint = "1"' >> mise.toml
|
||||
echo '[tools]' > apps/frontend/mise.toml
|
||||
echo 'shfmt = "3"' >> apps/frontend/mise.toml
|
||||
echo '[tools]' > apps/backend/mise.toml
|
||||
echo 'shellcheck = "0.10"' >> apps/backend/mise.toml
|
||||
|
||||
# Simple single-tool config for mise_dir tests
|
||||
SETUP_SIMPLE: |
|
||||
echo '[tools]' > mise.toml
|
||||
echo 'actionlint = "1"' >> mise.toml
|
||||
|
||||
jobs:
|
||||
# Install ONLY backend tools and save cache.
|
||||
# This cache should NOT be shared with frontend.
|
||||
install-backend:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: ${{ env.SETUP_MONOREPO }}
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/backend
|
||||
cache_key_prefix: monorepo-test-${{ github.run_id }}
|
||||
|
||||
# Try to restore frontend after backend cache exists - should be cache MISS
|
||||
# since frontend has a different working_directory and thus a different cache key.
|
||||
restore-frontend:
|
||||
needs: install-backend
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: ${{ env.SETUP_MONOREPO }}
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/frontend
|
||||
install: false
|
||||
cache_key_prefix: monorepo-test-${{ github.run_id }}
|
||||
- name: Verify cache isolation
|
||||
run: |
|
||||
# With the fix, frontend has a different cache key, so cache miss = no tools
|
||||
# With the bug, frontend has same key as backend, so cache hit = has shellcheck but not shfmt
|
||||
if [ -f ~/.local/share/mise/shims/shellcheck ]; then
|
||||
echo "FAIL: shellcheck found - frontend got backend's cache (shared key bug)"
|
||||
exit 1
|
||||
fi
|
||||
echo "PASS: No backend tools found - cache keys are properly isolated"
|
||||
|
||||
# Install frontend and save cache (used by unrelated-change-no-bust)
|
||||
install-frontend:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: ${{ env.SETUP_MONOREPO }}
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/frontend
|
||||
cache_key_prefix: unrelated-${{ github.run_id }}
|
||||
|
||||
# Test that changing an UNRELATED directory's config does NOT bust the cache.
|
||||
# Only configs affecting the working_directory are hashed.
|
||||
unrelated-change-no-bust:
|
||||
needs: install-frontend
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: ${{ env.SETUP_MONOREPO }}
|
||||
|
||||
# Modify BACKEND config (unrelated to frontend)
|
||||
- run: echo 'jq = "1"' >> apps/backend/mise.toml
|
||||
|
||||
# Try to restore frontend - should still be a cache HIT
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/frontend
|
||||
install: false
|
||||
cache_key_prefix: unrelated-${{ github.run_id }}
|
||||
|
||||
- name: Verify cache still hits after unrelated change
|
||||
run: |
|
||||
if [ ! -f ~/.local/share/mise/shims/shfmt ]; then
|
||||
echo "FAIL: shfmt missing - unrelated backend change busted frontend cache"
|
||||
exit 1
|
||||
fi
|
||||
echo "PASS: Frontend cache survived unrelated backend change"
|
||||
|
||||
# Test that changing a parent config changes the child's cache key.
|
||||
# We modify the root mise.toml and verify the cache key is different
|
||||
# (cache miss on restore attempt).
|
||||
parent-config-change:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: ${{ env.SETUP_MONOREPO }}
|
||||
|
||||
# Install frontend with original root config
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/frontend
|
||||
cache_key_prefix: parent-change-${{ github.run_id }}
|
||||
|
||||
# Clear local mise state to simulate a fresh restore
|
||||
- run: rm -rf ~/.local/share/mise/installs ~/.local/share/mise/shims
|
||||
|
||||
# Modify root config (add a new tool)
|
||||
- run: echo 'taplo = "0.9"' >> mise.toml
|
||||
|
||||
# Try to restore - should be a cache MISS because root config changed
|
||||
- uses: ./
|
||||
id: restore-after-change
|
||||
with:
|
||||
working_directory: apps/frontend
|
||||
install: false
|
||||
cache_key_prefix: parent-change-${{ github.run_id }}
|
||||
|
||||
# Verify cache miss (shfmt not present because we didn't install)
|
||||
- name: Verify cache miss after parent change
|
||||
run: |
|
||||
if [ -f ~/.local/share/mise/shims/shfmt ]; then
|
||||
echo "FAIL: shfmt found - cache should have missed after parent config change"
|
||||
exit 1
|
||||
fi
|
||||
echo "PASS: Cache missed as expected after parent config change"
|
||||
|
||||
# Test that changing a lock file changes the cache key.
|
||||
# Lock files pin exact versions, so changes should bust the cache.
|
||||
lock-file-change:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: |
|
||||
mkdir -p apps/project
|
||||
echo '[tools]' > apps/project/mise.toml
|
||||
echo 'shfmt = "3"' >> apps/project/mise.toml
|
||||
echo 'lockfile = "v1"' > apps/project/mise.lock
|
||||
|
||||
# Install with original lock file
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/project
|
||||
cache_key_prefix: lock-change-${{ github.run_id }}
|
||||
|
||||
# Clear local mise state
|
||||
- run: rm -rf ~/.local/share/mise/installs ~/.local/share/mise/shims
|
||||
|
||||
# Modify lock file
|
||||
- run: echo 'lockfile = "v2"' > apps/project/mise.lock
|
||||
|
||||
# Try to restore - should be cache MISS because lock file changed
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/project
|
||||
install: false
|
||||
cache_key_prefix: lock-change-${{ github.run_id }}
|
||||
|
||||
- name: Verify cache miss after lock file change
|
||||
run: |
|
||||
if [ -f ~/.local/share/mise/shims/shfmt ]; then
|
||||
echo "FAIL: shfmt found - cache should have missed after lock file change"
|
||||
exit 1
|
||||
fi
|
||||
echo "PASS: Cache missed as expected after lock file change"
|
||||
|
||||
# Test that IDENTICAL content in DIFFERENT paths produces DIFFERENT cache keys.
|
||||
# This prevents hash collisions from concatenating file contents without separators.
|
||||
install-identical-content-alpha:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: |
|
||||
mkdir -p apps/alpha
|
||||
echo '[tools]' > apps/alpha/mise.toml
|
||||
echo 'shfmt = "3"' >> apps/alpha/mise.toml
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/alpha
|
||||
cache_key_prefix: identical-content-${{ github.run_id }}
|
||||
|
||||
# Try to restore with IDENTICAL content but DIFFERENT path - should be cache MISS
|
||||
restore-identical-content-beta:
|
||||
needs: install-identical-content-alpha
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: |
|
||||
mkdir -p apps/beta
|
||||
# Exact same content as alpha
|
||||
echo '[tools]' > apps/beta/mise.toml
|
||||
echo 'shfmt = "3"' >> apps/beta/mise.toml
|
||||
- uses: ./
|
||||
with:
|
||||
working_directory: apps/beta
|
||||
install: false
|
||||
cache_key_prefix: identical-content-${{ github.run_id }}
|
||||
- name: Verify different paths produce different cache keys
|
||||
run: |
|
||||
if [ -f ~/.local/share/mise/shims/shfmt ]; then
|
||||
echo "FAIL: shfmt found - identical content in different path caused cache collision"
|
||||
exit 1
|
||||
fi
|
||||
echo "PASS: Identical content in different paths correctly produced different cache keys"
|
||||
Loading…
Add table
Add a link
Reference in a new issue