Java - Maven, Gradle

Root Library Catalog provides a Maven-compatible repository at pkg.root.io/maven/.

Prerequisites

Root Library Catalog supports two integration approaches depending on your build tool:

Maven: uses the Root Patcher CLI (rootio_patcher) to patch your pom.xml before building.
Gradle: uses the Root.io Gradle Plugin, which patches at build time — no CLI needed. Skip to the Gradle section.

Install the CLI if you’re using Maven:

# macOS (Apple Silicon)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_darwin_arm64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/

# Linux (x86_64)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_linux_x86_64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/

For macOS Intel and Windows, see the full installation instructions. Then set your API key:

export ROOTIO_API_KEY="your-api-key-here"

Maven

~/.m2/settings.xml

Configure Root as a mirror for Maven Central and add your credentials:

<settings>
  <servers>
    <server>
      <id>root-io</id>
      <username>rootio</username>
      <password>YOUR_ROOT_TOKEN</password>
    </server>
  </servers>

  <mirrors>
    <mirror>
      <id>root-io</id>
      <name>Root.io Mirror for All Maven Repositories</name>
      <url>https://pkg.root.io/maven/</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>

  <profiles>
    <profile>
      <id>root-io</id>
      <repositories>
        <repository>
          <id>root-io</id>
          <name>Root.io Maven Patches</name>
          <url>https://pkg.root.io/maven/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>root-io</id>
          <name>Root.io Maven Plugins</name>
          <url>https://pkg.root.io/maven/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>root-io</activeProfile>
  </activeProfiles>
</settings>

Keep your Root token out of source control. Use environment variable interpolation (${env.ROOT_TOKEN}) in settings.xml and export the token in your shell or CI environment.

Patch dependencies

# Preview
rootio_patcher maven remediate

# Apply
rootio_patcher maven remediate --dry-run=false

# Specify a pom.xml path
rootio_patcher maven remediate --file=path/to/pom.xml --dry-run=false

After running the patcher, rebuild:

mvn clean install

CI/CD Configuration

# GitHub Actions example
- name: Build with Maven
  run: mvn -U test
  env:
    ROOT_TOKEN: ${{ secrets.ROOT_TOKEN }}

Use environment variable interpolation in settings.xml to inject the token safely:

<password>${env.ROOT_TOKEN}</password>

Gradle

The Root.io Gradle Plugin automatically patches vulnerable dependencies at build time with zero changes to your dependency declarations.

Installation

Apply the plugin in build.gradle.kts:

plugins {
    id("io.root.patcher") version "0.2.0"
}

The plugin is published to the Gradle Plugin Portal — no extra repository configuration needed. If your pluginManagement block explicitly lists repositories, make sure gradlePluginPortal() is included. If your organization uses JFrog Artifactory, you can also host the plugin there or route patched artifact resolution through an Artifactory proxy - see Private JFrog Artifactory in the Gradle integration guide.

Configuration

rootio {
    // API key is resolved automatically from:
    // 1. Build script: apiKey.set("...")
    // 2. Environment variable: ROOTIO_API_KEY
    // 3. JVM system property: systemProp.ROOTIO_API_KEY
    // 4. .env file: ROOTIO_API_KEY=...

    ttlHours.set(24)  // Cache TTL (default: 24 hours)
    maxRetries.set(3)  // Retry attempts (default: 3)
}

Build

export ROOTIO_API_KEY="your-api-key-here"
./gradlew build

For full details, see the Gradle integration guide.

Troubleshooting

Issue	Solution
`401 Unauthorized`	Verify token in `settings.xml` and that the `server id` matches the `mirror id`
`Could not resolve artifact`	Confirm `mirrorOf` is set to `central`
Checksum validation errors	Expected for patched artifacts - Root’s checksums differ from Maven Central
SNAPSHOT artifacts	Set `<snapshots><enabled>false</enabled></snapshots>` to avoid SNAPSHOT resolution through Root

Getting Started

Root Image Catalog

Platform

Integrations

AI Integrations

Root Library Catalog

Core Concepts

Reports & Insights

Reference

Trust & Compliance

Java - Maven, Gradle

Prerequisites

Maven

~/.m2/settings.xml

Patch dependencies

CI/CD Configuration

Gradle

Installation

Configuration

Build

Troubleshooting

​Prerequisites

​Maven

​~/.m2/settings.xml

​Patch dependencies

​CI/CD Configuration

​Gradle

​Installation

​Configuration

​Build

​Troubleshooting

Prerequisites

Maven

~/.m2/settings.xml

Patch dependencies

CI/CD Configuration

Gradle

Installation

Configuration

Build

Troubleshooting