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 closed beta. 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.

Artifact registry is available by invitation only, to a limited set of beta participants. To request access, contact your GitLab account team.

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.

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.

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

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 Artifact Admins can access the registry and assign roles to other Organization Members.

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 Organization Members, 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

• A list request returns 20 items by default and up to 100. A larger value is reduced to 100.
• Container tag listings return 100 items by default and up to 1,000.
• Lists use keyset pagination and return a Link header with the next and previous pages. Lists return no total count.

Storage quota

• During beta, storage is free and applies no storage quota.
• Storage is measured as the total size of the unique blobs in your registry. Identical content stored twice counts once.
• Blobs are deduplicated in a registry, never across registries.
• Usage counters update after an upload finishes, so a large upload takes a moment to appear.

Rate limits

• During beta, artifact registry has no enforced rate limits. Limits are configured and measured, but requests are not blocked.
• When rate limiting is 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.