Artifact registry repositories
- Tier: Premium, Ultimate
- Offering: GitLab.com
- Status: Beta
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 hosted, remote, and virtual repositories.
Hosted repositories
A hosted repository stores the artifacts you publish to it with your package client, such as the packages your CI/CD pipeline builds. Hosted repositories are available for every format.
Behavior when you publish a version that already exists differs by format. For details, see publish behavior for existing versions.
Remote repositories
A remote repository proxies and caches one upstream registry over HTTPS. Clients read through the remote repository, and the registry caches each response. You cannot publish to a remote repository.
Virtual repositories
Virtual repositories are in beta. You can create and delete one for any format, and add upstreams to it. You cannot publish to any virtual repository.
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.
A role on a virtual repository grants access to every artifact served through it, including artifacts from upstreams you have no role on. In the upstream list of a virtual repository, you see the URL, health, visibility, and size of an upstream only if you have read access to that upstream. Otherwise, you see only its name, format, type, and position.
Set the upstreams of a virtual repository
Set the upstreams of a virtual repository so that clients can pull from several repositories through one URL.
The following requirements apply to virtual repositories and upstreams:
- An upstream must be a hosted or remote repository in the same registry, and must use the same format as the virtual repository. Docker and OCI virtual repositories accept both Docker and OCI upstreams.
- A virtual repository can have up to 20 upstreams.
- A virtual repository with no upstreams serves no artifacts.
Prerequisites:
- To set upstreams when you create a virtual repository: the Artifact Admin role.
- To change the upstreams of an existing virtual repository: the Artifact Manager or Artifact Admin role.
To set the upstreams of a virtual repository, use the GraphQL API:
- When you create a virtual repository, include the upstream repository IDs in the order you want the registry to check them.
- When you update a virtual repository, query the current list in the
upstreamRepositoriesfield, then send the whole list with your changes. The new list replaces the existing one and removes any upstream you leave out. It also overwrites any changes that another user made after your query.
To add, move, or remove a single upstream without replacing the whole list, use the management API.
Upstream list errors
After the repository’s own fields validate, the management API checks an upstream list in this order, and stops at the first check that fails:
400 Bad Request: The repository is not virtual. On create, set the type to virtual. On update, leave the list out.400 Bad Request: The value is not an array of distinct UUIDs. Send an array of distinct repository IDs, or[]for no upstreams.422 Unprocessable Contentwith thelimit_exceededcode: The array holds more than 20 IDs. Shorten the array to 20 IDs or fewer.422 Unprocessable Contentwith anerror.details.upstream_repository_idvalue: The value is the first ID in the array that cannot be an upstream. The ID cannot be an upstream because it names a repository that does not exist, is in another registry namespace, is virtual, or has a format the virtual repository does not accept. Remove or replace that ID, then send the request again.
The GraphQL mutations return the refused ID in refusedUpstreamRepositoryId.
Supported public upstreams
A remote repository can proxy any registry URL over HTTPS. Artifact registry recognizes the following public upstreams and adjusts how it caches them:
| Format | Upstream URL | Behavior |
|---|---|---|
| npm | https://registry.npmjs.org |
Cached tarballs never revalidate by default because npmjs.com does not allow a published version to be overwritten. Package metadata still refreshes, so new versions appear. |
| Maven | https://repo1.maven.org/maven2 or https://repo.maven.apache.org/maven2 |
Cached files never revalidate by default because Maven Central does not allow a published artifact to be overwritten. |
Caching and freshness
A remote repository caches what it fetches from the upstream. After a cached entry’s validity window passes, artifact registry checks the entry against the upstream again.
| Setting | Default | What it covers |
|---|---|---|
cache_validity_hours |
24 hours | Content files, such as npm tarballs, Maven JAR and POM files, and container tags. For upstreams whose published content never changes, set to 0 to never revalidate1. Container blobs and manifests never revalidate because their digest identifies their content. |
metadata_cache_validity_hours |
24 hours | Metadata, such as maven-metadata.xml, npm package metadata documents, and npm dist-tag mappings. Applies to Maven and npm only. Must be greater than 0, so that newly published versions appear. |
Test an upstream connection
Artifact registry checks each remote repository’s upstream every few minutes and marks it unhealthy after repeated connection failures or server errors.
While an npm or container upstream is unhealthy, the remote repository serves only cached
artifacts whose validity window has not passed. Other requests fail with a
503 Service Unavailable error and a Retry-After header until the upstream recovers.
Virtual repositories skip an unhealthy upstream.
To test the upstream connection, use the management API.
Upstream credentials
Maven and container upstreams use a username and password, and npm upstreams use an authentication token. Artifact registry shows whether credentials are set, but never shows their values.
Do not put credentials in the upstream URL. Anyone who can view the remote repository can see the URL. When you change the upstream URL, provide the credentials again in the same update. If you don’t, artifact registry clears the stored credentials.
Create a repository
Create a repository to store, proxy, or combine artifacts for one package format.
Prerequisites:
- The Artifact Admin role.
To create a repository:
- In the left sidebar, select Artifact registry > Repositories.
- Select New repository, then select Hosted repository, Remote repository, or Virtual repository.
- From the Format dropdown list, select Docker, Maven, npm, or OCI.
- 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
- Optional. In the Description (optional) text box, enter a description.
- Optional. For a virtual repository, add its upstream repositories:
- Select Add repository.
- Search for and select one or more hosted or remote repositories of the same format, then select Add.
- To change the order in which the registry checks the upstreams, use the arrow buttons.
- Select Create repository.
After you create the repository, the format, type, and name cannot change.
In the management API, the type is the kind field.
Delete a repository
Deleting a repository permanently removes the repository and its artifacts. You can’t undo a delete. If you must delete a repository, make a backup copy before you delete it.
After deletion, you cannot:
- Restore a deleted artifact or repository.
- Set a retention window or a policy that deletes content on a schedule.
Prerequisites:
- The Artifact Admin role.
To delete a repository:
- In the left sidebar, select Artifact registry > Repositories.
- Select the repository.
- Select More actions ( ) > Delete repository.
- In the Delete repository? confirmation dialog, type the repository name to confirm.
- Select Delete repository.
To delete a repository, you can also use the API.
After you delete a repository, its name becomes available again: immediately for an empty repository, or after all its artifacts are removed. This timing isn’t guaranteed, so don’t build automation that depends on reusing a name right away.
-
Setting
cache_validity_hoursto0does not turn caching off. A remote repository cannot fetch from the upstream without caching the result. ↩︎