Artifact registry formats

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

A format is the package type a repository serves. Artifact registry supports several formats and their clients.

Supported package formats and clients

Format Clients
Maven mvn, gradle, sbt
npm npm, yarn, pnpm
Docker Docker CLI, Podman
OCI oras, Docker CLI, Podman

Docker and OCI formats and repositories

Docker and OCI repositories use the same registry endpoints. The registry applies different push rules depending on the format:

  • A Docker repository accepts container image manifests and manifests that carry a subject, such as a signature or an attestation that refers to an image.
  • A Docker repository rejects an artifact that is neither, such as a Helm chart or a WebAssembly module with an empty configuration. The push fails with 400 MANIFEST_INVALID.
  • An OCI repository accepts any manifest type.
  • Both formats reject Docker manifest schema 1.

Choose Docker when you store container images. Choose OCI when you store artifacts that are not container images. Because the format is fixed at creation, moving an artifact between the two means creating a new repository.

Repository types

Type Availability
Hosted Available for all formats.
Remote Available for all formats.
Virtual Available for all formats. In beta.

For more information, see repository types.

Delete an artifact

Delete an artifact to remove a package, version, file, image, tag, or manifest that you no longer need.

On a hosted repository, a delete is permanent and can’t be undone. On a remote repository, a delete removes the cached copy, and the next request for the artifact fetches it from the upstream again.

Prerequisites:

  • The Artifact Manager or Artifact Admin role.

To delete one artifact or a batch of artifacts, use the management API. For npm packages, you can also use npm unpublish.

Publish behavior for existing versions

Each format handles a publish to a version that already exists differently:

Format Behavior
npm Rejects the publish with a 409 Conflict error.
Maven Accepts a release file only if it is byte-for-byte identical to the stored one. Otherwise, rejects it with a 409 Conflict error. Overwrites -SNAPSHOT files and maven-metadata.xml.
Docker and OCI Accepts the push of an existing tag. The tag moves to the new manifest.