> 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/concepts/registries-and-upstream-proxies.md).

# Registries and upstream proxies

Understand the difference between local registries and upstream proxies in Harness Artifacts, how resolution order works, and how to combine them effectively.

Harness Artifacts gives your team a central, controlled location to store the artifacts you own and cache the packages you consume, instead of developers pulling packages directly from the public internet.

## What is a registry

A **registry** in Harness Artifacts is a named, typed store for a specific package format. Each registry handles exactly one format: Docker images, Maven packages, npm packages, Helm charts, and so on. This one-format-per-registry design means your tooling always knows exactly which protocol to use, and your access controls stay clean.

Registries exist at a **scope**: account, organization, or project. A registry created at the account level is visible across your entire organization. One created at the project level is visible only within that project. You can promote artifacts up the scope hierarchy as they mature from development to production.

Every registry has a unique URL in the form:

```
pkg.harness.io/<account-id>/<registry-name>/
```

Your package manager points at this URL. Harness handles authentication, caching, scanning, and policy enforcement behind it.

## What is the difference between a local registry and an upstream proxy?

Harness supports two distinct registry kinds, and the distinction matters.

**A local registry** stores artifacts you push to it. Your CI pipeline builds a Docker image and pushes it here. A developer publishes an internal Maven library here. The registry owns that content. Nothing is fetched from outside.

**An upstream proxy** does not store your own artifacts. Instead, it acts as a caching intermediary between your developers and an external registry such as Docker Hub, Maven Central, npm, or PyPI. When a developer requests a package, the proxy checks whether it is already cached locally. If it is, the proxy serves the cached copy quickly, without a network call to the internet. If it is not cached, the proxy fetches it from the upstream source, stores it locally, and returns it to the developer.

The critical difference: a local registry is a source of truth for things you own; an upstream proxy is a transparent cache for things you consume.

An upstream proxy does not require a local registry. You can create one on its own and point your package manager directly at it. Attaching an upstream proxy to a local registry is only useful when you want a single endpoint that serves both your internal packages and cached external dependencies.

## Resolution order

A local registry can have one or more upstream proxies attached to it. When the registry receives a pull request, it resolves the artifact using a fixed order:

1. Check the local registry first. If the artifact exists there, return it immediately.
2. Query the upstream proxies in the priority order you configured, from top to bottom.
3. The first proxy to find the artifact wins. The artifact is cached and returned.

This means a locally published version always takes precedence over an upstream-cached version of the same package. Platform teams can use this to pin internal forks of open-source libraries without touching developer workflows.

Go to [Add and prioritize upstream proxies](https://developer.harness.io/artifact-registry/3.0/registries/add-and-prioritise-upstream-proxies.md) to configure proxy priority order.

{% hint style="warning" %}
**Shadowing upstream versions**

If you publish a package locally with the same name and version as one available upstream, the local copy shadows the upstream version permanently. Only change this intentionally.
{% endhint %}

## Use cases

### Isolating internal packages from the public internet

Your internal libraries should never be published to public registries. Create a local registry for each package format you produce. Developers configure their package managers once to point at your Harness registry. Internal packages stay internal.

### Surviving public registry outages

Docker Hub enforces pull rate limits. npm has had availability incidents. PyPI has experienced outages. When your CI pipeline depends on public registries directly, any outage or rate limit causes build failures.

Configure an upstream proxy for each public registry you depend on. After the first pull, Harness serves subsequent requests from cache. Your builds continue even when the upstream source is unavailable, as long as the artifact is already cached; an artifact that has never been pulled still requires the upstream source to be reachable.

### Tiered staging and production proxies

New open-source packages carry risk: a newly published version might contain malicious code or undisclosed vulnerabilities. A safe pattern is to pull new packages through a staging upstream proxy first, let Dependency Firewall scan and evaluate them, then promote approved versions to a production upstream proxy using Copy Version. Developers pull only from the production proxy and never receive an unscanned package.

Go to [Dependency Firewall](https://developer.harness.io/artifact-registry/3.0/concepts/dependency-firewall.md) to understand how policy evaluation integrates with upstream proxies.

## Next steps

* [Create a registry](https://developer.harness.io/artifact-registry/3.0/registries/create-a-registry.md)
* [Create an upstream proxy](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md)
* [Add and prioritize upstream proxies](https://developer.harness.io/artifact-registry/3.0/registries/add-and-prioritise-upstream-proxies.md)

{% @harness-feedback/feedback %}
