Artifact Registry

The GitLab artifact registry provides a single registry for your organization where you can store, manage, and distribute Maven, npm, Docker, and Open Container Initiative (OCI) artifacts.

Artifact registry lives at the organization level, not the project or group level. One registry serves every team in the organization, so you do not have to configure a registry for each project or group.

Artifact registry is in beta: public beta on GitLab.com and closed beta on GitLab Self-Managed. Do not use it for production workloads. Keep your existing package registry or container registry as the system of record, and test artifact registry with non-production or parallel pipelines.

To request access, sign up for the beta or contact your GitLab account team. On GitLab.com, GitLab then turns on artifact registry for your organization. On GitLab Self-Managed, your account team works with an administrator to install artifact registry and turn on its feature flags.

Enable artifact registry

To enable artifact registry in your organization, you must claim a registry handle. A registry handle serves as a permanent URL identifier for a registry namespace in an organization. It appears in every registry URL and in every client configuration file.

After you enable artifact registry, Organization Administrators are automatically granted the Artifact Admin role.

You cannot change the handle after you claim it. If the registry is deleted, the handle is retired permanently and cannot be reused.

Prerequisites:

• You must be an Organization Administrator for the organization.

To claim a registry handle and enable artifact registry:

1. In the left sidebar, select Your work > Organizations.
2. Select your organization.
3. In the left sidebar, select Artifact registry.
4. In the Registry handle text box, enter a handle. The handle must:
   • Be between 3 to 63 characters
   • Use only lowercase letters, digits, and hyphens (hyphens cannot be consecutive)
   • Start and end with a letter or digit
   • Not include api, app, or v followed by digits
   • Be unique across all of GitLab.com (some names are reserved)
5. Select Enable Artifact registry.

Artifact registry roles and access

Artifact registry uses its own roles, which are distinct from GitLab roles. GitLab roles cannot access or grant access to the artifact registry.

Only an Artifact Admin can assign roles. After you enable artifact registry, other users in the organization cannot access the registry until an Artifact Admin assigns them a role.

Membership in the organization, its groups, or its projects does not grant access to artifact registry.

Roles

Artifact registry has four roles:

Permissions

The following table lists each role’s permissions.

Get artifact registry namespace ID

Before you can assign artifact registry roles to users in an organization, you must fetch your registry namespace ID.

Prerequisites:

• The Artifact Admin role for the organization.

Query the ID with the organization.artifactRegistry field in the GraphQL API. To run the query, see Queries.

Assign a role

You can assign a role to the registry or a single repository. A role assigned to the registry applies to every repository in it. A role assigned to a single repository applies only to that repository.

If someone is assigned a role at both levels, they can access both the registry and its repositories.

Only an Artifact Admin can assign roles. A registry-level Artifact Admin can assign roles across the registry. A repository-level Artifact Admin can assign roles on that repository only.

Prerequisites:

• The Artifact Admin role.
• The artifact registry namespace ID

To assign and manage roles, use the artifact registry GraphQL API.

Authentication

Authentication with artifact registry requires a GitLab token. The GitLab token is exchanged for a short-lived access token scoped to the artifact registry.

When your package client makes a request, the artifact registry token authenticates it.

For detailed authentication instructions, see authenticate with artifact registry.

Repositories

A repository stores your artifacts. Artifact registry supports hosted, remote, and virtual repository types.

To learn more about repositories, see artifact registry repositories.

Visibility

Access to artifact registry is closed by default. You must have an artifact registry role to view the registry.

Registry limits

Artifact registry applies the following limits per registry.

Artifact size limits

Artifact size limits are applied by counting bytes as the request body is read, not by trusting the Content-Length header. A request that goes over the limit is cut off at the same size whether or not it declares a length, and nothing is stored.

Entity count limits

Entity count limits are checked before they are written. Exceeding a limit returns a 422 Unprocessable Content error.

Pagination limits

• List requests return 20 items by default and up to 100.
• Larger values are reduced to 100.
• Container tag lists return 100 items by default and up to 1,000.

Lists use keyset pagination, return the next and previous pages in a Link header, and do not include a total count.

Storage quota

During beta, storage is free and has no quota.

Artifact registry measures storage as the total size of the unique blobs in your registry. Identical content stored twice counts once. Blobs are deduplicated in a registry, not across registries. Usage updates after an upload finishes, so large uploads take a moment to appear.

Rate limits

During beta, rate limits are not enforced.

When rate limits are enforced, a throttled request returns a 429 Too Many Requests error with a Retry-After header.

View storage usage

Artifact registry reports storage usage and download counts for registries, repositories, formats, and versions and images.

Prerequisites:

• The Artifact Viewer, Artifact Contributor, Artifact Manager, or Artifact Admin role.

To view a repository’s stored size, artifact count, and download count, go the repository page:

1. In the left sidebar, select Artifact registry > Repositories.
2. Select the repository you want to view storage usage for.

To view registry totals, use the statistics API.