> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Private Maven, Gradle & sbt Registries

> Connect Artifactory or Nexus, verify private package access, and check dependency coverage after scanning.

Connect your package registry so ZeroPath can resolve internal libraries and the
dependencies they bring into your application. Use this setup when a Maven,
Gradle, or sbt build needs private packages, parent POMs, BOMs, or build plugins.

## Choose the connection

In **Settings → Integrations → Registries → Package registries**, choose:

| Your build | Connection | Authentication |
| - | - | - |
| Maven (`pom.xml`) | **Maven / Gradle** | Basic or Bearer token |
| Gradle (`build.gradle` or `build.gradle.kts`) | **Maven / Gradle** | Basic or Bearer token |
| sbt (`build.sbt`) | **sbt (Scala / Java)** | Basic only: username and password or identity token |

Connections apply to the organization. You can save one **Maven / Gradle**
connection and one **sbt** connection. If you scan both build types, configure
both connections, even when they use the same registry and account.

## Before you connect

* You need the **Create Integrations** permission.
* Use a dedicated account or token with read access to the packages and build
  plugins your projects need.
* Get the HTTPS URL of a **virtual or group repository** that serves your internal
  packages and proxies their public dependencies. Use the repository endpoint,
  such as `https://mycorp.jfrog.io/artifactory/maven-virtual/` or
  `https://nexus.example.com/repository/maven-public/`, rather than the registry's
  sign-in page. Native Maven resolution routes all repositories through this URL.
* Choose a published private package whose POM requires authentication. You will
  need its exact `group:artifact:version`, for example
  `com.example:shared-library:1.2.3`.
* For hosted ZeroPath, the registry must be reachable over the public internet;
  private-network addresses are rejected. A self-hosted ZeroPath instance can use
  registries on its private network. HTTPS is still required, and loopback and
  cloud-metadata addresses remain blocked.

## Connect Maven or Gradle

**1. Open Package registries**

Open [Settings → Integrations](https://zeropath.com/app/settings/integrations).
Select **Add Integration → Registries**, then find **Maven / Gradle** under
**Package registries** and click **Connect**.

**2. Enter the repository and credentials**

Set **Registry URL** to your virtual or group repository URL.

For **Basic**, enter **Username** and **Password / identity token**. For
**Bearer token**, enter the token without a username. If your Gradle build
reads `.artifactory_credentials`, `ARTIFACTORY_USERNAME`, or
`ARTIFACTORY_PASSWORD`, choose Basic so those values are available during
build setup. Store the secret in this form, not in your repository or URL.

**3. Verify a private package**

In **Private package to verify**, enter `group:artifact:version` for a
published private package, then click **Connect registry**. ZeroPath checks
that the package requires authentication and that its POM is readable with
your credentials. Directory listing is not required.

For `com.example:shared-library:1.2.3`, the POM must be available at
`com/example/shared-library/1.2.3/shared-library-1.2.3.pom` beneath the
repository URL. A JAR without a POM is not enough for this check.

The connection supplies credentials for Maven POM/BOM lookups and native Maven
and Gradle dependency resolution. It also supports Gradle build setup that reads
the Artifactory credentials file or environment variables listed above.

### Private Gradle plugins

Declare the private plugin repository in `pluginManagement.repositories` in
`settings.gradle` or `settings.gradle.kts`. A repository declared only in a
project's `repositories` block does not configure plugin resolution. For example,
in `settings.gradle.kts`:

```kotlin theme={null}
pluginManagement {
    repositories {
        maven { url = uri("https://mycorp.jfrog.io/artifactory/maven-virtual/") }
        gradlePluginPortal()
    }
}
```

ZeroPath supplies authentication to Maven repositories on the connected host,
including declared plugin repositories. The repository must contain the plugin
and any metadata it needs; a successful library POM check does not verify plugin
access.

## Connect sbt

Under **Package registries**, click **Connect** for **sbt (Scala / Java)** and
complete these fields:

| Field | What to enter |
| - | - |
| **Maven repository URL** | Your HTTPS virtual or group repository URL, including public upstream dependencies. |
| **Username** and **Password / identity token** | A read-only account with access to your libraries and plugins. sbt uses Basic authentication. |
| **Authentication realm** | The realm returned by your registry's HTTP authentication challenge. Artifactory commonly uses `Artifactory Realm`; confirm it with your registry administrator. |
| **Private package to verify** | A published Maven-layout coordinate, such as `com.example:shared-library_2.12:1.2.3`. Include the Scala suffix from the published artifact name. |
| **Ivy repository URL (optional)** | An HTTPS Ivy repository if your sbt launcher or plugins use Ivy layout. It must use the same host, port, and credentials as the Maven URL. |
| **Ivy metadata path** | Required when you supply an Ivy URL. Enter the relative path to an existing metadata XML file, such as `org.example/plugin/scala_2.12/sbt_1.0/1.0/ivys/ivy.xml`, without a leading slash. |

Click **Connect registry**. ZeroPath verifies the private POM and, if supplied,
the Ivy metadata file. Ask your registry administrator for the exact Ivy path;
it is not a Maven coordinate or a directory listing.

Credentials are available before sbt starts and loads its build definition,
including private meta-build dependencies and plugins. Ivy, Coursier, and builds
that read `.artifactory_credentials` or `ARTIFACTORY_USERNAME` /
`ARTIFACTORY_PASSWORD` can use the connection. You do not need to commit these
credentials to your project.

## Run a scan and check coverage

After connecting, run a **new full scan or SCA scan** of the affected repository.
Saved connections are used automatically; previous scan results are not updated.

1. In **Assets → Repositories**, open the repository. Select the scanned branch in **Inventory**
   and check manifest resolution under **Overview**.
2. In **Inventory → Dependencies**, check for a known internal library and one of its expected
   transitive dependencies, including their resolved versions.
3. If the scan fails, read its error. For incomplete coverage, see how to
   [retrieve manifest warnings](https://zeropath.com/docs/sca/coverage.md#read-and-act-on-warnings) and check registry access
   and build configuration before retrying.

> [!NOTE]
>
> **Connected** confirms access to the package used for verification. The scan
> checks the rest of the build and its transitive dependencies.

Gradle and sbt can resolve transitives with their native build tools or a
supported committed lockfile: `gradle.lockfile`, `build.sbt.lock`, or `lock.sbt`.
To avoid running the build during scanning, generate the lockfile in your build
environment with registry access and commit it. When the manifest resolves from
that lockfile, ZeroPath skips native build resolution. See
[lockfile setup and commands](https://zeropath.com/docs/sca/coverage.md#gradle-and-sbt-lockfiles). If the scan
reports an error with a saved registry connection, correct it before retrying.

> [!WARNING]
>
> For Maven packages published only to private repositories, some transitive
> dependencies may remain unresolved after connecting. Check the scan's coverage
> and contact support with the scan URL and affected package coordinates if
> expected dependencies are missing.

## Troubleshooting

| What you see | What to check |
| - | - |
| The validation package is public | Choose an internal package whose POM cannot be read anonymously. A public dependency cannot verify your credentials. |
| Unauthorized, 401, or 403 | Check the username, token expiry, authentication mode, and read permissions for that repository and package. |
| The private package POM could not be read | Check the full repository URL, exact coordinate, and published POM. For Scala artifacts, include the published suffix, such as `_2.12` or `_2.13`. |
| Authentication realm mismatch | Use the realm from the registry's HTTP challenge. Ask your registry administrator if it differs from the default. |
| Ivy metadata could not be read | Check the Ivy URL, relative XML path, and read permissions. The Maven and Ivy URLs must share the same host and port. |
| A Gradle plugin is unresolved | Check `pluginManagement.repositories`, plugin metadata, and access to the plugin repository. |
| Connection succeeds, but resolution fails | Read the per-manifest warning. Check access to other packages, parent POMs, BOMs, sbt launcher or plugins, and public upstreams. Registry validation tests only the package you selected. |
| A saved JVM connection is unusable | Check the scan error, edit the connection, correct its URL or credentials, save it, and run a new scan. |

If the warning persists, send support the scan URL, affected manifest path,
warning message, and a package coordinate you expected to resolve. Do not include
tokens or passwords.

To rotate credentials, **Edit** the connection and save the new secret. Leaving
the secret field blank keeps the existing one; changing the authentication mode
requires a new secret. Changes apply to subsequent scans across the organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.