Artifact registry repositories

Use repositories to store and manage artifacts for a specific package format. A repository serves one package format and its artifacts, and you cannot nest one repository inside another.

During beta:

• Repository visibility is set to private by default.
• Organization members cannot view the artifact registry or its repositories without an assigned artifact registry role.

Repository types

Artifact registry supports the following repository types:

• Hosted: Stores artifacts you publish. Use a hosted repository to push your own builds, such as the packages your CI/CD pipeline produces.
• Remote: Proxies and caches one external registry. When a client reads from a remote repository, the request passes through to the upstream registry and the response is cached. You cannot publish to a remote repository.
• Virtual: Combines several repositories behind one URL. Clients point at one registry instead of several. You cannot publish to a virtual repository.

Virtual repositories

A virtual repository uses one URL to point to multiple upstream repositories. The virtual repository organizes its upstream repositories into an ordered list.

When a client requests a package from a virtual repository, the registry walks through the list of upstreams in order until an upstream with the requested package is found.

When working with virtual registries:

• You cannot publish to a virtual repository or to a remote repository. Both reject writes.
• An upstream cannot be a virtual repository. The registry rejects that upstream when you add it.
• A virtual repository can hold up to 20 upstreams. Going over the limit returns a 422 Unprocessable Content error.
• A role assigned to a virtual repository controls read access through that repository. A role assigned to a contained repository controls direct requests to that repository.

Supported public upstreams

Remote upstream repositories can proxy the following public registries:

• npm: Proxies npmjs.com.
• Maven: Proxies Maven Central.
• Docker: Proxies Docker Hub.

Caching and freshness

Content is stale after the validity window passes following the last upstream check. A stale entry is checked against the upstream again.

Set cache_validity_hours to 0 to never revalidate. Use this setting for upstreams whose published content never changes, such as npmjs.com and Maven Central.

Setting cache_validity_hours to 0 does not turn caching off. No pass-through mode skips the cache.

metadata_cache_validity_hours must be greater than zero. Metadata has to refresh, or newly published versions never appear.

Container blobs and manifests are addressed by digest, so the registry never checks them again. The digest is the content.

Where the upstream returns an entity tag, revalidation is conditional, and only changed content is downloaded.

A stale entry with no stored entity tag is fetched in full.

Test an upstream connection

• The test sends a HEAD request to the base URL of the upstream.
• A scheduled check runs every five minutes with a five-second timeout.
• A remote is marked unhealthy after three consecutive failures.
• 2xx and 3xx responses mean healthy.
• 401, 403, and 404 also mean healthy, because they prove the upstream is reachable.
• Many container registries serve nothing at their root, so a healthy Docker Hub upstream commonly answers 404.
• Only transport errors, timeouts, and 5xx responses count as failures.
• An unhealthy upstream is skipped during virtual resolution without an outbound request.
• A direct read against an unhealthy remote repository returns 503 with a Retry-After header.
• A cache hit against an unhealthy remote repository is still served.

Upstream credentials

• Maven and container upstreams take a username and password.
• npm upstreams take an authentication token.
• Credentials are write-only.
• Responses show only whether credentials are set, never the values.
• Changing an upstream URL clears the stored credentials unless you supply new ones in the same request.
• The response reports that the credentials were cleared.
• Credentials scoped to the old host must not be sent to a new one.

Create a repository

To create a repository:

1. In the left sidebar, select Artifact registry > Repositories.
2. Select New repository, then select Hosted repository or Remote repository.
3. From the Format dropdown list, select Docker, Maven, npm, or OCI.
4. In the Repository name text box, enter a name. The name must:
   • Be 1 to 255 characters
   • Use lowercase letters, digits, and the characters ., _, and -
   • Start and end with a letter or digit
   • Be unique across the whole registry
5. Optional. In the Description (optional) text box, enter a description.
6. Select Create repository.

After you create the repository, the format, type, and name cannot change. Only the description can change.

Delete a repository

In beta, repository deletion permanently removes the repository and its artifacts. If you must delete a repository, make a backup copy before you delete it.

After deletion, you cannot:

• Restore a deleted artifact or repository.
• See deleted content in a trash view.
• Set a retention window or a policy that deletes content on a schedule.

Prerequisites:

• The Artifact Admin role.

To delete a repository:

1. In the left sidebar, select Artifact registry > Repositories.
2. Select the repository.
3. Select More actions ( ) > Delete repository.
4. In the Delete repository? confirmation dialog, type the repository name to confirm.
5. Select Delete repository.

You can also delete a repository through the API.

Repository name availability after deletion

If you delete an empty repository, the name is available immediately.

If you delete a repository with artifacts, the name is available after all artifacts are removed.

Visibility

During beta, visibility is set to private for all repositories.

Related topics

• Artifact registry formats