Artifact Registry API

Tier: Premium, Ultimate
Offering: GitLab.com
Status: Beta

Artifact Registry has two API surfaces. Use the GitLab GraphQL API to manage the registry and its repositories, for anything you would otherwise do in the UI. Use the Artifact Registry management API to read and delete the artifacts inside a repository. The Artifact Registry service serves the management API, not GitLab.

During beta, role assignment is available through the GitLab GraphQL API only. There is no UI for it yet.

Manage the registry with the GraphQL API

During beta, use the GitLab GraphQL API to manage the registry and its repositories. It’s the only supported way to assign roles.

Common tasks

Mutation	Description
`artifactRegistryActivate`	Activate the registry
`artifactRegistryRepositoryCreate`	Create a repository
`artifactRegistryRepositoryUpdate`	Update a repository
`artifactRegistryRepositoryDelete`	Delete a repository ¹
`artifactRegistryRoleGrant`	Grant a role
`artifactRegistryRoleRevoke`	Revoke a role
`artifactRegistryRoleBulkGrant`	Grant roles in bulk
`artifactRegistryRoleBulkRevoke`	Revoke roles in bulk

Footnotes:

artifactRegistryRepositoryDelete succeeds even if the repository is already deleted.

Queries

The registry queries are fields on the organization type:

Query	Description
`organization.artifactRegistry`	Fetch the registry, including the namespace ID (`id`) used as `resourceId` in role mutations

Pass the organization as a global ID, for example gid://gitlab/Organizations::Organization/123.

For all fields, arguments, and return types, see the GraphQL API reference.

Things to know

Every Artifact Registry query and mutation is an experiment. Names and arguments can change.
The whole GraphQL surface, queries and mutations, sits behind a feature flag named artifact_registry_ui. It’s disabled by default.
The queries artifactRegistryRepositories and artifactRegistryRepository return null when artifact_registry_ui is disabled. They raise a resource-not-available error when the organization isn’t activated. artifactRegistry returns null in both cases.

Management API

The Artifact Registry service serves this API, not GitLab. It uses its own credentials, separate from the GitLab API. Routes are anchored at the registry handle, under /api/v1/:handle/. No GitLab feature flag applies to it.

Repository create, read, update, and delete operations also live here. During beta, the GraphQL API is the supported route for those operations.

Artifacts

Resource	Operations
Container images, tags, and manifests	List and read. Delete one at a time or in a batch.
Maven and npm packages, versions, and files	List and read. Delete one at a time or in a batch.
npm dist-tags	List, read, and delete.
Statistics	Read figures for the registry, one format, one repository, or one version.

Conventions

Lists use keyset pagination. A request returns 20 items by default and at most 100 items. The response carries a Link header with the next and previous pages.
Lists return no total count.
Every response carries an X-Request-ID header. The same value appears in the error body. Quote the value when you report a problem.
An error body is a JSON object with an error key. The key holds code, message, and request_id.
A 401 status code is the exception. It returns an empty body with a WWW-Authenticate header.

The full endpoint reference, including request and response schemas, is published from the Artifact Registry project’s OpenAPI document. For more information, see the Artifact Registry project.

Lifecycle and retention policies are not available during beta, through either API surface.