> ## 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.

# Java - Maven, Gradle

> Configure Maven or Gradle to use Root Library Catalog for secure Java dependencies.

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](/integrations/gradle), which patches at build time — no CLI needed. Skip to the [Gradle section](#gradle).

Install the CLI if you're using Maven:

```bash theme={null}
# 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](/rlc/patcher#installation).

Then set your API key:

```bash theme={null}
export ROOTIO_API_KEY="your-api-key-here"
```

***

## Maven

### \~/.m2/settings.xml

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

```xml theme={null}
<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>
```

<Warning>
  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.
</Warning>

### Patch dependencies

```bash theme={null}
# 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:

```bash theme={null}
mvn clean install
```

### CI/CD Configuration

```yaml theme={null}
# 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:

```xml theme={null}
<password>${env.ROOT_TOKEN}</password>
```

***

## Gradle

The [Root.io Gradle Plugin](/integrations/gradle) automatically patches vulnerable dependencies at build time with zero changes to your dependency declarations.

### Installation

Apply the plugin in `build.gradle.kts`:

```kotlin theme={null}
plugins {
    id("io.root.patcher") version "0.2.0"
}
```

The plugin is published to the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/io.root.patcher) — 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](/integrations/gradle#option-4-private-jfrog-artifactory) in the Gradle integration guide.

### Configuration

```kotlin theme={null}
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

```bash theme={null}
export ROOTIO_API_KEY="your-api-key-here"
./gradlew build
```

For full details, see the [Gradle integration guide](/integrations/gradle).

***

## 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 |