This repo defines a plugin for Gradle which integrates with Buildless for remote build caching. Buildless can be used as a drop-in remote HTTPS cache endpoint, or you can use this plug-in which offers a number of extra luxurious features (see below).

Note Requires Gradle 8.0 or above

Current version

Latest: 1.0.0-rc2

settings.gradle.kts (Kotlin DSL):

plugins {
    id("build.less") version "1.0.0-rc2"
}

settings.gradle (Groovy DSL):

plugins {
    id 'build.less' version '1.0.0-rc2'
}

libs.versions.toml (Version Catalog):

[versions]
# ...
buildless = "1.0.0-rc2"

[plugins]
# ...
buildless = { id = "build.less", version.ref = "buildless" }

Getting started

Installing and using the plugin is pretty easy.

1. Install the plugin in your settings.gradle file (see above)
2. Set your API key via the Gradle DSL, env vars, config files, or JVM or Gradle properties (see below)
3. ???
4. Profit! (Enjoy lightning-fast build caching)

Of course, if you want to, you can customize the plugin's settings to your heart's content. Settings are documented below the Features section in this README.

Features

• 🚀 Lightning-fast build caching with Buildless
• ⚡ Buildless Agent support for near-cache, async pushes, and protocol upgrades
• 🔑 Automatically load API keys from environment vars, .env, config files, or Gradle or JVM properties
• 🧠 Smart auto-configuration of lowest-latency endpoints based on your location
• 📡 Build telemetry for enhanced cache reporting and performance
• 🔧 Configure Gradle build caching in one combined block, with our without using Buildless

We have more exciting features coming soon! Check out our public roadmap for more info.

Supply Chain Security

Our plugin is built in a secure fashion, and so is our service. Here are a few things we do keep things hardened:

• Dependency Verification: We aggressively verify dependencies, and use Dependency Locking to make sure versions don't drift
• We ship SBOMs in OWASP CycloneDX format, and soon in SPDX too
• Releases are stamped via Sigstore
• We aggressively update versions, and only depend on high-quality libraries / plugins
• All releases and publications are signed, all commits in those releases are signed
• All plugin code is open source, in this repo

Configuration

The plugin provides a Gradle DSL for configuring Buildless with Gradle, and additionally provides project-level customizations and checks.

The most important thing to set up is your API key. There are several ways to specify your key; they are listed exhaustively below, with their order of precedence.

Complete configuration sample

settings.gradle.kts (Kotlin DSL):

plugins {
  id("build.less") version "1.0.0-rc2"
}

buildless {
  // various flags:
  debug = true  // activate or deactivate debug mode (verbose logging, API tracing, etc)
  telemetry = true  // activate or deactivate private build telemetry (build analytics in the dashboard)
  reportErrors = true  // activate or deactivate error reporting to the buildless team (just plugin errors)

  // options for configuring your API key:
  apiKey("...")
  apiKey(ApiKey.of("..."))
  apiKey(ApiKey.of("...", type = SubjectType.ORG))

  // configuring local caching (it defaults to being active):
  localCache.enabled = true  // turn the local cache on or off
  localCache.directory = "..."  // set the directory where the cache is stored (defaults to .gradle/cache)

  // or...
  localCache {
    enabled = true
    directory = "..."
  }

  // configuring remote caching (it defaults to being active):
  remoteCache.enabled = true  // turn the remote cache on or off
  remoteCache.endpoint = "..."  // set a custom or enterprise cache endpoint (not usually necessary)

  // or...
  remoteCache {
      enabled = true
      endpoint = "..."
  }
}

API key

Builds use your regular API key, not your events key. Once you setup your Buildless account, you can find your key in your dashboard, either in the Tenant > Settings section (for an org-level key), or in your Profile (for your user-level key).

Once you obtain your API key, you can set it up in any of the following ways. The first key found (from top to bottom in this document) will be used:

• 1) DSL string (not recommended). For example:

  buildless {
    apiKey("...")
  }

• 2) Environment variables. All the following values work:

  • BUILDLESS_APIKEY
  • GRADLE_CACHE_PASSWORD

• 3) Gradle or JVM system properties. All the following values work:

  • buildless.apiKey

• 4) Config file (recommended). All the following locations work (project root unless otherwise specified):

  • .buildless.toml, .buildless.yaml, .buildless.json (with or without preceding .)
  • .github/.buildless.toml, .github/.buildless.yaml, .github/.buildless.json (with or without preceding .)
  • package.json:buildless (as a JSON object)
  • ~/.config/buildless.toml, ~/.config/buildless.yaml, ~/.config/buildless.json (with or without preceding .)

Note: You can find your Buildless API key in your dashboard.

Debug mode

Default value: true

buildless {
  debug = true  // or `BUILDLESS_DEBUG` or `-Dbuildless.debug` or `-Pbuildless.debug`
}

Activating debug mode activate verbose logging for the plugin, and additionally marks API calls with trace values which can be used for diagnosis from the dashboard.

Agent

Default: On when Agent is active, off otherwise

buildless {
  agent {
    enabled = true  // enabled by default if agent is active
  }
}

The Buildless Agent is software which runs on the local machine and acts as a caching proxy between Gradle and Buildless. It is highly recommended to use the Agent, as it upgrades Gradle's cache traffic from HTTP/1.1 to HTTP/2 or HTTP/3, and performs a number of other optimizations.

About the Agent

Agent functionality is also recommended for two other reasons:

• Async pushes: With the Agent enabled, your build no longer has to wait for pushes to fully complete to the Cloud. Instead, these are deferred and your build continues immediately.

• Resilience: If there is a network interruption or outage with Buildless Cloud, or your Cloud-based cache is inaccessible for any other reason, your build continues and remains unaffected.

The Buildless Agent is provided with the CLI tools.

Agent detection

The Agent is detected, if running, via a known configuration file location on disk, as well as socket or port liveness checks, as applicable. There is no need to restart your Gradle daemon to notice an Agent process.

Local cache

Default: On when Agent is off, off when Agent is on

buildless {
  local {
    enabled = true  // enabled by default if agent is off
  }
}

Activating the local cache enables Gradle's built-in disk caching mechanism. This is generally good to leave off if the Buildless Agent is enabled, because the Agent will cache in-memory and on-disk intelligently, and there isn't much sense (or gain) in duplicating that effort.

You can still opt-in to the local cache with the Agent if you want to using the snippet above.

Telemetry

Default value: true

buildless {
  telemetry = false  // or `BUILDLESS_TELEMETRY` or `-Dbuildless.telemetry` or `-Pbuildless.telemetry`
}

Build telemetry is the basis for a great many features in Buildless. After processing, it is handed directly back to you for use in your dashboard. Emitting telemetry is recommended in all circumstances (including CI and locally); the telemetry transport is optimized for low overhead and doesn't block the build.

If you really don't want to emit telemetry, you can disable it as shown above.

Error reporting

Default value: true

buildless {
  errorReporting = false
}

Error reporting is used to send errors to the Buildless team for analysis. It is recommended to leave this on, but if you are working in an airgapped environment (or just don't want to share that information), you can always turn it off.

Support

Need help setting up Buildless, or have a question? Drop us a line:

email: support at less dot build
phone: +1-844-420-1414

Or chat with us anytime via the Intercom widget in the dashboard.

Legalese

This software was made by the Elide team, and is meant for use with Buildless. You can use it to configure any local or remote caching in Gradle, though.

License