v1.7.2: Fix isolated objects-cache cleanup with mbx 1.22 and add clean-target-before-export

Cleanup of the isolated objects cache now works with the read-only object trees that mbx 1.22 creates. A new opt-in input, clean-target-before-export, frees runner disk space before the bundle is exported. Both changes apply only with isolate-objects-cache: true.

Added

• clean-target-before-export input (#68, @donbeave). Defaults to false. When set, the post step runs mbx clean for the configured workspace just before it exports the isolated objects bundle. This removes the workspace's managed Cargo target and learned incremental state, so the target and the staged bundle are not both on disk at the same time. The mbx action results and objects stay in the isolated store and are exported as usual.

  - uses: jdx/mr-boxington-action@v1
    with:
      github-cache-mode: objects
      isolate-objects-cache: true
      clean-target-before-export: true

  The input requires isolate-objects-cache: true, and setup fails without it. Cleanup runs only when the action is going to save after a cache miss. Restore-only runs and exact cache hits skip it. If cleanup fails, the action doesn't export the bundle. Enable this input only when no later step in the job needs the target tree. The disk-usage diagnostics also record a sample after cleanup and before export.

Fixed

• Removing isolated objects-cache directories with mbx 1.22 (#62, @donbeave). mbx 1.22 creates object-cache OUT_DIR trees that are read-only. Because of this, the action could not delete the isolated store or bundle after a successful import or during post-step cleanup. The action now restores owner write access across its own tree before deleting it. On Windows, it also clears the read-only flag on files. Symlinks inside the tree are not followed, so their targets outside the tree are left unchanged.

Full Changelog: v1.7.1...v1.7.2

v1.7.1: More accurate disk-usage reporting in isolated objects-cache mode

Fixes the disk-usage diagnostics that the post step logs when isolate-objects-cache: true is set. Cache restore and save behavior is unchanged.

Fixed

• Disk-usage summary for isolate-objects-cache (#60, @donbeave). The Objects cache sample summary in the post step is now more accurate and more reliable:
  • The action now waits for any sample still in progress and takes one last sample before it prints the summary. Before, the summary could be printed before sampling had finished, so it could miss the final disk usage.
  • When a diagnostic sample fails, the failure no longer replaces the actual result of the cache operation. If the restore or save itself failed, that original error is still the one reported. The summary records the number of sampling failures and a short reason code, such as code:EIO, without including file paths.
  • The archive-size figures now count cache.tar staging files, which are used on Windows runners, as well as cache.tgz.

Full Changelog: v1.7.0...v1.7.1

v1.7.0: Isolated objects cache and cache key suffixes

Parallel jobs can now save under their own primary keys with cache-key-suffix. On disposable hosted runners, the GitHub objects payload can now run from a private, job-scoped store with isolate-objects-cache. Both inputs are opt-in, so existing workflows are unaffected.

Added

• cache-key-suffix input (#58, @donbeave). The suffix is added to the end of the generated primary key, so matrix or parallel jobs save their own entries. It does not change the generated restore prefixes, so any job can still warm-start from another job's compatible entry.

  - uses: jdx/mr-boxington-action@v1
    with:
      cache-key-suffix: ${{ matrix.job }}

  The suffix may only contain ASCII letters, numbers, periods, underscores, and hyphens. The final key must be at most 512 characters. Setting both cache-key-suffix and cache-key is an error, so use cache-key on its own when you supply the full primary key. Explicit restore-keys are used as given.

• isolate-objects-cache input (#58, @donbeave). Defaults to false and requires backend: github with github-cache-mode: objects. Setup fails if you enable it with any other backend or mode. When it is on:

  • The live mbx store (MBX_CACHE_DIR) is placed in a private directory under RUNNER_TEMP.
  • On restore, the bundle is imported and then deleted.
  • On save, the action exports a bundle and checks it. It then deletes the isolated store before actions/cache packs its upload archive, so the job doesn't keep two copies on disk at once. Only the exported bundle is saved.

  - uses: jdx/mr-boxington-action@v1
    with:
      github-cache-mode: objects
      isolate-objects-cache: true

  The private directory is cleaned up whether the post step succeeds or fails. Use this mode only on disposable hosted runners. Leave it off on persistent runners that rely on mbx's normal warm store. Use one isolated objects-cache step per job. The bundle path is fixed so the cache version matches across jobs and runs.

  In this mode, the post step also logs disk usage at each stage. It sorts save failures by cause:

  • Another job reserving or finalizing the same key, GitHub cache service 5xx errors, and network failures produce a warning, and the job continues.
  • Running out of disk while staging the archive, or any save result the action can't identify, fails the step.

New Contributors

• @donbeave made their first contribution in #58

Full Changelog: v1.6.0...v1.7.0

v1.6.0: Opt-in cache saves from pull requests and protected branches, plus a `remote` backend

With the GitHub backend, pull requests and protected branches can now save their own cache entries, so later PR revisions reuse what earlier ones built. A new remote backend uses MBX_REMOTE_* settings exported by earlier steps instead of overwriting them. backend: server now works as an alias of remote, with small behavior changes listed below.

Added

• Opt-in saving from pull requests and protected branches (#48, #52, @garysassano). Until now, only default-branch pushes and opted-in workflow_dispatch runs saved, so every PR revision restored the default branch's baseline and rebuilt what the previous revision had already compiled. Two new inputs, both defaulting to false:

  • save-on-pull-request saves after a successful pull_request run from the same repository on refs/pull/<number>/merge. GitHub scopes these entries to that PR. Fork PRs and pull_request_target runs never save.
  • save-on-protected-branch saves after a successful push to a non-default branch where GITHUB_REF_PROTECTED=true.

  - uses: jdx/mr-boxington-action@v1
    with:
      save-on-pull-request: true

  A saving PR run gets a run-unique primary key (<sha>-run-<id>-<attempt>), so cache-hit is always false on those runs. When restore-keys is not set, the generated restore keys check the PR's own entries on the current base first, then the PR's newest entry on any base, then the base branch's latest entry. An explicit cache-key is used as given, with no per-run suffix. PR entries count toward the 10 GB repository cache limit. You can remove them when a PR closes with gh cache delete --all --ref refs/pull/<number>/merge.

• New cache-save-eligible and cache-save-reason outputs (#48, @garysassano) show whether a run may save and why, for example restore only (fork pull request). The same reason appears in the log and the job summary. The action now also follows the job's ACTIONS_CACHE_MODE: if it is read or none, a run that would otherwise save is reported as not saving, and the action no longer prunes and exports a payload that would be thrown away.

• remote backend (#53, @jdx). This backend installs mbx and uses whatever remote an earlier step already set up, such as a runner action that exports MBX_REMOTE_URL for an S3 bucket. Each input you set is exported as its MBX_REMOTE_* variable and overrides the environment. Settings with no input are left alone, including any AWS_* credentials. New remote-url (a cache server URL or an s3:// bucket) and remote-mode inputs are added. server-url and server-mode still work as aliases, but setting both spellings to different values is an error.

  - run: |
      echo "MBX_REMOTE_URL=s3://acme-build-cache/mbx" >> "$GITHUB_ENV"
      echo "MBX_REMOTE_NAMESPACE=acme/backend" >> "$GITHUB_ENV"
  - uses: jdx/mr-boxington-action@v1
    with:
      backend: remote

  During setup, the action runs mbx doctor --json to check the remote:

  • If no remote is configured, the step fails.
  • If mbx rejects the configuration, the step fails with mbx's reason.
  • If the remote can't be reached, the step only warns, so a cache outage doesn't fail the job.

  The job summary shows the remote and both the configured and effective mode.

Fixed

• The README said mbx disables the remote cache on tags and releases. That was wrong: those runs can still read from it but not write to it (#53).
• Updated the bundled undici to 6.29.0 and brace-expansion to 1.1.21 to fix npm audit findings (#57, @jdx).

Breaking Changes

These apply to existing backend: server users (#53):

• server-mode no longer defaults to read-write. Before, the action always exported MBX_REMOTE_MODE=read-write, which overrode any mode set earlier in the job. mbx's own default is still read-write, so workflows that set no mode anywhere behave the same as before.
• Setup now makes one network request to the remote through mbx doctor. A configuration mbx rejects now fails setup instead of the first build. A missing namespace still fails setup, as it did before.
• With backend: remote/server, the step now fails if no remote is configured anywhere. Before, it fell back to the local cache without saying so. Make sure any step that sets MBX_REMOTE_* runs before this action.

Full Changelog: v1.5.0...v1.6.0

v1.5.0: Cache a Cargo workspace below the checkout root

A new working-directory input lets the default target payload cache a Cargo workspace that lives in a subdirectory of the repository, such as rust/ next to a TypeScript package. It defaults to ., so existing workflows work the same as before.

Added

• working-directory input for the target payload (#46, @garysassano). Until now, the target payload always cached ./target and ran cargo metadata from the job's working directory. That broke when the workspace sat below the checkout root: the restore went to a root target/ that Cargo never writes to. On saving runs, the post step then either skipped the save or failed because there was no root manifest. With working-directory set, the action now:

  • caches <working-directory>/target
  • sets up build-script shims in that directory
  • runs the post-step cargo metadata prune in that workspace

  The path is resolved relative to the job's working directory. If the directory doesn't exist, setup fails instead of silently caching nothing.

  - uses: jdx/mr-boxington-action@v1
    with:
      working-directory: rust
  - run: mbx test --workspace
    working-directory: rust

  The cached tree is still always <workspace>/target. A custom CARGO_TARGET_DIR or build.target-dir is not followed.

New Contributors

• @garysassano made their first contribution in #46

Full Changelog: v1.4.0...v1.5.0

v1.4.0: Faster object-mode restores from a directory bundle

github-cache-mode: objects now transports the mbx bundle as a directory instead of a tar when the installed mbx is 1.12.0 or newer, cutting warm-restore import time substantially. No workflow changes are needed, but object-mode caches restore cold once after the switch.

Changed

• Object-mode caches are saved and restored as a directory bundle (#41, @jdx). actions/cache archives whatever path it is given, so wrapping a tar inside it meant every byte was unpacked twice on a warm restore: once by the cache action and again by mbx cache import. The post step now runs mbx cache export --format directory and the importer reads the restored tree in place. On a warm restore of a 4,071-object / 1.4 GiB closure on ubuntu-24.04, mbx cache import dropped from 6.46s to 2.02s; the cache action's own restore got about 1.3s slower because it handles ~5,000 files instead of one archive, for a net saving of roughly 3.1s before the build starts (single-trial measurements). target mode is unchanged.
  • Version-gated. --format directory arrived in mbx 1.12.0 and older binaries reject the flag, so the form follows the version actually installed. Versions below 1.12.0, and anything that does not parse as a version, keep using a tar so exports do not fail.
  • Separate cache keys. A tar entry and a directory entry cannot restore each other. Directory bundles add a -dir suffix to the generation segment of the generated key (for example linux-x64-mbx-v1-dir-rust-<hash>-<sha>), while the tar form keeps the bare generation it has always used, so entries saved before this release still restore for older mbx versions. Workflows that assert on cache-primary-key output should allow for the extra segment.
  • The job summary's Payload row now reports mbx objects (directory) or mbx objects (tar) so you can see which form a run used.

Breaking Changes

• The first object-mode job after the installed mbx crosses 1.12.0 (including version: latest picking it up automatically) restores cold once because the directory bundle uses a new cache key. Warm caches rebuild on the next default-branch save; no configuration change is required.

Full Changelog: v1.3.1...v1.4.0

v1.3.1: Preserve imported objects on hosted runners

A small release. The main change fixes cache eviction that could break object-mode caching on GitHub-hosted runners, plus a documentation cleanup.

Fixed

• Imported objects survive automatic GC on GitHub-hosted runners (#37, @jdx). A restored object bundle can exceed mbx's local disk budget on a GitHub-hosted runner, so automatic garbage collection could evict objects after the first build. That caused later commands to miss the cache and the post-job export to fail with action result is missing. For backend: github with github-cache-mode: objects, the action now defaults MBX_GC_AUTO=0 when RUNNER_ENVIRONMENT is github-hosted and the variable is unset, exporting it before invoking mbx so it applies for the whole job. Explicit MBX_GC_AUTO values are respected, and self-hosted/unknown runners, target mode, and other backends are unchanged. With cleanup disabled the cache can grow for the duration of the job; set MBX_GC_AUTO=1 to keep automatic cleanup, or set MBX_GC_AUTO=0 on a disposable self-hosted runner to opt into the same behavior.

Documentation

• Dropped the CI performance warning (#32, @jdx). Removed the README note advising that mbx does not yet consistently outperform Swatinem/rust-cache on GitHub-hosted runners; the default target payload now measures within noise on paired same-runner trials. The cache-mode section still carries the measured numbers and tradeoffs.

Full Changelog: v1.3.0...v1.3.1

v1.3.0: Warm target-tree caching by default, plus a local backend

This release changes what the GitHub Actions backend caches by default: it now transports Cargo's pruned target tree and registry so restored jobs incremental-compile like a rust-cache-style workflow, with the previous portable objects closure still available behind a new input. It also adds a local filesystem backend and removes the long-deprecated max-size input.

Added

• local backend (#28, @jdx). Set backend: local to install or reuse mbx and keep its store on the filesystem, with no GitHub Actions cache restore/save and no remote transport. Useful on persistent runners or when a volume action mounts mbx's cache directory.

  - uses: jdx/mr-boxington-action@v1
    with:
      backend: local
  - run: mbx test --workspace

• github-cache-mode input (#31, @jdx). Chooses the GitHub cache payload: the new target tree (default) or the portable objects closure. Use objects for workflows whose builds must share across differing target directories or checkout layouts.

  - uses: jdx/mr-boxington-action@v1
    with:
      github-cache-mode: objects
  - run: mbx test --workspace

Changed

• GitHub cache defaults to a warm Cargo target tree (#31, @jdx). The default backend now restores Cargo's pruned target directory and registry from the previous compatible build, so a job that edits a few files recompiles only those crates. Before saving, the post step removes final products and unrelated Cargo state while retaining fingerprints, dependencies, build-script state, and the registry. Full mbx executables used by build-script shims (including legacy hard-linked copies) are stripped from the archive and rehydrated from the installed mbx after restore; tiny launchers and Cargo freshness timestamps stay intact. In target mode the action disables mbx-managed target views and native-link object caching so it transports a single archive. When version pins an exact release, that archive also carries one mbx executable so later warm jobs skip a separate release download. Opt back into the old behavior with github-cache-mode: objects. In paired GitHub-hosted measurements the target payload restored and built a small edit roughly ten seconds faster than objects.

Removed

• max-size input (#30, @jdx). Removed the deprecated input, which has done nothing since the GitHub backend moved to closure-bundle exports. There is no runtime behavior change; a workflow still passing max-size will only get an unexpected-input warning from the runner.

Breaking Changes

• The GitHub backend's default cache payload changed from objects to target, using a distinct cache key, so existing entries will not be reused on the first run after upgrading. Warm caches rebuild automatically on the next default-branch save. To keep the prior behavior, set github-cache-mode: objects.
• The max-size input no longer exists; remove it from workflows to avoid an unexpected-input warning.

Full Changelog: v1.2.0...v1.3.0

v1.2.0: Use mbx from PATH when version is omitted

A small release. The action now reuses an existing mbx on PATH when you leave version unset, only downloading a release when none is found, and it prefers an exported GITHUB_TOKEN for release metadata lookups. The README also gains an honest look at current CI caching performance.

Changed

• version now defaults to using mbx from PATH (#27, @jdx). When version is omitted, the action probes for an existing mbx (via mbx --version) and uses it as-is, downloading the latest release only when nothing is found. Setting version explicitly (including latest) still forces the verified release install path. This avoids reinstalling mbx on runners that already provide it. Version parsing also accepts prerelease and build-metadata formats such as 1.3.1-beta.2+build.4.

  # Reuse mbx already on PATH, fall back to latest if absent
  - uses: jdx/mr-boxington-action@v1
  
  # Always install a specific release
  - uses: jdx/mr-boxington-action@v1
    with:
      version: "0.4.0"

• Release metadata requests prefer GITHUB_TOKEN (#27, @jdx). When a GITHUB_TOKEN is exported in the environment, it is used to resolve mbx release metadata; otherwise the action falls back to the github-token input. Either path still requires contents: read.

Documentation

• Current CI performance disclosure (#23, @jdx). The README now states plainly that mbx does not yet reliably outperform Swatinem/rust-cache on GitHub-hosted runners, publishes warm benchmark comparisons for both the server and GitHub-cache backends, and advises benchmarking your complete job (including restore/import/export overhead) before switching.

Full Changelog: v1.1.0...v1.2.0

v1.1.0: Exact build closures and toolchain-scoped cache keys

This release reworks GitHub Actions caching to store exact mbx build closures instead of the whole local store, scopes generated cache keys by Rust toolchain identity so caches survive compiler bumps, and adds opt-in cache seeding for trusted manual dispatches. It also improves diagnostics when the GitHub cache runtime is unavailable.

Highlights

• Cache keys are now scoped to the exact Rust compiler your build uses, so a runner-image toolchain rollout no longer silently discards a warm cache. A new toolchain input lets you point the key at the toolchain your build names directly.
• GitHub cache saves now upload a single portable build closure bundle rather than the whole store, cutting payload size substantially (measured at ~48% fewer uncompressed bytes on a real project after one historical revision accumulated).

Added

• Toolchain-scoped cache keys (#16, @jdx). Generated primary keys and restore prefixes now carry a rust-<sha256(rustc -vV)[..12]> segment (${platform}-${architecture}-mbx-${generation}-${toolchain}-${commit}), giving each toolchain its own cache entry. This fixes warm caches reporting zero hits after a runner image bumps its preinstalled Rust. Runners with no rustc on PATH fall back to the literal norust and log guidance to install the toolchain before this action.
• toolchain input (#17, @jdx). Tell the action which toolchain your build uses so the key follows that compiler instead of whatever rustc on PATH resolves to. Useful when a build invokes a specific toolchain on its own command line:

  - uses: jdx/mr-boxington-action@v1
    with:
      toolchain: "1.91"
  - run: mbx +1.91 check --workspace

  Either 1.91 or +1.91 works. The input scopes the key only; it does not install or select a toolchain. Leaving it unset keeps the bare rustc -vV probe so rust-toolchain.toml overrides are still honored.
• save-on-workflow-dispatch input (#18, @jdx). Off by default. When enabled, trusted manual workflow_dispatch runs may write the cache (including from non-default branches), letting benchmark and seeding workflows warm a fresh cache generation. Pull requests and non-default-branch pushes remain restore-only.
• cache-links input (#15, @jdx). Controls native link caching via MBX_CACHE_LINKS. Defaults to auto, which enables it only on Linux; set true/false to force it on other platforms. A controlled warm Linux build fell from 124.7s to 84.9s (~32% faster) in benchmarking.

Changed

• GitHub cache stores exact build closures (#20, @jdx). Instead of archiving the entire local store, each job is assigned a unique MBX_CACHE_EXPORT_GROUP, restores a single portable bundle via mbx cache import, and exports its deduplicated closure in the post step. Jobs that never completed an mbx build skip the save while real export failures still surface. Requires mbx 1.1.0 or newer. The new cache path uses a distinct GitHub cache version, so existing whole-store entries are not misread as bundles.
• Rolling keys for saving dispatches (#19, @jdx). Because GitHub cache entries are immutable, opted-in workflow_dispatch runs now receive a fresh primary key per run/attempt while still restoring from the compatible generation prefix, so repeated dispatches progressively warm the cache. Push, pull-request, and restore-only key behavior is unchanged.

Fixed

• Clearer diagnostics for an unavailable GitHub cache runtime (#22, @jdx). The action now validates runner-injected cache credentials (both cache service v1 and v2) before installing mbx and fails early with an explicit message, instead of proceeding and later reporting a misleading No mbx cache found. Running the bundle outside a uses: action step is now reported distinctly from an ordinary cache miss.

Deprecated

• max-size (#20, @jdx). It no longer applies now that the cached payload is the exact action closure and is ignored for closure exports.

Full Changelog: v1.0.1...v1.1.0