Remote repositories overview

This document provides an overview of remote repositories. For instructions on how to create a remote repository, see Create remote repositories.

Artifact Registry Quotas and limits apply to remote repositories.

How remote repositories work

Remote repositories store artifacts from preset external sources such as Docker Hub, Maven Central, the Python Package Index (PyPI), Debian or CentOS as well as user-defined sources for supported formats. A remote repository acts as a proxy for the external source so that you have more control over your external dependencies. The first time that you request a version of a package, Artifact Registry downloads and caches the package in the remote repository. The next time you request the same package version, Artifact Registry serves the cached copy.

If you request an artifact from an upstream source that doesn't exist, or doesn't contain the version you specified, the request will fail.

The other repository modes are:

  • Standard: The default repository mode. You upload or publish artifacts such as private packages directly to standard repositories. Although you can download directly from individual standard repositories, accessing groups of repositories with a virtual repository simplifies tool configuration.
  • Virtual: A repository that acts as a single access point for multiple upstream repositories, including remote and standard repositories.

Upstream authentication

Artifact Registry remote repositories support basic authentication to preset and user-defined upstream sources for supported formats. For more information on how to authenticate to remote repository upstream sources, see Configure authentication to remote repository upstreams.

Use cases and benefits

Faster, more reliable access to artifacts
Storing cached copies of your public dependencies in Artifact Registry reduces latency when other Google Cloud services retrieve images. Cached artifacts are also still available if the external public repository is offline due to an outage or other issue.
Safer dependency resolution

Use remote repositories together with virtual repositories to mitigate risks associated with public dependencies. Some tools do not provide a way to control search order when a mix of private and public repositories are configured in the client. This type of configuration is vulnerable to a dependency confusion attack, where someone uploads a new version of a package with bad code to a public repository to trick clients into choosing the bad version.

Instead of configuring clients directly to search multiple repositories, you can configure virtual repositories to prioritize your private repositories over remote repositories.

If Artifact Registry is in a VPC Service Controls service perimeter, Artifact Registry denies access to upstream sources outside the perimeter by default. To allow remote repositories in a specific location to access their configured external sources outside the perimeter, see the instructions for VPC Service Controls configuration.

To learn about other dependency management best practices, see Dependency management.

Updates to package indexes and metadata

Mutable files such as package indexes and metadata are updated from the upstream source when they become more than the default age. Defaults for specific file types are listed in the following table:

Format File type Default update age
Maven maven-metadata.xml 5 minutes
archetype-catalog.xml 1 hour
Npm Manifest files 5 minutes
Python Index files 1 hour
Docker List/Get tags cache 1 hour
Apt/Yum (preview) Index files 2 minutes
Package files 72 hours

Supported formats

See the following sections for the formats available for preset and user-defined remote repositories.

Preset upstreams

You can create remote repositories for the following repository formats and corresponding preset upstream sources:

Format package types Upstream URL Upstream preset name
Docker Public or private DOCKER-HUB
Maven Public or private MAVEN-CENTRAL
npm Public or private NPMJS
Python Public PYPI
OS packages (preview) Public See OS packages supported upstreams See OS packages supported upstreams

OS packages preset upstreams

You can create an OS package remote repository by choosing a repository base and customizing the remainder of the URL to the specific repository. The following repository bases are supported:


Repository URL Prefix Repository Base Name
Ubuntu LTS or Pro UBUNTU


Repository URL Prefix Repository Base Name
Fedora Extra Packages for Enterprise Linux (EPEL) EPEL

User-defined upstreams

You can create remote repositories for user-defined upstream sources in the following formats:

  • Docker
  • npm
  • Maven
  • Python

The following non-exhaustive table lists some common upstream URIs.

Format Upstream URI Registry Name
Docker AWS ECR Public Gallery
Docker Kubernetes Container Registry
Docker Jfrog Artifactory
Docker https://MY_NEXUS_IP Nexus
npm GitHub Npm Registry
npm Jfrog Artifactory
npm https://MY_NEXUS_IP/repository/MY_UPSTREAM_REPOSITORY Nexus
Maven Jfrog Artifactory
Maven https://MY_NEXUS_IP/repository/MY_UPSTREAM_REPOSITORY Nexus
Python Jfrog Artifactory
Python https://MY_NEXUS_IP/repository/MY_UPSTREAM_REPOSITORY Nexus


  • MY_ARTIFACTORY_INSTANCE is the name of your Jfrog Artifactory upstream instance.
  • MY_NEXUS_IP is the IP address and port of your Nexus upstream instance.
  • MY_UPSTREAM_REPOSITORY is the name of your upstream repository; used in the Nexus and Artifactory examples.


In addition to Artifact Registry quotas and limitations, remote repositories have the following limitations:

  • Maven remote repositories don't permit setting the version policy to snapshot or release.

What's next