Configuration Reference

The action is available in two build-tool-specific variants that share most inputs:

• Gradle — buildish-tooling/buildish-mammoth-cache/actions/github/gradle@<sha>
• Maven — buildish-tooling/buildish-mammoth-cache/actions/github/maven@<sha>

All inputs described in Common inputs apply to both. Inputs described under Gradle-only inputs or Maven-only inputs are accepted only by the corresponding action and ignored (or rejected) by the other.

The following compact matrix is generated from the typed public contract. The detailed sections below add examples and rationale; the parity test ensures metadata, readers, config-file keys, runtime outputs, and these reference rows cannot silently diverge.

Canonical input matrix

Canonical output matrix

Common inputs

config-file

• Default: unset
• Optional workspace-relative .json, .yml, or .yaml file containing a top-level object.
• Config-file keys use the same kebab-case names as the action inputs.
• Direct action inputs override values loaded from the file.
• dependent-jobs and wrapper-properties-files may be either strings or arrays in the file.
• cache-partitions may be expressed as a native YAML/JSON array in the file instead of a serialized JSON string.
• github-token is intentionally rejected in config files; pass secrets directly via action inputs or environment variables.
• The resolved file must remain inside the workspace after symlink resolution.

base-directory

• Default: .
• Repository-relative base directory for wrapper discovery and other project-relative paths.
• Windows-style relative paths using \ are accepted and normalized to internal POSIX-style paths.
• Absolute/rooted paths are rejected, including C:\repo, \Windows\System32, and \\server\share.
• Must remain inside the repository workspace.

cache-enabled

• Default: true
• Accepted values: true, false
• Enables or disables cache orchestration.

read-only

• Default: event-dependent
• Accepted values: true, false
• Defaults to true for pull_request / pull_request_target.
• Defaults to false for other events.
• A repository config file may set true, but cannot set false to lower the pull-request safety floor. Only a direct workflow input can make that explicit trusted-workflow choice.
• Use this to prevent cache mutation.

job-mode

• Default: standalone
• Supported values:
  • standalone
  • distributed-worker
  • distributed-aggregator
• Controls cache coordination behavior.

dependent-jobs

• Default: empty
• Comma- or newline-separated job names.
• Only valid with distributed job modes.

cache-key-prefix

• Default: buildish-mammoth-cache-
• Must start with an alphanumeric character.
• Remaining characters may only be letters, numbers, ., _, or -.
• Changes only the namespace prefix. The action always appends build tool, schema, Java, runner, partition, ref-lineage, and immutable-generation identity.

cache-partitions

• Default: empty
• Optional JSON array of cache partition overrides and custom partitions.
• In config-file, this may also be a native YAML/JSON array instead of a serialized string.
• Each object must contain:
  • id: lowercase letters, numbers, and - only
  • includes: array of cache-root-relative include globs
  • excludes: optional array of cache-root-relative exclude globs
• Overriding a built-in partition replaces its built-in include/exclude lists.
• Setting includes: [] disables a built-in partition.
• Custom partitions must have at least one include glob.
• Hard safety excludes are always enforced even when a partition is overridden.

cleanup-enabled

• Default: true
• Accepted values: true, false
• Enables restore cleanup and timestamp garbage collection. When false, both are skipped even if their individual modes request cleanup.

cache-gc-mode

• Default: timestamp
• Supported values: off, timestamp
• Controls best-effort garbage collection of managed cache files before standalone or distributed-aggregator jobs save the base cache.
• timestamp deletes a managed file only when both its modification time and effective access time are older than cache-gc-older-than-days.
• Effective access time is evaluated conservatively as the newer of access time and modification time.
• Set off when jobs must retain rarely used old cache entries, for example offline-style builds that cannot redownload pruned dependencies.

cache-gc-older-than-days

• Default: 14
• Minimum: 2
• Age threshold for cache-gc-mode: timestamp.
• The minimum is intentionally above 24 hours because common runner filesystems may defer or coalesce access-time updates.
• Increase this value if your Gradle or Maven build uses a large dependency set with artifacts that are valid but touched infrequently.

restore-cleanup-mode

• Default: none
• Supported values: none, prune-managed
• prune-managed only acts after a base-cache hit.
• It deletes files currently matched by the active managed partitions, then restores the matched base cache again.
• It never deletes files outside the action-managed partition space.
• It is intentionally an opt-in because it is more destructive and may increase restore time.

allow-duplicate-dependent-delta-paths

• Default: false
• Accepted values: true, false
• When true, the aggregator resolves non-identical overlapping worker paths by newest modification time.
• Exact same-content overlaps merge safely without this option.
• When false, non-identical path conflicts are errors.
• Only relevant for distributed aggregator jobs.

github-token

• Default: unset (falls back to GITHUB_TOKEN when available)
• Used for authenticated requests to the configured GitHub API host. The Gradle action uses these headers for authenticated wrapper downloads; provider integrations may also use them.
• Direct-only: config files reject this secret-bearing input.
• Never written to summaries or persisted post-action state.

github-event-name

• Default: unset (the action reads GITHUB_EVENT_NAME from the runner environment)
• Reusable workflows only. When a workflow is triggered via workflow_call, GitHub sets GITHUB_EVENT_NAME to workflow_call rather than the original caller’s event name. Pass ${{ github.event_name }} from the caller workflow to restore the correct value.
• Affects isPullRequest detection and the default read-only behavior on pull-request events.
• Example:

  1github-event-name: ${{ github.event_name }}
  

github-job-name

• Default: unset (the action reads GITHUB_JOB from the runner environment)
• Reusable workflows and matrix jobs. Assigns a stable, predictable job name for cache coordination and artifact naming, independent of the GitHub Actions job key or matrix label.
• Example:

  1github-job-name: aggregator
  

github-ref-name

• Default: unset (the action resolves the ref name from GITHUB_REF_NAME, GITHUB_REF, and the event payload)
• Reusable workflows only. When a workflow is triggered via workflow_call, the ref context visible inside the reusable workflow may differ from the caller’s. Pass the resolved ref name from the caller workflow to ensure cache keys use the correct branch or tag.
• Example:

  1github-ref-name: ${{ github.ref_name }}
  

github-default-branch

• Default: unset (the action reads the default branch from the event payload or GITHUB_DEFAULT_BRANCH)
• Reusable workflows only. Pass the caller’s default branch so that cache key fallbacks target the correct base branch.
• Example:

  1github-default-branch: ${{ github.event.repository.default_branch }}
  

Outputs

Both actions expose the same cache lifecycle outputs after prepare:

Generation keys are finalize outcomes and are intentionally not planned prepare outputs. The job summary and finalize log report the exact key only after a successful publication.

Gradle-only inputs

process-all-wrapper-files

• Default: false
• Accepted values: true, false
• Scans for every matching wrapper properties file under base-directory.
• Cannot be combined with wrapper-properties-files.

wrapper-properties-glob

• Default: **/gradle/wrapper/gradle-wrapper.properties
• Repository-relative discovery glob used beneath base-directory.
• Windows-style relative paths using \ are accepted and normalized before evaluation.
• Absolute/rooted paths are rejected, including drive-prefixed, rooted, and UNC paths.

wrapper-properties-files

• Default: empty
• Comma- or newline-separated explicit gradle-wrapper.properties files.
• Paths are relative to base-directory.
• Windows-style relative paths using \ are accepted and normalized to internal POSIX-style paths.
• Absolute/rooted paths are rejected, including drive-prefixed, rooted, and UNC paths.
• Entries must be explicit file paths, not globs.

gradle-user-home

• Default: $GRADLE_USER_HOME when set, otherwise $HOME/.gradle
• In v1, only the default Gradle user home is supported. Non-default values fail validation intentionally.

setup-java

• Default: false
• Reserved compatibility flag. In v1, setting true fails intentionally.
• Run actions/setup-java before this action instead.

Maven-only inputs

maven-user-home

• Default: $MAVEN_USER_HOME when set, otherwise $HOME/.m2
• Accepts an absolute path or a path resolved from the action process working directory.
• The managed root contains both the Maven local repository at repository/ and Maven Wrapper distributions at wrapper/dists/; do not pass the repository/ directory itself.
• Operators are responsible for ensuring a custom user home contains only intended Maven cache state and is not shared across trust zones.

Distributed mode wiring example

The snippets below show the minimum input wiring needed to connect two worker jobs to an aggregator. The github-job-name input gives each job a stable, human-readable name that is independent of matrix labeling; the aggregator’s dependent-jobs must list exactly those names.

See Distributed Multi-Job Builds for a full explanation of how the delta exchange works and for additional configuration options.

Gradle

 1jobs:
 2  worker-a:
 3    runs-on: ubuntu-latest
 4    permissions:
 5      contents: read
 6    steps:
 7      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
 8      - uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165
 9        with: { distribution: temurin, java-version: '21' }
10      - uses: buildish-tooling/buildish-mammoth-cache/actions/github/gradle@<commit-sha>
11        with:
12          job-mode: distributed-worker
13          github-job-name: worker-a # stable name used by the aggregator
14          cache-key-prefix: my-project-gradle-
15      - run: ./gradlew :module-a:build
16
17  worker-b:
18    runs-on: ubuntu-latest
19    permissions:
20      contents: read
21    steps:
22      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
23      - uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165
24        with: { distribution: temurin, java-version: '21' }
25      - uses: buildish-tooling/buildish-mammoth-cache/actions/github/gradle@<commit-sha>
26        with:
27          job-mode: distributed-worker
28          github-job-name: worker-b
29          cache-key-prefix: my-project-gradle-
30      - run: ./gradlew :module-b:build
31
32  aggregator:
33    needs: [worker-a, worker-b]
34    if: ${{ always() && github.event_name != 'pull_request' && github.event_name != 'pull_request_target' }}
35    runs-on: ubuntu-latest
36    permissions:
37      contents: read
38    steps:
39      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
40      - uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165
41        with: { distribution: temurin, java-version: '21' }
42      - uses: buildish-tooling/buildish-mammoth-cache/actions/github/gradle@<commit-sha>
43        with:
44          job-mode: distributed-aggregator
45          dependent-jobs: worker-a, worker-b # must match github-job-name on each worker
46          github-job-name: aggregator
47          cache-key-prefix: my-project-gradle-

Maven

 1jobs:
 2  worker-a:
 3    runs-on: ubuntu-latest
 4    permissions:
 5      contents: read
 6    steps:
 7      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
 8      - uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165
 9        with: { distribution: temurin, java-version: '21' }
10      - uses: buildish-tooling/buildish-mammoth-cache/actions/github/maven@<commit-sha>
11        with:
12          job-mode: distributed-worker
13          github-job-name: worker-a
14          cache-key-prefix: my-project-maven-
15      - run: mvn -pl module-a verify
16
17  worker-b:
18    runs-on: ubuntu-latest
19    permissions:
20      contents: read
21    steps:
22      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
23      - uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165
24        with: { distribution: temurin, java-version: '21' }
25      - uses: buildish-tooling/buildish-mammoth-cache/actions/github/maven@<commit-sha>
26        with:
27          job-mode: distributed-worker
28          github-job-name: worker-b
29          cache-key-prefix: my-project-maven-
30      - run: mvn -pl module-b verify
31
32  aggregator:
33    needs: [worker-a, worker-b]
34    if: ${{ always() && github.event_name != 'pull_request' && github.event_name != 'pull_request_target' }}
35    runs-on: ubuntu-latest
36    permissions:
37      contents: read
38    steps:
39      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
40      - uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165
41        with: { distribution: temurin, java-version: '21' }
42      - uses: buildish-tooling/buildish-mammoth-cache/actions/github/maven@<commit-sha>
43        with:
44          job-mode: distributed-aggregator
45          dependent-jobs: worker-a, worker-b
46          github-job-name: aggregator
47          cache-key-prefix: my-project-maven-