Skip to content

CGRepo for Java - Global config #3464

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
s-stumbo wants to merge 2 commits into
base: main
Choose a base branch
from
Open

CGRepo for Java - Global config #3464

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5b15dff
CGRepo for Java - Global config
s-stumbo Jun 24, 2026
17a65a8
updates
s-stumbo Jun 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 59 additions & 93 deletions content/chainguard/libraries/java/global-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ linktitle: "Global configuration"
description: "Configuring Chainguard Libraries for Java in your organization"
type: "article"
date: 2025-03-25T08:04:00+00:00

@mosabua mosabua Jun 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

???

@s-stumbo s-stumbo Jun 30, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had accidentally changed this to the last updated date, so I changed it back to what was listed there previously and instead updated lastmod with my last updated time

lastmod: 2025-04-07T14:42:00+00:00
lastmod: 2026-06-24T14:42:00+00:00
draft: false
tags: ["Chainguard Libraries", "Java"]
images: []
Expand All @@ -24,40 +24,48 @@ Repository](https://www.sonatype.com/products/sonatype-nexus-repository). The
repository manager acts as a single point of access for developers and
development tools to retrieve the required libraries.

At a high level, adopting the use of Chainguard Libraries consists of the
following steps:

* Add Chainguard Libraries as a remote repository for library retrieval.
* Configure the Chainguard Libraries repository as the first choice for any
library access. This ensures that any future requests of new libraries access
the version supplied by Chainguard. Typically this is accomplished by creating a
group repository or virtual repository that combines the repository with other
external and internal repositories.

Additional steps depend on the desired insights and can include the following
The recommended approach is to use the [upstream
fallback](/chainguard/libraries/overview/#upstream-fallback-and-controls)
feature of Chainguard Repository, which allows you to configure your repository
manager with a single upstream pointed at `https://libraries.cgr.dev/java/`. The
Chainguard Repository handles fallback and policy enforcement; your repository
manager handles local caching and access control. Chainguard also retrieves
packages from the public Maven Central repository on your behalf when upstream
fallback is enabled. This includes protections such as malware scanning and a
cooldown period for newly published packages.

At a high level, adopting the use of Chainguard Libraries consists of the following steps:

* Configure your environment to use `https://libraries.cgr.dev/java/`
as the single upstream source for Java package retrieval. This can be done
either:
* As a remote repository in your repository manager, or
* Directly in your Java build configuration (for example, Maven or Gradle).
* Additional steps depend on your specific environment and preferences, and can include the following
optional measures:
* Remove all cached artifacts for Maven Central. This step ensures that any libraries you pull are from Chainguard Libraries, and not existing cached artifacts from upstream.
* Remove any repositories that are no longer desired or necessary, depending on your organization's preferences.

* Remove all cached artifacts in the proxy repository of Maven Central and other
repositories. This step allows you to validate which libraries are not
available from Chainguard Libraries and proceed with potential next steps with
Chainguard and your own development efforts.
* Remove any repositories that are no longer desired or necessary. Depending on
your library requirements this step can result in removal of some proxy
repositories or even removal of all proxy repositories.

Adopting the use of a repository manager is the recommended approach, however if
your organization does not use a repository manager, you can still use
Chainguard Libraries. All access to the Chainguard Libraries repository is then
distributed across all your build platforms and therefore more complex to
configure and control. Refer to the [direct access documentation for build
This page explains how to use Chainguard Libraries for Java with a repository
manager. If your organization does not use a repository manager, you can pull
directly from Chainguard. Refer to the [direct access documentation for build
tools](/chainguard/libraries/java/build-configuration/#direct-access) for more
information.

### Considerations for fallback approach

Before configuring your repo manager, consider how you want to handle packages that aren't
yet available in the Chainguard Libraries repository. If you configure a fallback to Maven Central, packages sourced from that registry are not covered by Chainguard's
malware-resistance guarantees. See the [fallback approaches](/chainguard/libraries/quickstart/#artifact-manager-recommended) described in the Chainguard Libraries quick start for guidance on choosing the right approach for your environment.
### Manually managing fallback
Chainguard recommends using the Chainguard Repository's built-in [upstream
fallback](/chainguard/libraries/overview/#upstream-fallback-and-controls) rather
than configuring a public registry fallback in your repo manager. Configuring
your own fallback bypasses the protection that the Chainguard Repository
provides.

However, if you intentionally want to manage fallback ordering yourself, you can
configure `https://libraries.cgr.dev/java/` as a remote repository alongside
your Maven upstream, and combine them in a virtual or group repository with
Chainguard as the first priority. The per-tool instructions on this page follow
this pattern. If you configure a fallback to Maven Central, packages sourced
from that registry are not covered by Chainguard's malware-resistance
guarantees.

<a name="cloudsmith"></a>

Expand All @@ -73,8 +81,7 @@ by defining multiple upstream repositories.

### Initial configuration

Use the following steps to add a repository with the Maven Central Repository
and the Chainguard Libraries for Java repository as Maven upstream repositories.
Use the following steps to set up a repository in Cloudsmith to access Chainguard Java Libraries via the Chainguard Repository.

Configure a `java-all` repository:

Expand All @@ -88,19 +95,6 @@ Configure a `java-all` repository:
infrastructure.
1. Click **+Create Repository**.

Configure an upstream proxy for the Maven Central Repository:

1. Click the name of the new `java-public` repository on the repositories
page to configure it.
1. Click the **Upstreams** tab, then click **+Add Upstream Proxy**.
1. Configure an upstream proxy with the format **Maven**.
1. Configure another upstream proxy with the following:
* **Name**: `java-public`
* **Priority**: `2`
* **Upstream URL**: `https://repo1.maven.org/maven2/`
* **Mode**: Cache and Proxy
1. Click **Create Upstream Proxy**.

Configure an upstream proxy for the Chainguard Libraries for Java repository:

1. Click the name of the new `java-chainguard` repository on the repositories
Expand All @@ -116,6 +110,8 @@ Configure an upstream proxy for the Chainguard Libraries for Java repository:
1. Click **Create Upstream Proxy**.
1. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named `java-chainguard-remediated` with a URL set to `https://libraries.cgr.dev/java-remediated/`. Use the same authentication details.

If you are manually configuring fallback, you can add an additional upstream proxy for the public Maven Central repository with a lower priority than `java-chainguard`.

Use this setup for initial testing with Chainguard Libraries for Java. For
production usage, add the `java-chainguard` upstream proxy to your production
repository.
Expand Down Expand Up @@ -151,7 +147,7 @@ are tagged with the name of the upstream proxy.

## Google Artifact Registry

[Google Artifact Registry](https://cloud.google.com/artifact-registry) supports
[Google Artifact Registry (GAR)](https://cloud.google.com/artifact-registry) supports
the Maven format for hosting artifacts in **Standard** repositories and proxying
artifacts from public repositories in **Remote** repositories. Use **Virtual**
repositories to combine them for consumption with Maven and other build tools.
Expand All @@ -161,9 +157,7 @@ point for more details.

### Initial configuration

Use the following steps to add the Maven Central Repository and the Chainguard
Libraries for Java repository as remote repositories and combine them as a
virtual repository:
Use the following steps to set up a repository in GAR to access Chainguard Java Libraries via the Chainguard Repository.

1. Log in to the Google Cloud console as a user with administrator privileges.
1. Navigate to your project and find the **Artifact Registry** with the search.
Expand All @@ -180,22 +174,10 @@ value as retrieved with chainctl](/chainguard/libraries/access/):
1. Set the **Secret** value to the password from your `chainctl` output.
1. Click **Create secret**.

Navigate to Artifact Registry and select **Repositories** in the left hand
navigation under the **Artifact Registry** label to configure a remote
repository for the Maven Central Repository:
Navigate to Artifact Registry. In the left hand navigation under Artifact Registry, select **Repositories**. Configure a remote
repository for Chainguard Libraries for Java:

1. Click **Create a Repository** (or the **+** button).
1. Configure the repository:
* **Name**: `java-public`
* **Format**: Maven
* **Mode**: Remote
* **Remote repository source**: Maven Central
* **Location type > Region**: Select a region.
1. Click **Create**.

Configure a remote repository for the Chainguard Libraries for Java repository:

1. Click **+** to add another repository.
1. Configure the repository:
* **Name**: `java-chainguard`
* **Format**: `Maven`
Expand All @@ -210,6 +192,8 @@ Configure a remote repository for the Chainguard Libraries for Java repository:
1. Click **Create**.
1. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named `java-chainguard-remediated` with a URL set to `https://libraries.cgr.dev/java-remediated/`. Use the same authentication details.

If you are manually managing fallback, you can configure an additional remote repository for the public Maven Central with lower priority.

Combine the repositories in a new virtual repository:

1. Click the **+** button to add another repository.
Expand All @@ -221,12 +205,9 @@ Combine the repositories in a new virtual repository:
1. Use the **Browse** button to locate and select the `java-chainguard`
repository as **Repository 1** and set the **Policy name 1** to
`java-chainguard`.
1. Use the **Browse** button to locate and select the `java-public` repository
as **Repository 1** and set the **Policy name 1** to `java-public`.
1. If you are using the remediated repository or manually configuring fallback to the public Maven repository, use the **Browse** button to locate and select each repository.
1. Under **Virtual upstream repositories**, click **Add upstream repository**.
1. Set the **Priority** value for the `java-chainguard` policy name to a higher
value than the `java-public` priority value.
* If you are using the remediated repository, add the `java-chainguard-remediated` repository and ensure it is the first in the displayed list. If not, ensure the `java-chainguard` repository is first.
1. Set the **Priority** values for the repositories. The priority order should be: `java-chainguard-remediated`, `java-chainguard`, then if you are manually configuring fallback to public Maven, `java-public` last.
1. Under **Location type**, choose the same suitable **Region** for your development as configured for the `java-public` repository.
1. Click **Create**.

Expand Down Expand Up @@ -258,24 +239,12 @@ for more information.

### Initial configuration

Use the following steps to add the Maven Central Repository and the Chainguard
Libraries for Java repository as remote repositories and combine them as a
virtual repository:
Use the following steps to set up a repository in Artifactory to access Chainguard Java Libraries via the Chainguard Repository.

1. Log in as a user with administrator privileges.
1. Click **Administration** in the top navigation bar.
1. Select **Repositories** in the left hand navigation.

Configure a remote repository for the Maven Central Repository:

1. Click **Create a Repository** and choose the **Remote** option.
1. Configure the repository:
* **Package type**: Maven
* **Repository Key**: `java-public`
* **URL**: `https://repo1.maven.org/maven2/`
* Deactivate **Maven Settings - Handle Snapshots**.
1. Click **Create Remote Repository**.

Configure a remote repository for the Chainguard Libraries for Java repository:

1. Click **Create a Repository** and choose the **Remote** option.
Expand All @@ -291,6 +260,8 @@ Configure a remote repository for the Chainguard Libraries for Java repository:
1. Click **Create Remote Repository**.
1. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named `java-chainguard-remediated` with a URL set to `https://libraries.cgr.dev/java-remediated/`. Use the same authentication details.

If you are manually managing fallback, you can configure an additional remote repository for Maven Central with lower priority. Make sure to deactivate **Maven Settings - Handle Snapshots** in the remote repository.

Combine the repositories in a new virtual repository:

1. Click **Create a Repository** and choose the **Virtual** option.
Expand Down Expand Up @@ -383,23 +354,15 @@ Libraries for Java repository for production use.

### Initial configuration

For initial testing and adoption it is advised to create a separate proxy
Use the following steps to set up a repository in Sonatype Nexus to access Chainguard Java Libraries via the Chainguard Repository.

If you are configuring your own fallback in your repo manager, for initial testing it is advised to create a separate proxy
repository for the Maven Central Repository, a separate proxy repository
Chainguard Libraries for Java repository, and a separate repository group:
Chainguard Libraries for Java repository, and a separate repository group.

1. Log in as a user with administrator privileges.
1. Click the gear icon in the top navigation bar to access **Server administration**.

Configure a remote repository for the Maven Central Repository:

1. Select **Repository - Repositories** in the left hand navigation.
1. Click **Create repository**, then select the `maven2 (proxy)` recipe.
1. Configure the repository:
* **Name**: `java-public`
* **Maven 2 - Version policy**: `Release`
* **Proxy - Remote storage**: Add the URL `https://repo1.maven.org/maven2/`.
1. Click **Create repository**.

Configure a remote repository for the Chainguard Libraries for Java repository:

1. Select **Repository - Repositories** in the left hand navigation.
Expand All @@ -414,6 +377,8 @@ Configure a remote repository for the Chainguard Libraries for Java repository:
1. Click **Create repository**.
1. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named `java-chainguard-remediated` with a URL set to `https://libraries.cgr.dev/java-remediated/`. Use the same authentication details.

If you are manually managing fallback, you can configure an additional `java-public` remote repository for Maven Central with lower priority.

Combine a new repository group and add the repositories:

1. Select **Repository - Repositories** in the left hand navigation.
Expand Down Expand Up @@ -445,3 +410,4 @@ Use the URL of the repository group, such as
configuration](/chainguard/libraries/java/build-configuration/) and build a
first test project. In a working setup the `java-chainguard` proxy repository contains
all libraries retrieved from Chainguard.