We use cookies to understand how people use Depot.
Depot
Sign InGet started
Cache

Maven

Maven is a build automation and project management tool primarily used for Java projects that helps developers manage dependencies, build processes, and documentation in a centralized way. It follows a convention-over-configuration approach by providing a standard project structure and build lifecycle, allowing teams to quickly begin development without extensive configuration.

Depot Cache provides a remote cache service that can be used with Maven, allowing you to incrementally cache and reuse parts of your builds. This cache is accessible from anywhere, both on your local machine and on CI/CD systems.

Configuring Maven to use Depot Cache

Depot Cache can be used with Maven from Depot's managed GitHub Actions runners, your local machine, any CI/CD system, or within containerized builds using Dockerfiles or Bake files.

From Depot-managed Actions runners

Depot GitHub Actions runners are pre-configured to use Depot Cache with Maven - each runner is launched with a settings.xml file that is pre-populated with the connection details for Depot Cache. You must verify that remote caching is enabled via the Maven Build Cache extension in .mvn/maven-build-cache-config.xml:

<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd">
    <configuration>
        <enabled>true</enabled>
        <hashAlgorithm>SHA-256</hashAlgorithm>
        <validateXml>true</validateXml>
        <remote enabled="true" saveToRemote="true" id="depot-cache">
            <url>https://cache.depot.dev</url>
        </remote>
        <projectVersioning adjustMetaInf="true" />
    </configuration>
</cache>

It is important to note that the id of your remote cache must be set to depot-cache for the Depot Cache service to work correctly in Depot GitHub Actions Runners. The cache will not be used if you use a different ID.

You should also verify that you have registered the Build Cache extension in your pom.xml file:

<build>
    <extensions>
        <extension>
            <groupId>org.apache.maven.extensions</groupId>
            <artifactId>maven-build-cache-extension</artifactId>
            <version>1.0.1</version>
        </extension>
    </extensions>
</build>

If you don't want Depot to override the Maven configuration files on each runner, disable Allow Actions jobs to automatically connect to Depot Cache in your organization settings page. You can manually configure Maven to use Depot Cache as described in the "Using Depot Cache from your local machine or any CI/CD system" section.

Using Depot Cache with Maven in depot/build-push-action

When using depot/build-push-action to build Docker images that contain Maven projects, your build needs access to Maven's remote cache credentials to benefit from caching.

These credentials are not automatically available inside your Docker build environment. Unlike builds running directly on Depot-managed GitHub Actions runners (which have automatic access to Depot Cache environment variables), containerized builds execute in isolated VMs that require explicit configuration.

Follow these steps to securely pass your Maven credentials into your Docker build:

  1. Store the Depot token in a GitHub Secret named DEPOT_TOKEN.

  2. Configure Maven Build Cache extension in .mvn/maven-build-cache-config.xml:

<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd">
    <configuration>
        <enabled>true</enabled>
        <hashAlgorithm>SHA-256</hashAlgorithm>
        <validateXml>true</validateXml>
        <remote enabled="true" saveToRemote="true" id="depot-cache">
            <url>https://cache.depot.dev</url>
        </remote>
        <projectVersioning adjustMetaInf="true" />
    </configuration>
</cache>
  1. Update your settings.xml to read the Depot token from an environment variable. Create or update .m2/settings.xml:
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>depot-cache</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer ${env.DEPOT_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>
  1. Configure your GitHub Action to pass secrets to the container build:
- name: Build and push
  uses: depot/build-push-action@v1
  with:
    context: .
    file: ./Dockerfile
    push: true
    tags: your-image:tag
    secrets: |
      "DEPOT_TOKEN=${{ secrets.DEPOT_TOKEN }}"
  1. Update your Dockerfile to copy configuration files and run the build with mounted secret:
# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Copy Maven configuration files
COPY .mvn/maven-build-cache-config.xml .mvn/maven-build-cache-config.xml
COPY .m2/settings.xml /root/.m2/settings.xml

# Run build with mounted secret
RUN --mount=type=secret,id=DEPOT_TOKEN,env=DEPOT_TOKEN \
    mvn clean install

Adding # syntax=docker/dockerfile:1 as the first line of your Dockerfile enables mounting secrets as environment variables.

Using Depot Cache from your local machine or any CI/CD system

To manually configure Maven to use Depot Cache, you will need to configure remote caching in your ~/.m2/settings.xml file. Configure Maven to use the Depot Cache service endpoints and set your API token where there is the DEPOT_TOKEN below:

settings.xml:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>depot-cache</id>
                <configuration>
                    <httpHeaders>
                        <property>
                            <name>Authorization</name>
                            <value>Bearer DEPOT_TOKEN</value>
                        </property>
                    </httpHeaders>
                </configuration>
        </server>
    </servers>
</settings>

Note: Maven support currently only supports Depot Organization API tokens, not user tokens.

After Maven is configured to use Depot Cache, you can run your builds as usual. Maven will automatically communicate with Depot Cache to fetch and reuse any stored build artifacts from your previous builds.

Using Depot Cache with Maven in Depot CLI

When building directly with Depot CLI, follow these steps:

  1. Configure Maven Build Cache extension in .mvn/maven-build-cache-config.xml:
<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd">
    <configuration>
        <enabled>true</enabled>
        <hashAlgorithm>SHA-256</hashAlgorithm>
        <validateXml>true</validateXml>
        <remote enabled="true" saveToRemote="true" id="depot-cache">
            <url>https://cache.depot.dev</url>
        </remote>
        <projectVersioning adjustMetaInf="true" />
    </configuration>
</cache>
  1. Update your settings.xml to read the Depot token from an environment variable. Create or update .m2/settings.xml:
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>depot-cache</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer ${env.DEPOT_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>
  1. Update your Dockerfile to copy configuration files and mount the secret:
# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Copy Maven configuration files
COPY .mvn/maven-build-cache-config.xml .mvn/maven-build-cache-config.xml
COPY .m2/settings.xml /root/.m2/settings.xml

# Run build with mounted secret
RUN --mount=type=secret,id=DEPOT_TOKEN,env=DEPOT_TOKEN \
    mvn clean install

Adding # syntax=docker/dockerfile:1 as the first line of your Dockerfile enables mounting secrets as environment variables.

  1. Build with Depot CLI:
depot build --secret id=DEPOT_TOKEN,env=DEPOT_TOKEN -t your-image:tag .

Or with Docker Buildx:

docker buildx build --secret id=DEPOT_TOKEN,env=DEPOT_TOKEN -t your-image:tag .

Using Depot Cache with Maven in Bake files

When using Bake files to build Docker images containing Maven projects, you can pass secrets through the target.secret attribute:

  1. Configure Maven Build Cache extension in .mvn/maven-build-cache-config.xml:
<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd">
    <configuration>
        <enabled>true</enabled>
        <hashAlgorithm>SHA-256</hashAlgorithm>
        <validateXml>true</validateXml>
        <remote enabled="true" saveToRemote="true" id="depot-cache">
            <url>https://cache.depot.dev</url>
        </remote>
        <projectVersioning adjustMetaInf="true" />
    </configuration>
</cache>
  1. Update your settings.xml to read the Depot token from an environment variable. Create or update .m2/settings.xml:
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>depot-cache</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer ${env.DEPOT_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>
  1. Define the secret in your docker-bake.hcl file:
target "default" {
  context    = "."
  dockerfile = "Dockerfile"
  tags       = ["your-image:tag"]
  secret = [
    {
      type = "env"
      id   = "DEPOT_TOKEN"
    }
  ]
}
  1. Update your Dockerfile to copy configuration files and run the build with mounted secret:
# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Copy Maven configuration files
COPY .mvn/maven-build-cache-config.xml .mvn/maven-build-cache-config.xml
COPY .m2/settings.xml /root/.m2/settings.xml

# Run build with mounted secret
RUN --mount=type=secret,id=DEPOT_TOKEN,env=DEPOT_TOKEN \
    mvn clean install

Adding # syntax=docker/dockerfile:1 as the first line of your Dockerfile enables mounting secrets as environment variables.

  1. Run the build with depot bake:
DEPOT_TOKEN=your_token depot bake