Skip to content
Documentation

Docs / Adapter commands / Maven

Maven adapter

Keep Maven's build-cache extension and normal build phases. The adapter supplies the remote endpoint, write policy, and any missing default configuration.

Command
boringcache maven
Protocol
Maven build cache extension over /v1.1/* and /v1/*
Action
mode: maven

How the adapter works

Maven-native cache records

BoringCache does not guess Maven outputs. The build cache extension still decides what can be reused.

Shared trust boundaries

Use restore-only and save tokens instead of giving every job the same write access.

One place to inspect

Maven cache traffic lands in the same workspace reporting as the rest of the build.

Set up Maven

Keep the command and cache tag in .boringcache.toml, then use the same boringcache maven entrypoint locally and in CI. The adapter adds missing cache configuration without rewriting files already in your project.

[adapters.maven]
tag = "maven-cache"
command = ["mvn", "verify", "--batch-mode", "-ntp"]

# Run: boringcache maven

Before the first run

  • Prefer the project's Maven wrapper when it is present.
  • Keep any existing build-cache extension and cache configuration; the adapter preserves both.
  • Resolve unreadable or conflicting extension XML instead of asking the adapter to rewrite it.

Maven modules

What is recorded

With the build cache extension enabled, Maven writes a cache report under target/maven-incremental when a build ends. The CLI reads the report the command wrote; it adds nothing to the Maven command.

The run page and the run API list every module the build cache considered: whether Maven built it or restored it from the local or remote cache, and the module's input checksum. Maven's report has no per-module timing, so none is shown.

Every request Maven makes to the cache is recorded too, with its result, size and time.

Commands without modules

Maven writes the report in the directory of the -f or --file POM, or in the working directory. A command run through another program from a different directory, or a build with the build cache disabled, records only the cache requests.

Use the same adapter in GitHub Actions

The Action prepares the Maven extension and cache configuration, then gives the later Maven command the settings it needs.

.github/workflows/ci.yml
- uses: boringcache/one@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  with:
    trust-policy: auto
    mode: maven

- run: ./mvnw verify

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

GitHub Actions reference

Benchmarks

Spring AI builds the same upstream commits with BoringCache, Depot Cache and GHA Cache on the same runner classes.

Spring AI

Maven

Benchmark →

Spring framework modules for AI applications.

Average restore, build and save · lower is better

GitHub runner

4 vCPU · 16 GB · Ubuntu 24.04 x86-64

BoringCache
4 min 2 s 17 builds
Depot Cache
5 min 37 s 17 builds
GHA Cache
4 min 15 s 17 builds
Same CPU model

Builds of one commit can land on different CPU models. These ratios use only the build pairs where both caches ran on the same model; above 1.00× means BoringCache's total time over those pairs was lower.

Depot Cache vs BoringCache
1.30× · 7 of 17
GHA Cache vs BoringCache
0.99× · 4 of 17
5 CPU models recorded
BoringCache · Build cache
AMD EPYC 7763 (8 builds) · AMD EPYC 9V45 (5 builds) · Intel Xeon Platinum 8573C (3 builds) · AMD EPYC 9V74 (1 build)
Depot Cache
AMD EPYC 7763 (11 builds) · AMD EPYC 9V74 (4 builds) · Intel Xeon Platinum 8573C (1 build) · AMD EPYC 9V45 (1 build)
GHA Cache · Local cache directory restored and saved by actions/cache
AMD EPYC 7763 (9 builds) · AMD EPYC 9V45 (5 builds) · AMD EPYC 9V74 (2 builds) · Intel Xeon 6973P-C (1 build)
Cold and warm builds

Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.

One cold and warm build per cache
Cache Cold Warm CPU
BoringCache Build cache 8 min 23 s 42.0 s Cold: AMD EPYC 7763 · Warm: Intel Xeon Platinum 8370C
Depot Cache 10 min 58 s 3 min 23 s AMD EPYC 9V74 Different CPU
GHA Cache Local cache directory restored and saved by actions/cache 8 min 16 s 8 min 2 s AMD EPYC 7763 Different CPU

Cache hits

BoringCache · GitHub runner · 4 vCPU

74.9% of 6,472 lookups over 17 builds

Served from the runner
Under 1 ms per read
Read from cache
1.88 GB

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

Compare every supported command, protocol, and Action mode in one place.

Adapter command index →

Need help or found something unclear? Open an issue or browse the CLI repo.