Choosing a Bitbucket Pipelines Cache for Faster Java Maven Builds

Problem and Takeaway

When a Bitbucket Pipelines build spends minutes downloading Maven dependencies, you waste pipeline minutes and hit storage limits faster. The useful takeaway is that caching the Maven local repository (~/.m2) usually gives the best balance of speed, storage impact, and setup effort for Java projects.

Decision Constraints

Choose a caching mechanism that fits these limits:

• Pipeline minute quota – reduce time spent in mvn dependency:resolve.
• Per‑repository cache storage – Bitbucket Cloud caps the cache at 1 GB.
• Reproducible, secure builds – avoid caching secrets or non‑deterministic artifacts.

Option Comparison

Option	What is cached	Typical hit‑rate	Storage impact	Setup complexity
Docker layer cache	Image layers from services (e.g., maven:3‑jdk‑11)	60‑80 %	Medium (layers stored per repo)	Low (add services with cache)
Artifact cache	~/.m2 directory (Maven local repo)	70‑90 %	Low‑Medium (dependencies only)	Medium (define caches path)
Custom script cache	Arbitrary files (e.g., node_modules, Gradle)	Variable	Depends on data size	High (manual save/restore)

Implementing the Artifact Cache

Add a caches entry that points to the Maven local repository. This works with the default maven keyword, which maps to ~/.m2.

image: maven:3.9-jdk-11
pipelines:
  default:
    - step:
        caches:
          - maven
        script:
          - mvn -B verify

To apply the change:

Clone the repository (requires read access).
Edit bitbucket-pipelines.yml in the root directory.
Commit and push the file (requires write permission on the repo).
Push to the branch that triggers pipelines (e.g., git push origin main).

Validating the Cache
After the push, open the pipeline run in Bitbucket and look for the Cache section in the log:

The log will show something like Restoring cache... followed by Cache hit: 78% and the size used.
A miss on the first run is expected; subsequent runs should show a hit ratio above 60 %.

To confirm a real time saving:

Run the pipeline three times with caching enabled and record the total duration (shown in the pipeline summary).
Disable the cache by temporarily removing the caches block, run three more builds, and record those durations.
Compare the averages; a steady 20‑40 % reduction indicates the cache is effective.

Limitations and Practical Checks

Bitbucket Cloud limits repository cache to 1 GB; exceeding this triggers eviction and may lengthen builds. Check usage in Repository settings → Pipelines → Cache usage.
Cached data is not encrypted at rest; never store settings.xml with server passwords or API keys in ~/.m2.
When you change dependency versions, the cache may still serve old artifacts. To force a refresh, delete the cache from the repository settings or bump a cache key (e.g., add a custom caches entry with a key based on the checksum of pom.xml).
Practical verification: after each build, view the pipeline log for the Cache entry and note the hit ratio and used size. If the ratio stays below 40 % or the size approaches the 1 GB limit, revisit what is being cached.