OCI Repository

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

Helm v3 charts via OCI

Starting Helm v3.8.0 OCI-compliant registries can now be used to store and share chart packages. For full detail see Helm Docs .

🚧

Early Access Feature

While Cloudsmith OCI Registries are GA, our Helm OCI registry is in Early Access, so some Cloudsmith features like Helm OCI Upstreams aren't yet available.

Setup

Before you can push your chart you need to login to Cloudsmith's registry.

helm registry login helm.oci.cloudsmith.io -u OWNER/REPOSITORY -p TOKEN

helm registry login helm.oci.cloudsmith.io -u USERNAME -p PASSWORD

helm registry login helm.oci.cloudsmith.io -u USERNAME -p API-KEY

With public repositories, you don't need any sort of authentication and you can jump straight to the Installing a Chart section below.

Push your chart

The command to upload a Helm Chart via OCI using the Helm CLI is:

helm push CHART_NAME-CHART_VERSION.tgz oci://helm.oci.cloudsmith.io/OWNER/REPOSITORY

Installing a Chart

To install/use a specific version of a chart:

helm install oci://docker.cloudsmith.io/OWNER/REPOSITORY/CHART_NAME --version CHART_VERSION

To install the latest version of a chart:

helm install oci://docker.cloudsmith.io/OWNER/REPOSITORY/CHART_NAME

Or you can upgrade to the most recent version of a chart if you've already installed:

helm upgrade oci://docker.cloudsmith.io/OWNER/REPOSITORY/CHART_NAME

If you've got a requirements.yaml file in your chart, you can specify this as a dependency:

dependencies:
  - name: CHART_NAME
    version: CHART_VERSION
    repository: NAME

Logging out of Registry

Helm provides a command to logout of OCI-based registries

helm registry logout docker.cloudsmith.io

Provenance

Provenance files allow for verification of both the integrity and source of a Helm chart.

🚧

Provenance files aren't supported for OCI chart uploads yet, but this feature is coming soon. Cloudsmith fully supports both verification and generation of Helm provenance files for non-OCI Helm Charts.

Security Scanning

Supported

Please see our Security Scanning documentation for further information.

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.