Artifact Registry

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed
  • Status: Beta

The availability of this feature is controlled by a feature flag. For more information, see the history.

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 revoke this role while they remain an organization administrator.

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.

Each organization can make 10 attempts in one hour to claim a registry handle. Attempts refused because the handle is not available also count. After 10 attempts, GitLab refuses new attempts until one hour after the first attempt. Trying a different handle does not help. Wait, then try again.

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:

RoleDescription
Artifact ViewerPull artifacts and view the artifact registry.
Artifact ContributorPublish artifacts. CI/CD jobs usually require this role.
Artifact ManagerManage a repository’s artifacts and settings. Delete artifacts.
Artifact AdminManage registry access. Create and delete repositories.

Permissions

The following table lists each role’s permissions.

ActionArtifact ViewerArtifact ContributorArtifact ManagerArtifact Admin
Assign artifact registry rolesNoNoNocheck-sm
View and download artifactscheck-smcheck-smcheck-smcheck-sm
Publish artifactsNocheck-smcheck-smcheck-sm
Delete artifactsNoNocheck-smcheck-sm
View repositories and usagecheck-smcheck-smcheck-smcheck-sm
Create repositoriesNoNoNocheck-sm
Update repository settingsNoNocheck-smcheck-sm
Delete repositoriesNoNoNocheck-sm
Manage a virtual repository’s upstreamsNoNocheck-smcheck-sm

Role scope

You can assign a role to the registry or to a single repository:

  • A role on the registry applies to every repository in it.
  • A role on a single repository applies only to that repository. The user does not need a role on the registry.

If someone has a role at both levels, they get the permissions of both roles on that repository. A role on a repository can add permissions. It cannot remove permissions that a role on the registry grants.

A user with roles on some repositories, and no role on the registry, sees only those repositories. Other repositories return a 404 Not Found error.

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.

Get a repository ID

To assign a role on a single repository, you need the repository ID.

Prerequisites:

  • The Artifact Admin role.

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

Assign a role

Assign a role to give a user access to the registry or to one repository.

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:

To assign a role:

To remove a role, use the artifactRegistryRoleRevoke mutation with the same assigneeId and resourceId.

Limit a user to some repositories

Limit a user to some repositories when they should not see the rest of the registry.

Prerequisites:

  • The Artifact Admin role.
  • The repository ID of each repository.
  • The user is not an organization administrator.

To limit a user to some repositories:

  1. Assign the user a role on each repository.
  2. If the user has a role on the registry, revoke it. Use the artifactRegistryRoleRevoke mutation, and set resourceId to the namespace ID.

Assign the repository roles before you revoke the registry role, so the user keeps access in between. The change can take a minute or more to take effect.

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.

LimitDefault
Maven artifact size5 GB
Maven maven-metadata.xml size10 MB
npm tarball size5 GB
npm package.json size20 KB
Container blob size50 GB
Container manifest size4 MB
References per container manifest200

Entity count limits

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

LimitDefault
Repositories per registry, per format1,000
Versions per package25,000
Tags per package version1,000
Tags per container manifest1,000
Manifests per container image25,000
Upstreams per virtual repository20
Repository description length1,024 characters
Repository name length255 characters

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.

FigureScopeWhat it counts
Stored sizeRepositoryThe size of the unique blobs the repository holds.
Deduplicated sizeRegistryThe size of the unique blobs across the whole registry.
Artifact countRepositoryThe artifacts the repository holds.
Component countRegistryThe versions and images across the whole registry.
Download countRepository, format, registryDelivered downloads.
Repository countRegistry, formatActive repositories.

Download counts for Docker and OCI repositories can include downloads recorded before Artifact registry started to count one download for each image manifest pull. Those earlier counts are higher than the real number of pulls, because every manifest and blob read was counted as a download.

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. Registry totals need a role on the registry. With a role on a repository only, you can view that repository’s figures.