cloudparts

Artifact registries

Private servers that hold a team’s packages and container images, cache what it pulls from public registries, and decide which versions get promoted, kept or deleted.

7 technologies on this page ↓
Live model
What you’re watchingBuilds ask one virtual repository for everything. Internal packages come from the local repository; public ones go to the remote repository, which answers most requests from its cache and only goes to the public registry on a miss.

How it works

An artifact registry, also called a repository manager, speaks the wire protocols of package managers and container tools, so npm install, pip install, mvn or docker pull talk to it as if it were npmjs.com, PyPI, Maven Central or Docker Hub. Most products offer three kinds of repository, under different names. A local or hosted repository stores what you publish yourself: internal libraries, release builds, your own images. A remote or proxy repository stands in front of a public registry: on the first request it fetches the package from upstream, stores a copy and serves it, and later requests come from that copy. Artifactory, for example, fetches remote artifacts only “on demand”, and rechecks changing metadata such as maven-metadata.xml or a Docker manifest after a cache period, two hours by default for most formats. A virtual or group repository puts several of these behind one URL and searches them in a fixed order, so a build needs only one registry address. Around those three sit the policies that make it more than a cache. Promotion moves or copies a build from a staging repository to a release repository once it passes tests or scans, so production only pulls from the release side. Retention and cleanup rules delete old snapshots and untagged images by count, age or last download, and a garbage collector then frees the blobs no longer referenced; stores like Artifactory keep each file once, named by its checksum, so the same JAR in ten repositories takes the space of one. Container registries follow the OCI Distribution Specification, which standardizes how images and other artifacts are pushed and pulled.

Think of it as

A company’s central stockroom. It shelves parts the company makes itself, keeps a copy of anything ordered from outside the first time someone asks for it, and hands everyone the same catalogue with the in-house shelf checked first. Stock that passed inspection moves to the outgoing shelf, and old stock is cleared out on a schedule.

Reach for it when

  • Builds pull the same dependencies and base images hundreds of times a day: a proxy cache keeps them fast, keeps working when the public registry is down, and avoids pull limits such as Docker Hub’s 100 anonymous pulls per 6 hours per IP address
  • You publish internal libraries or images that must not go to a public registry
  • Production should only run artifacts that passed tests, scans or a licence check: promotion from staging to release repositories makes that a rule
  • Several ecosystems (Maven, npm, PyPI, Docker, Helm) need one place for access control, audit logs and storage quotas

Think twice when

  • A small team with a few public dependencies and no private packages: the public registries and your forge’s built-in package registry are enough
  • Running one yourself without anyone to patch it: a registry sits on the path of every build, so its outages and vulnerabilities become yours; a managed registry may be the better choice
  • Configuring a private index next to the public one, such as pip’s --extra-index-url: clients then pick the higher version from either, which is how dependency confusion works; send clients to one virtual repository that checks private repositories first

A real example

A team of 40 runs 300 CI builds a day. Every build pulls node:22 from Docker Hub and installs about 900 npm packages, and on busy days CI fails with Docker Hub rate-limit errors. They set up a registry with a remote repository for Docker Hub, a remote repository for npmjs.com, a local repository for their own @acme/* packages, and a virtual npm repository that checks the local one first. CI now points .npmrc and its image names at the registry. The first build of the day fetches each package from upstream once; the rest are served from the cache. Release builds publish to a staging repository, a scan job promotes those without critical CVEs to the release repository that production pulls from, and a cleanup rule deletes snapshot builds older than 30 days.

Technologies

Specific products, and what each does differently.

Universal repository managers

Many package formats and container images in one server, with local, remote and virtual repositories.

JFrog ArtifactoryCommercialThe commercial universal repository manager: one server, or JFrog’s SaaS, that hosts, proxies and promotes artifacts for more than 60 package types, from Maven and npm to Docker images and Hugging Face models.Sonatype Nexus RepositoryCommercialSonatype’s repository manager, born from Maven: proxy, hosted and group repositories for Maven, npm, PyPI, Docker and more, in a free Community Edition capped by usage or a paid Pro edition.Artifact KeeperOpen sourceA self-hosted artifact registry written in Rust that speaks the protocols of more than 45 package formats, with proxying, promotion, retention rules and vulnerability scanning all in one MIT-licensed release.

Also used for artifact registries

Products of other kinds that are often used this way, grouped by what they are.

What each provider calls it

AWS
AWS CodeArtifact for packages (upstream repositories and one external connection to a public registry per repository); Amazon ECR for container images, with pull through cache rules
Google Cloud
Artifact Registry: standard, remote and virtual repositories for Docker, Maven, npm, Python, Go, Apt, Yum and more, with cleanup policies
Azure
Azure Artifacts feeds with upstream sources for packages; Azure Container Registry with artifact cache rules for images
Open source & others
Harbor and Project Quay for container images; Nexus Repository Community Edition and Artifact Keeper for many formats; Forgejo includes a package registry. Commercial: JFrog Artifactory, Nexus Repository Pro, Red Hat Quay

Same three repositories, different names#

Every product separates what you publish from what it proxies; the universal ones also merge them behind one URL.

ProductYour own artifactsCache of a public registryOne URL over several
JFrog ArtifactoryLocal repositoryRemote repositoryVirtual repository: local first, then remote caches, then remotes
Nexus RepositoryHosted repositoryProxy repositoryGroup repository, searched in member order
Artifact KeeperLocal repositoryRemote repository (24-hour default cache TTL)Virtual repository, members by priority number
Google Artifact RegistryStandard repositoryRemote repositoryVirtual repository
HarborProjectProxy cache project (no pushes)None
Red Hat QuayOrganization repositoryProxy cache organizationNone
  • Azure Artifacts folds all three into one feed: packages published to it, packages saved from upstream sources, then the upstream sources in their listed order.

In code · text

# pip.conf: send pip to ONE index, the registry’s virtual repository,
# which checks the private repository first and the PyPI proxy second
[global]
index-url = https://registry.example.com/pypi/python/simple/

# Not this: with extra-index-url pip asks both indexes and installs
# whichever has the higher version, so a public package with an
# internal name and version 9000.0.0 wins (dependency confusion)
# extra-index-url = https://pypi.internal.example.com/simple/

Often confused with

Package managersContainersBuild toolsCI/CD pipelinesRelease automationCommon Vulnerabilities and Exposures (CVE)
Where it came from2005–2026

Maven made downloading dependencies from a central repository routine, and with it came a new failure: the build broke whenever the public server was slow or down. Tamás Cservenák started Proximity in December 2005 to proxy Maven artifacts past a very slow ADSL line. Yoav Landman, a consultant moving client projects from Ant to Maven 2, started Artifactory in 2006, “frustrated by the absence of good options to manage dependencies and hosting artifacts in house”; a multi-day Codehaus outage was “the final straw”. Its adoption led him to found JFrog. In 2007 Sonatype asked Cservenák to build Nexus, which absorbed Proximity’s code. Both settled on the same model: proxy what is public, host what is yours, and group them behind one address.

Containers brought a second kind of registry. Quay launched in late 2013 as the first private hosted Docker registry, and CoreOS bought it in 2014. VMware started Harbor internally in 2014 and open-sourced it in 2016, the same year Nexus 3.0 added hosting a private Docker registry next to Maven, npm and NuGet. The OCI Distribution Specification 1.0, released in May 2021, turned Docker’s registry API into a common standard, so one registry can hold images, Helm charts and other artifacts.

Two events in the early 2020s made the proxy part hard to skip. Docker Hub began limiting pulls, today 100 per 6 hours for each anonymous IP address. And in February 2021 Alex Birsan showed “dependency confusion”: by publishing packages to npm, PyPI and RubyGems under internal names found in companies’ code, he got his code run inside more than 35 organizations, because tools such as pip with --extra-index-url take the higher version from either index. A virtual repository that checks private repositories first, with clients pointed only at it, became the standard defence; Google’s Artifact Registry documents ranking private repositories above remote ones for that reason.

Why it’s built this way

Cache on demand instead of mirroring
Copying all of Maven Central or npm would cost far more storage than any team uses. Remote repositories fetch an artifact the first time someone asks for it and keep it, so the cache holds exactly what builds need and still serves it when upstream is down.
One virtual URL with a fixed search order
Package managers given several sources may query them in parallel and take whichever answers or has the higher version. A server-side order (local first, then caches, then upstreams) makes resolution deterministic and stops a public package from shadowing a private one.
Store files by checksum
The same artifact appears in many repositories and is copied on every promotion. Storing each file once, named by its checksum, with the database mapping paths to checksums, makes copies and moves cheap database operations and deduplicates storage.
Retention as rules, then garbage collection
CI publishes a new snapshot or image tag on every commit, and nobody deletes them by hand. Rules that keep the newest N versions or those pulled recently mark the rest for deletion, and a separate garbage collection frees the blobs no remaining version references.

Timeline

  1. 2005

    Tamás Cservenák starts Proximity, a Maven proxy (December)

  2. 2006

    Yoav Landman starts Artifactory

  3. 2007

    Sonatype starts Nexus, which absorbs Proximity

  4. 2013

    Quay launches as a private hosted Docker registry

  5. 2016

    Harbor is open-sourced; Nexus 3.0 adds a private Docker registry (April)

  6. 2020

    Harbor graduates in the CNCF (June)

  7. 2021

    Dependency confusion is published (February); OCI Distribution Spec 1.0 (May)

  8. 2026

    Artifact Keeper, an MIT-licensed registry for 45+ formats, is released

Sources19

Improve this page on GitHub