> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/maven.md).

# Maven

Maven - publish artifacts to Harness Artifacts

Use a **Maven** registry to host private Java packages. The registry works with the Maven, Gradle, and Sbt/Scala clients.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install the Maven CLI (`mvn`), Gradle (`gradle`), or sbt, depending on your build tool.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Maven Registry

To create a Maven registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Maven** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Maven, Gradle, and Sbt/Scala packages from external sources when they are not available locally. The default upstream is Maven Central.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Maven** as the **Registry type**.
7. Select the **Source**: **Maven Central** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL**.
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required. This works for public Maven registries.
9. Optionally, configure **Metadata configuration** to control how long the registry caches metadata and not-found responses from the upstream source.

{% hint style="info" %}
**Metadata configuration**

The **Metadata cache TTL (seconds)** field controls how long cached metadata, such as a package index, stays valid before the registry fetches it again. The **Negative cache TTL (seconds)** field controls how long the registry caches a not-found response, so it does not repeat an upstream lookup for an artifact it already failed to find. Both fields accept a value from 0 to 604800 seconds (7 days) and default to 600 seconds (10 minutes); a value of 0 is treated as unset.

Metadata TTL does not remove cached artifacts. To delete cached artifacts, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

For the full field reference, go to [Configure metadata cache TTL](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md#configure-metadata-cache-ttl).
{% endhint %}

10. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Maven Artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Select **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Select **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a package is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.
{% endhint %}

## Maven client setup

In your Maven Artifact, select the required registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for the Maven, Gradle, or Sbt/Scala client.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your Maven Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Select **Maven**, **Gradle**, or **Sbt/Scala** for your build tool. In the code samples, replace the values in angle brackets with your own values.

{% tabs %}
{% tab title="Maven" %}
**1. Configure authentication**

Add the registry credentials to your `~/.m2/settings.xml` file on macOS or Linux, or `%USERPROFILE%\.m2\settings.xml` on Windows:

```xml
<settings>
  <servers>
    <server>
      <id>maven-dev</id>
      <username><USERNAME></username>
      <password><IDENTITY_TOKEN></password>
    </server>
  </servers>
</settings>
```

**2. Pull a package**

Add the registry as a repository in your project's `pom.xml`:

```xml
<repositories>
  <repository>
    <id>maven-dev</id>
    <url>https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/maven</url>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </releases>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>
</repositories>
```

Add a dependency, replacing `<GROUP_ID>`, `<ARTIFACT_ID>`, and `<VERSION>` with your own:

```xml
<dependency>
  <groupId><GROUP_ID></groupId>
  <artifactId><ARTIFACT_ID></artifactId>
  <version><VERSION></version>
</dependency>
```

Install the dependency:

```bash
mvn install
```

**3. Push a package**

Add the registry as a distribution target in `pom.xml`:

```xml
<distributionManagement>
  <snapshotRepository>
    <id>maven-dev</id>
    <url>https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/maven</url>
  </snapshotRepository>
  <repository>
    <id>maven-dev</id>
    <url>https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/maven</url>
  </repository>
</distributionManagement>
```

Publish the package:

```bash
mvn deploy
```

{% endtab %}

{% tab title="Gradle" %}
**1. Configure authentication**

Add the registry credentials to your `~/.gradle/gradle.properties` file:

```properties
repositoryUser=<USERNAME>
repositoryPassword=<IDENTITY_TOKEN>
```

**2. Pull a package**

Add the registry as a repository in your project's `build.gradle`:

```groovy
repositories {
  maven {
    url "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/maven"
    credentials {
      username findProperty('repositoryUser')
      password findProperty('repositoryPassword')
    }
  }
}
```

Add a dependency, replacing `<GROUP_ID>`, `<ARTIFACT_ID>`, and `<VERSION>` with your own:

```groovy
dependencies {
  implementation '<GROUP_ID>:<ARTIFACT_ID>:<VERSION>'
}
```

Install the dependencies:

```bash
./gradlew build     # Linux or macOS
gradlew.bat build    # Windows
```

**3. Push a package**

Add a maven-publish plugin configuration to `build.gradle`:

```groovy
publishing {
  publications {
    maven(MavenPublication) {
      groupId = '<GROUP_ID>'
      artifactId = '<ARTIFACT_ID>'
      version = '<VERSION>'
      from components.java
    }
  }
  repositories {
    maven {
      url "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/maven"
      credentials {
        username findProperty('repositoryUser')
        password findProperty('repositoryPassword')
      }
    }
  }
}
```

Publish the package:

```bash
./gradlew publish
```

{% endtab %}

{% tab title="Sbt/Scala" %}
**1. Configure authentication**

Add the registry credentials to your `~/.sbt/.credentials` file:

```properties
realm=Harness Registry
host=pkg.harness.io
user=<USERNAME>
password=<IDENTITY_TOKEN>
```

**2. Pull a package**

Add the registry as a resolver in your project's `build.sbt`:

```scala
resolvers += "Harness Registry" at "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/maven"
credentials += Credentials(Path.userHome / ".sbt" / ".credentials")
```

Add a dependency, replacing `<GROUP_ID>`, `<ARTIFACT_ID>`, and `<VERSION>` with your own:

```scala
libraryDependencies += "<GROUP_ID>" % "<ARTIFACT_ID>" % "<VERSION>"
```

Install the dependency:

```bash
sbt update
```

**3. Push a package**

Add a publish target to `build.sbt`:

```scala
publishTo := Some("Harness Registry" at "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/maven")
```

Publish the package:

```bash
sbt publish
```

{% endtab %}
{% endtabs %}

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. In a new project with no cached dependencies for the package (no matching entries in `~/.m2/repository`, `~/.gradle/caches`, or `~/.ivy2/cache`), use your build tool to install or resolve the package you published.
2. Confirm that the client downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step for a Maven project. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        mvn versions:set -DnewVersion="$PACKAGE_VERSION" versions:commit
        mvn deploy
```

## Troubleshooting

<details>

<summary>`mvn deploy` fails with `401` or `403` against a Maven registry</summary>

Check that the registry address in your `settings.xml` matches the one shown in **Setup Client**, and that the identity token is the one you generated there. If the token has expired or was revoked, generate a new one and update your client configuration.

</details>

<details>

<summary>`mvn deploy`, `gradlew publish`, or `sbt publish` returns `409 Conflict`</summary>

Package versions are immutable after publish. Choose a new version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`mvn install` cannot resolve a package, or `gradlew build` finds only the latest version</summary>

Check that the group ID, artifact ID, and version match the values you used when you published the package. Also, check that the registry name and account ID in your client configuration are correct.

</details>

<details>

<summary>Client still uses an old version after a new publish</summary>

Clear the local dependency cache for your build tool (`~/.m2/repository`, `~/.gradle/caches`, or `~/.ivy2/cache`), and update the version you pinned in your project.

</details>

<details>

<summary>**Setup Client** has no push instructions on an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** omits the push instructions for it. Publish to a virtual Maven registry instead, or cache packages from Maven Central through the upstream proxy.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
