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:
- In the left sidebar, select Your work > Organizations.
- Select your organization.
- In the left sidebar, select Artifact registry.
- 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, orvfollowed by digits - Be unique across all of GitLab.com (some names are reserved)
- 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:
| Role | Description |
|---|---|
| Artifact Viewer | Pull artifacts and view the artifact registry. |
| Artifact Contributor | Publish artifacts. CI/CD jobs usually require this role. |
| Artifact Manager | Manage a repository’s artifacts and settings. Delete artifacts. |
| Artifact Admin | Manage registry access. Create and delete repositories. |
Permissions
The following table lists each role’s permissions.
| Action | Artifact Viewer | Artifact Contributor | Artifact Manager | Artifact Admin |
|---|---|---|---|---|
| Assign artifact registry roles | No | No | No | |
| View and download artifacts | ||||
| Publish artifacts | No | |||
| Delete artifacts | No | No | ||
| View repositories and usage | ||||
| Create repositories | No | No | No | |
| Update repository settings | No | No | ||
| Delete repositories | No | No | No | |
| Manage a virtual repository’s upstreams | No | No |
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:
- The Artifact Admin role.
- The artifact registry namespace ID or the repository ID.
To assign a role:
- Use the
artifactRegistryRoleGrantmutation in the GraphQL API. SetresourceIdto the namespace ID or the repository ID, and send your organization ID in theX-GitLab-Organization-IDheader.
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:
- Assign the user a role on each repository.
- If the user has a role on the registry, revoke it.
Use the
artifactRegistryRoleRevokemutation, and setresourceIdto 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.
| Limit | Default |
|---|---|
| Maven artifact size | 5 GB |
Maven maven-metadata.xml size |
10 MB |
| npm tarball size | 5 GB |
npm package.json size |
20 KB |
| Container blob size | 50 GB |
| Container manifest size | 4 MB |
| References per container manifest | 200 |
Entity count limits
Entity count limits are checked before they are written.
Exceeding a limit returns a 422 Unprocessable Content error.
| Limit | Default |
|---|---|
| Repositories per registry, per format | 1,000 |
| Versions per package | 25,000 |
| Tags per package version | 1,000 |
| Tags per container manifest | 1,000 |
| Manifests per container image | 25,000 |
| Upstreams per virtual repository | 20 |
| Repository description length | 1,024 characters |
| Repository name length | 255 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.
| Figure | Scope | What it counts |
|---|---|---|
| Stored size | Repository | The size of the unique blobs the repository holds. |
| Deduplicated size | Registry | The size of the unique blobs across the whole registry. |
| Artifact count | Repository | The artifacts the repository holds. |
| Component count | Registry | The versions and images across the whole registry. |
| Download count | Repository, format, registry | Delivered downloads. |
| Repository count | Registry, format | Active 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:
- In the left sidebar, select Artifact registry > Repositories.
- 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.