Global configuration

Go module consumption in a large organization is typically managed by a repository manager. The repository manager acts as a single point of access for developers and development tools to retrieve Go modules.

Configure Artifactory with a single remote repository pointed at https://libraries.cgr.dev/go/. Chainguard Repository handles upstream fallback and policy enforcement; Artifactory handles local caching, access control, and the endpoint used by your Go toolchains.

JFrog Artifactory

JFrog Artifactory supports Go repositories for proxying and hosting Go modules, and virtual repositories for combining sources into one endpoint. Refer to the Go repositories documentation for Artifactory for more information.

If an existing Artifactory remote repository points directly to a public Go module proxy, disable or remove it from the virtual repository that your builds use. Artifactory resolves virtual repositories according to their configured order, so a misconfiguration can cause an unprotected module to be served without an obvious build failure.

Prerequisites

Before you begin, you need:

• An entitlement to Chainguard Libraries for Go
• Administrator access to your repository manager instance
• A pull token for Chainguard Libraries for Go

Initial configuration

Use the following steps to add Chainguard Libraries for Go as an Artifactory remote repository:

1. Sign in to Artifactory as a user with administrator privileges.
2. Click Administration in the top navigation bar.
3. In the left navigation, click Repositories.
4. Click Create a Repository, then choose Remote.
5. Configure the remote repository with the following values:
   • Package type: Go
   • Repository key: go-chainguard
   • URL: https://libraries.cgr.dev/go/
   • Username: the username returned by chainctl
   • Password: the password returned by chainctl
6. Open the Advanced configuration tab and configure the following:
   • In the Network section, confirm that Lenient Host Authentication is unchecked. This prevents Artifactory from forwarding credentials across a redirect.
   • Optionally select Enable Cookie Management. JFrog recommends this for remote repositories that use redirects.
   • In the Others section, select Bypass HEAD Requests so that Artifactory retrieves package files with GET requests instead of probing with HEAD requests first.
   • In the Others section, uncheck Block Mismatching Mime Types.
   • Select Disable URL Normalization so that Artifactory does not rewrite a pre-signed redirect URL.
7. Click Create Remote Repository.

Chainguard Libraries serves module metadata and source archives through the standard Go module proxy protocol. Some module files may be served through redirects to pre-signed storage URLs. These settings prevent Artifactory from rewriting the redirect, forwarding credentials to another host, or caching a redirect response instead of the module file.

Create a virtual repository

Create a virtual repository to give developers and CI systems a single Go module endpoint:

1. Click Create a Repository, then choose Virtual.
2. Configure the virtual repository with the following values:
   • Package type: Go
   • Repository Key: go-all
   • Repositories: add go-chainguard
3. Click Create Virtual Repository.

For the recommended configuration, go-chainguard should be the only external upstream in go-all.

Validate the remote repository

Validate the Artifactory remote before configuring developer workstations or CI/CD systems. The Artifactory Test button is not a reliable indicator of a working Chainguard configuration; a remote can pass the test but still be misconfigured for package retrieval.

Use a module and version that are available through your organization’s Chainguard Libraries for Go entitlement. The following example uses rsc.io/quote version v1.5.2:

Fetch the module archive directly from Chainguard and compute its checksum:

 curl -fsS -L \\
   -u "${CHAINGUARD_GO_IDENTITY_ID}:${CHAINGUARD_GO_TOKEN}" \\
   "https://libraries.cgr.dev/go/rsc.io/quote/@v/v1.5.2.zip" \\
   | sha256sum

Fetch the same archive through the Artifactory remote repository and compute its checksum:

 curl -fsS -L \\
   -u "${ARTIFACTORY_USERNAME}:${ARTIFACTORY_TOKEN}" \\
   "https://<artifactory-host>/artifactory/go-chainguard/rsc.io/quote/@v/v1.5.2.zip" \\
   | sha256sum

Replace artifactory-host with your Artifactory hostname. Replace ARTIFACTORY_USERNAME and ARTIFACTORY_TOKEN with credentials that can read from Artifactory.

Fetch the archive through the virtual repository that developers and CI systems will use:

 curl -fsS -L \\
   -u "${ARTIFACTORY_USERNAME}:${ARTIFACTORY_TOKEN}" \\
   "https://<artifactory-host>/artifactory/go-all/rsc.io/quote/@v/v1.5.2.zip" \\
   | sha256sum

The three checksums must match. Do not proceed to production rollout if the Artifactory checksum differs from the direct Chainguard checksum or if either Artifactory request fails.

If validation fails, review the following settings:

• URL: confirm that the remote repository URL is exactly https://libraries.cgr.dev/go/.
• Credentials: regenerate the pull token with chainctl auth pull-token create --repository=go and update the Artifactory remote repository credentials. Expired tokens can fail without a clear error in the Artifactory user interface.
• Advanced configuration: confirm that the redirect and request settings from the initial configuration are applied.
• Cached files: if the remote repository was previously configured with incorrect settings, delete the affected cached module files from the go-chainguard cache and repeat the validation.
• Virtual repository order: confirm that no public Go proxy appears ahead of go-chainguard or is still included in go-all.

Configure build tools

Use the URL of the go-all virtual repository in Go configuration. In Artifactory, select the go-all repository and use Set Me Up or Generate Settings to obtain the URL and authentication instructions for your Artifactory version. The URL commonly has the following form: https://exampleorg.jfrog.io/artifactory/go-all.

See Configuring your build tool for more information.