Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Artifact RegistryRegistry TypesDependency Firewall

Create an upstream proxy

Create an upstream proxy to cache artifacts from an external registry such as Docker Hub, Amazon ECR, or a private server on demand.

An upstream proxy is a special registry configuration that fetches artifacts from an external source on demand and caches them locally. When a client requests an artifact that is not already in the cache, Harness retrieves it from the configured upstream source, stores it, and serves future requests from the local copy.

Use an upstream proxy to:

  • Cache open-source dependencies so builds continue even if the upstream source is down or rate-limiting requests.

  • Route all external artifact traffic through a single controlled access point.

  • Apply Dependency Firewall policies to artifacts fetched from public registries.

Artifacts cached through an upstream proxy are automatically scanned at ingest time when the Harness Supply Chain Security module is enabled.

Before you begin

  • Your role must include Create/Edit permission on Artifact Registry. Go to RBAC and permissions for details.

  • If the upstream source requires authentication, store the credentials in Harness Secret Manager before you create the proxy. Harness Artifacts does not support external secret managers for upstream authentication.

Create an upstream proxy

  1. In the left navigation, select Registries.

  2. Select Create registry.

  3. In the Create a new artifact registry drawer, select the Upstream Proxy toggle or choose the package type and enable the upstream proxy option.

  4. Select the registry type that matches the upstream source format.

  5. Enter an Upstream Proxy Key.

    The key must start with a letter and can only contain lowercase letters, numbers, underscores (_), hyphens (-), and periods (.).

  6. Configure the Source for the upstream:

    Source option
    When to use

    Docker Hub

    Public Docker Hub registry

    AWS ECR

    Amazon Elastic Container Registry

    Custom

    Any other registry, including on-premises servers (for example, JFrog Artifactory)

    When you select Custom, enter the Remote registry URL. The URL must start with https://. Use the base URL of the repository, not a specific artifact path.

  7. Set the Authentication method:

    • Anonymous: for public sources that do not require credentials.

    • Username and Password: for private sources. Select the Harness secrets that store your credentials.

    NPM bearer token

    Bearer token authentication is available only for npm upstream proxies. Go to the npm client setup page to configure a bearer token for an npm upstream proxy.

  8. Select Create upstream proxy.

After creation, attach the proxy to one or more registries so clients can use it. Go to Add and prioritise upstream proxies.

Configure metadata cache TTL

After creating the proxy, you can configure how long the proxy caches package metadata fetched from the upstream source.

Open the upstream proxy, select Configuration, then find the Metadata configuration section.

Field
What it controls
Range
Default

Metadata Cache TTL

How long cached package index metadata stays valid before Harness checks the upstream again

0–604,800 seconds (7 days)

600 seconds (10 min)

Negative Cache TTL

How long Harness caches a not-found response before retrying the upstream

0–604,800 seconds (7 days)

600 seconds (10 min)

A value of 0 means the field is unset and the default applies.

Metadata cache TTL controls how long package index metadata stays valid. It does not remove cached artifacts. To remove cached artifacts on a schedule, go to Lifecycle management.

Delete cached artifacts

Deleting a cached artifact removes it from the local cache only. It does not appear in the Deleted view. Pull the artifact again through the proxy to re-cache it from the upstream source.

Troubleshooting

Can I use an on-premises JFrog Artifactory as an upstream source?

Yes, if Harness can reach your Artifactory server over HTTPS. Select Custom as the source, enter the Artifactory repository URL (starting with https://), and choose Username and Password authentication. Store the credentials as Harness secrets before creating the proxy.

To copy artifacts from Artifactory in bulk rather than fetching on demand, go to Migrate artifacts.

Can I pre-fill the cache before clients request artifacts?

No. An upstream proxy fetches and caches an artifact the first time a client requests it. To fill the cache in advance, request the artifact through the proxy once, for example in a pipeline step that installs or pulls the dependency.

My build times are unexpectedly slow after setting up an upstream proxy

Verify that your dependency manager is configured to use the proxy registry URL (for example, in .npmrc, pip.conf, or settings.xml). If the client is still resolving packages directly from the public registry, it is bypassing the cache entirely.

Next steps

Last updated

Was this helpful?