Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.root.io/llms.txt

Use this file to discover all available pages before exploring further.

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

IssueSolution
401 UnauthorizedVerify token in settings.xml and that the server id matches the mirror id
Could not resolve artifactConfirm mirrorOf is set to central
Checksum validation errorsExpected for patched artifacts - Root’s checksums differ from Maven Central
SNAPSHOT artifactsSet <snapshots><enabled>false</enabled></snapshots> to avoid SNAPSHOT resolution through Root