Getting Started

What this action does

This action speeds up JVM builds on CI by caching the build tool’s local artifact store between runs. On each run it:

1. Restores the cache before the build so the build tool finds its dependencies already in place.
2. Publishes a new complete immutable cache generation after a material change. Unchanged hits do not create duplicate entries.

Two job modes are available for both build tools:

• Single-job — one build job per workflow run. The action wraps that job and handles everything automatically.
• Distributed multi-job — multiple parallel build jobs. Each job uploads only the delta it produced; a dedicated aggregator job merges all deltas into the next cache entry so no job’s work is lost.

Gradle

For Gradle the action caches GRADLE_USER_HOME and additionally:

• Provisions any missing gradle-wrapper.jar files, verifying each one with a SHA-256 checksum and a PGP signature before writing it to disk. See Security for details.

Maven

For Maven the action caches the Maven user home (~/.m2 by default, or the path set by maven-user-home), including the local repository under repository/ and Maven Wrapper downloads under wrapper/dists/. No wrapper provisioning is performed — Maven’s own bootstrap is handled by the runner environment or actions/setup-java.

Planned workflow shape

The examples below document the intended action contract. The current source tree omits the generated dist/ bundles required by GitHub Actions, so no current source ref can be used with these snippets. Once the project publishes a reviewed materialized ref, pin that exact immutable ref and place the action step before your build invocation.

Cache and same-run delta artifact operations use job-scoped Actions runtime credentials, so they do not require actions: write. The examples grant only contents: read for checkout. See Security for the full permissions boundary.

The action defaults to read-only on pull_request and pull_request_target events, so cache writes from untrusted forks are automatically suppressed. Repository config can make this policy stricter but cannot lower the pull-request floor; only a direct workflow input can do that. Distributed read-only workers upload nothing, and read-only aggregators perform no artifact exchange.

Gradle

 1jobs:
 2  build:
 3    runs-on: ubuntu-latest
 4    permissions:
 5      contents: read
 6    steps:
 7      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
 8      - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654
 9        with:
10          distribution: temurin
11          java-version: '21'
12      - uses: buildish-tooling/buildish-mammoth-cache/actions/github/gradle@<materialized-ref>
13      - run: ./gradlew build

Maven

 1jobs:
 2  build:
 3    runs-on: ubuntu-latest
 4    permissions:
 5      contents: read
 6    steps:
 7      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
 8      - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654
 9        with:
10          distribution: temurin
11          java-version: '21'
12      - uses: buildish-tooling/buildish-mammoth-cache/actions/github/maven@<materialized-ref>
13      - run: mvn verify

How it works

The action runs twice per job: a prepare step before the build and a finalize step after. This two-phase structure is what makes precise, non-invasive caching possible — the action snapshots the build tool’s cache directory before the build, snapshots it again after, and saves only the difference without interfering while the build runs.

sequenceDiagram
    participant P as prepare
    participant B as Your build steps
    participant F as finalize

    P->>P: restore cache
    note over P: Gradle only: provision gradle-wrapper.jar
    P->>P: snapshot cache directory (pre-build)
    P-->>B: hand off
    B->>B: build runs …
    B-->>F: job post step
    F->>F: snapshot cache directory (post-build)
    F->>F: compare material state (post − pre)
    F->>F: publish complete generation if required

For distributed multi-job builds, worker jobs upload their delta as a workflow artifact instead of saving the cache directly. An aggregator job then merges all worker deltas into a single cache entry. See Distributed multi-job for details.