Buildless + Maven

🚧

Maven's build cache extension is in beta

Maven has a new build cache extension, which is awesome, but it may not ship with your Maven distribution just yet.

Setting up build caching in Maven

Build caching in Maven is very new, but works great with Buildless out of the box! There is no need for an extra plugin or extension (and we don't yet offer one). In the future, we may offer an enhanced plug-in or Maven extension as we do for Gradle.

First, you need to add the build cache extension to your build. After that, you add a cache configuration, and set up your Buildless credentials. See the directions for each step below to continue.

👍

Maven's remote cache docs are helpful

You can find Apache Maven's docs on this subject here.

Obtain your account and API key

Before you configure Maven with Buildless, you'll need to setup your account and obtain your API key. You can sign up for Buildless here. To locate your API key, it depends which kind of key you want to use:

• For individual users: Your API key is located in the welcome email and in your user settings, accessed from the Buildless Console.
• For tenant users who wish to authorize an org-level cache (with no specific user), access your org API key in the Buildless Console at Tenant → Settings → Integration.

Authorizing your environment

The easiest and most secure way to use Buildless is via the environment variables and CLI config files. These techniques for configuring the cache keep your API key out of your source code.

Once you obtain your API key, set it in your environment via BUILDLESS_APIKEY:

echo "export BUILDLESS_APIKEY=..." >> ~/.bashrc

export BUILDLESS_APIKEY="..."

🚧

Buildless with Maven does not yet support config files

The best way to authorize the cache is with a config file stored in your project, user directory, or globally on your system; this keeps your API key out of your environment, too, where other tools can access it.

Our Maven integration does not yet support this feature, but it will soon.

Adding the build cache extension to your build

First up, you'll need to add the build cache extension to your build. Add the snippet below to your Maven extensions; if you don't have an extensions file yet, you can create it at:

• .mvn/extensions.xml, or
• pom.xml

The latter is recommended.

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

Adding your cache configuration

Next, copy Maven's default template file to the following path:

.mvn/maven-build-cache-config.xml.

This file configures the build cache within your codebase. See the template itself for available options. At this time, there is no recommendation from Buildless about how to optimize these options, but it's on the way!

Configuring Maven to use Buildless

With build caching enabled, Maven will handle local caching. Next, configure remote caching to point to Buildless by specifying the API endpoint and authorization credentials.

Specifying your credentials

Same as with custom Maven repositories, your build cache credentials are situated in your Servers config, which is typically at ~/.m2/settings.xml.

You can add your credentials like this:

<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>buildless</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>X-API-Key</name>
            <value>${env.BUILDLESS_API_KEY}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
  ...
</settings>

🚧

Known issues with credentials configuration

When using the standard username/password configuration, the Maven Build Cache extension will sometimes fail to include credential information in the request. To avoid this, add your API Key under the X-API-Key header to ensure it is sent correctly every time.

Enabling Buildless as the remote cache

With your credentials specified, you can enable Buildless in your cache config:

<remote enabled="true" id="buildless">
    <url>https://maven.less.build/cache/generic/</url>
</remote>

📘

Naming your server configuration

You can use any name you want, just make sure it lines up with the <remote id=... value in your cache settings. The default ID value is cache if no value is specified.

Maven code samples

Check out the Maven code sample for a starting point.