OCI Repository

🚧

Early Access Feature

Our OCI registry is in early access, so some Cloudsmith features aren't yet available for OCI artifacts.

The OpenContainer Initiative (OCI) is a lightweight, open governance structure project, formed under the auspices of the Linux Foundation, for the express purpose of creating open industry standards around container formats and runtimes.

OCI provides the concept of the registry as a storage service for storing and distributing artifacts for use.

Cloudsmith is OCI-compliant and provides a fully-fledged registry with full OCI v1.1 compatibility. With Cloudsmith you'll be able to push, pull, inspect and manage OCI artifacts, privately and publicly.

All of this is provided with the standard functionality and features that are offered in the Cloudsmith platform, such as collaboration, advanced permissioning, whitelabelled distribution, multi-tenacy with other packaging formats, etc.

For more information on OCI, please see:

• OCI: The official website for the OpenContainer Initiative.
• OCI Distribution Spec: The official Github repository containing the distribution specification.
• OCI Article: The Wikipedia article on OCI.

Differences from the OCI Image and Distribution Specification

For clarity, it's important to note some of the differences between a registry such as Docker Hub, and a Cloudsmith OCI registry. These are both naming and functional in nature.

Naming Differences

Docker defines the following names (this is not the official wording):

• Layer: A blob (big object of bytes) containing software and configuration.
• Image: A collection of Docker layers plus metadata that represent an application.
• Container: A running instance of a Docker image in-memory.
• Repository: A collection of Docker images, separated by hashref and version tags.
• Registry: A collection of all Docker repositories, separated by namespaces.

For comparison purposes, where terms differ from Cloudsmith:

• Package: A specific identifiable and versionable artifact.
• Repository: A collection of versionable artifacts, with multiple allowed per account.

Therefore, based on the above, the following terms are equivalent:

For consistency, the terms will be used within all of the OCI-related documentation but please be aware of the differences if looking at documentation elsewhere.

Upload an Generic Artifact with ORAS

📘

If you have added a Custom Domain for Docker, you must use it to authenticate and push. Please replace docker.cloudsmith.io in the following instructions with the Docker custom domain you have created.

ORAS (OCI Registry As Storage) is an open-source tool that enables users to push, pull, and manage non-container artifacts in OCI-compliant registries. It extends the OCI specification beyond container images, turning registries into a general-purpose storage system for diverse artifact types.

Setup

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs

You need to authenticate via oras login to push/pull artifacts:

oras login docker.cloudsmith.io
Username: USERNAME
Password: API-KEY

Login Succeeded

Push an artifact

After authentication you can push the artifact by doing:

$ oras push docker.cloudsmith.io/OWNER/REPOSITORY/ARTIFACT_NAME:TAG ./FILENAME_PATH

ORAS allows you to specify the type of the artifact by using the --artifact-type parameter, you can use it in the following way:

$ oras push docker.cloudsmith.io/OWNER/REPOSITORY/ARTIFACT_NAME:TAG --artifact-type application/vnd.cloudsmith.v1 ./FILENAME_PATH

For more information on how to define a unique artifact type check the official documentation .

Attach file to an existing Artifact

🚧

The attach command in ORAS is in preview and still under development

As Cloudsmith is fully OCI v1.1 compliant, this includes support for the Referrers API.

Referrers allow artifacts to reference related objects, enabling a parent artifact (like a container image) to have associated metadata or attachments (e.g., SBOMs, signatures, or provenance files). This is critical for securely and efficiently managing relationships between artifacts, such as attaching additional context or verifying authenticity without modifying the original artifact.

To attach a file to an existing artifact, execute:

$ oras attach --artifact-type application/vnd.cloudsmith.attachment.v1 docker.cloudsmith.io/OWNER/REPOSITORY/ARTIFACT_NAME:TAG ./FILE_TO_ATTACH

Download / Pull an Generic Artifact with ORAS

Setup

Public Registries

For public registries, no further setup is needed as authentication is not required.

Private Registries

📘

Private Registries require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication.

The setup method will differ depending on what authentication type you choose to use.

🚧

Entitlement Tokens and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs

You need to authenticate via oras login to pull images:

oras login docker.cloudsmith.io
Username: token
Password: TOKEN

Login Succeeded

oras login docker.cloudsmith.io
Username: USERNAME
Password: API-KEY

Login Succeeded

Pull an Artifact

Pulling (downloading) an artifact from the Cloudsmith OCI registry can be done using the standard oras pull command:

$ oras pull docker.cloudsmith.io/OWNER/REPOSITORY/ARTIFACT_NAME:TAG

Push and pull Helm v3 charts via OCI

For this please refer to our Helm documentation here .

Security Scanning

Supported

Please see our Security Scanning documentation for further information.

Current Limitations

The Cloudsmith OCI registry implementation currently has the following limitations:

• At the moment all artifacts uploaded via OCI regardless of their artifact and media type will show in the Cloudsmith UI as a "Docker Package"

Upstream Proxying / Caching

Configurable Proxying Caching

You can configure upstream OCI registries you wish to use by using our Docker Upstream feature. In addition, you can also choose to cache any requested artifacts for future use.

Key Signing Support

RSA Index

Troubleshooting

Please see the Troubleshooting page for further help and information.