rust-cache: honor CARGO_HOME and add a restore-only save toggle

The cached paths were hardcoded to $HOME/.cargo, so a container image that bakes the toolchain elsewhere (e.g. /opt/cargo via CARGO_HOME) cached a directory cargo never touches.
The new save input (default true) switches the inner step to the restore-only variant of actions/cache — for PR jobs that consume a cache a default-branch warmup job maintains.
Selftests cover both: a sentinel round-trips through a custom CARGO_HOME, and a save:false run leaves no cache entry behind.

Author: gronke

.github/actions/rust-cache/action.yml

@@ -14,6 +14,13 @@ inputs:
     description: Cache-family name, so independent jobs (build, tauri, …) keep separate caches.
     required: false
     default: rust
+  save:
+    description: >-
+      Also save the cache at job end (the actions/cache post step). Set "false" for restore-only
+      consumers — e.g. PR jobs reading a cache that a default-branch warmup job maintains, where
+      per-branch saves would only burn quota and job minutes.
+    required: false
+    default: "true"
   cache-target:
     description: >-
       Also cache the build target/ directory (keeps compiled dependencies between runs). Off by
@@ -66,12 +73,15 @@ runs:
 
         # Cache cargo's DOWNLOAD cache — registry index + .crate tarballs + git db. Never
         # registry/src: cargo re-extracts it from the tarballs, so caching it is pure duplication
-        # (it roughly doubles the registry footprint for no benefit).
+        # (it roughly doubles the registry footprint for no benefit). The cargo home comes from
+        # CARGO_HOME when set — container images that bake the toolchain elsewhere (e.g.
+        # /opt/cargo) rely on it, and $HOME/.cargo would cache a directory cargo never touches.
+        CARGO_DIR="${CARGO_HOME:-$HOME/.cargo}"
         {
           echo 'paths<<__PATHS__'
-          echo "$HOME/.cargo/registry/index"
-          echo "$HOME/.cargo/registry/cache"
-          echo "$HOME/.cargo/git/db"
+          echo "$CARGO_DIR/registry/index"
+          echo "$CARGO_DIR/registry/cache"
+          echo "$CARGO_DIR/git/db"
           if [ "$CACHE_TARGET" = "true" ]; then echo "$TARGET_DIR"; fi
           if [ -n "$EXTRA_DIRS" ]; then printf '%s\n' "$EXTRA_DIRS"; fi
           echo '__PATHS__'
@@ -80,11 +90,23 @@ runs:
     # actions/cache restores here and auto-saves at job end (its post step runs even when nested in a
     # composite action). An exact-key save is skipped on a hit, so an unchanged Cargo.lock never grows
     # the cache; a changed lock seeds a fresh entry and the stale one is LRU-evicted — no ratchet.
+    # `save: "false"` swaps in the restore-only variant of the same first-party action.
     - name: Cache cargo registry/git (+ target)
+      if: inputs.save == 'true'
       uses: actions/cache@v5
       with:
         path: ${{ steps.meta.outputs.paths }}
         key: ${{ inputs.prefix }}-${{ runner.os }}-rust-${{ steps.meta.outputs.rust }}-${{ hashFiles(inputs.lockfiles) }}
         restore-keys: |
           ${{ inputs.prefix }}-${{ runner.os }}-rust-${{ steps.meta.outputs.rust }}-
           ${{ inputs.prefix }}-${{ runner.os }}-rust-
+
+    - name: Restore cargo registry/git (+ target) without saving
+      if: inputs.save != 'true'
+      uses: actions/cache/restore@v5
+      with:
+        path: ${{ steps.meta.outputs.paths }}
+        key: ${{ inputs.prefix }}-${{ runner.os }}-rust-${{ steps.meta.outputs.rust }}-${{ hashFiles(inputs.lockfiles) }}
+        restore-keys: |
+          ${{ inputs.prefix }}-${{ runner.os }}-rust-${{ steps.meta.outputs.rust }}-
+          ${{ inputs.prefix }}-${{ runner.os }}-rust-

.github/workflows/selftest.yml

@@ -417,3 +417,64 @@ jobs:
           prefix: passthrough
       - name: explicit CARGO_INCREMENTAL is preserved
         run: test "$CARGO_INCREMENTAL" = "1"
+
+  # rust-cache must resolve the cargo home from CARGO_HOME (container images bake the
+  # toolchain outside $HOME/.cargo): seed a sentinel under a custom CARGO_HOME, let the
+  # post step save it, and prove a second job restores it into the same custom location.
+  selftest-cache-cargo-home-save:
+    name: rust-cache honors CARGO_HOME (save)
+    runs-on: ubuntu-latest
+    env:
+      CARGO_HOME: ${{ runner.temp }}/cargo-home
+    steps:
+      - uses: actions/checkout@v6
+      - name: seed a sentinel in the custom cargo home
+        run: |
+          mkdir -p "$CARGO_HOME/registry/index" "$CARGO_HOME/registry/cache" "$CARGO_HOME/git/db"
+          echo "${{ github.run_id }}" > "$CARGO_HOME/registry/cache/selftest-sentinel"
+      - uses: ./.github/actions/rust-cache
+        with:
+          prefix: cargohome-${{ github.run_id }}
+
+  selftest-cache-cargo-home-restore:
+    name: rust-cache honors CARGO_HOME (restore)
+    needs: selftest-cache-cargo-home-save
+    runs-on: ubuntu-latest
+    env:
+      CARGO_HOME: ${{ runner.temp }}/cargo-home
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/rust-cache
+        with:
+          prefix: cargohome-${{ github.run_id }}
+          save: "false"
+      - name: sentinel came back into the custom cargo home
+        run: test "$(cat "$CARGO_HOME/registry/cache/selftest-sentinel")" = "${{ github.run_id }}"
+
+  # save:"false" must not create a cache entry: run restore-only under a unique prefix,
+  # then assert no entry with that prefix exists.
+  selftest-cache-no-save:
+    name: rust-cache save:false saves nothing
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/rust-cache
+        with:
+          prefix: nosave-${{ github.run_id }}
+          save: "false"
+
+  selftest-cache-no-save-assert:
+    name: rust-cache save:false left no entry
+    needs: selftest-cache-no-save
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      - name: no cache entry exists for the nosave prefix
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          COUNT=$(gh cache list --repo ${{ github.repository }} --limit 100 --json key \
+            --jq '[.[] | select(.key | startswith("nosave-${{ github.run_id }}-"))] | length')
+          test "$COUNT" -eq 0

README.md

@@ -53,15 +53,19 @@ A crate with `publish = false` is validated for tag/version coherence only, so t
 Caches cargo for CI and **defaults** incremental compilation off — pure cost in CI (no edit→recompile loop), and the main thing that balloons `target/`.
 An explicit `CARGO_INCREMENTAL` (set at the workflow/job level) is obeyed — for the occasional variant build that is faster with it on — and flows through to the Docker actions via their `CARGO_.*` forwarding. The action imposes no build profile; set `CARGO_*` vars to tune the build.
 Caches the cargo download cache (registry index + `.crate` tarballs + git db) via the first-party `actions/cache`; optionally caches `target/` too, kept bounded by the `Cargo.lock` key (no restore-key ratchet).
+The cargo home is resolved from `CARGO_HOME` when set — container images that bake the toolchain outside `$HOME/.cargo` (e.g. `/opt/cargo`) are cached correctly.
 Place it before your build/test steps.
 
 ```yaml
 - uses: gronke/rust-ci/.github/actions/rust-cache@main
   with:
     prefix: build            # cache family — use a distinct one per job
     cache-target: "true"     # also cache target/ (off by default)
+    # save: "false"          # restore-only, for jobs consuming a warmup-maintained cache
 ```
 
+`save: "false"` restores without writing a cache at job end — for PR jobs that read a cache a default-branch warmup job maintains, where per-branch saves would only burn quota and job minutes.
+
 ### `build-image`
 
 Builds the toolchain image — `rust:<version>` plus clippy, rustfmt, and jq — locally and loads it into the Docker daemon, so the Docker actions below run against a local `rust-ci:latest` tag with no registry.