The OCI Artifact Registry stores and distributes OCI-compliant application configurations, files, and AI models.

Usage restrictions

Container images (including buildx registry caches and attestations) and Helm Charts pushed to the OCI registry address will be rejected. Use the Docker Registry and Helm Registry, respectively.

Artifact Path Rules

Two naming rules are supported when publishing artifacts to a repository:

• Same-name artifact: The artifact path is the same as the repository path, such as oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}.
• Different-name artifact: The repository path is used as a namespace, and the artifact path is repository path/artifact name, such as oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<ARTIFACT_NAME>.

Login

Log in with a CNB access token. To obtain CNB_TOKEN, see Creating an Access Token.

ORAS, Docker Compose, and Docker Model can use credentials stored by Docker:

docker login -u cnb -p "${CNB_TOKEN}" oci.cnb.cool

When using llmman, you can also save the credentials with its login command:

llmman login oci.cnb.cool -u cnb -p "${CNB_TOKEN}"

Publish Generic OCI Artifacts with ORAS

Local CLI

ORAS can package a local file or directory and publish it to the OCI Artifact Registry:

oras push \
  oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<ARTIFACT_NAME>:latest \
  <PATH_TO_ARTIFACT>

Pull the artifact:

oras pull \
  oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<ARTIFACT_NAME>:latest

Cloud Native Build

The following example packages a local file or directory from the repository and pushes it to the CNB OCI Artifact Registry:

.cnb.yml

main:
  push:
    - docker:
        image: ghcr.io/oras-project/oras
      stages:
        - name: oras push
          # <PATH_TO_ARTIFACT> is the path to a local file or directory, such as ./dist
          # <ARTIFACT_NAME> is the artifact name
          script: oras push "${CNB_OCI_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}/<ARTIFACT_NAME>:latest" <PATH_TO_ARTIFACT>

Publish Application Configurations with Docker Compose

Docker Compose versions that support OCI artifacts can package Compose application configurations and publish them to the OCI Artifact Registry.

Local CLI

Run the following command in the directory containing compose.yaml:

docker compose publish \
  oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<APP_NAME>:latest

If the application uses multiple Compose files, merge and publish them together:

docker compose \
  -f compose.yaml \
  -f compose.production.yaml \
  publish --resolve-image-digests \
  oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<APP_NAME>:latest

To use the artifact, add the oci:// prefix to its address:

docker compose \
  -f oci://oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<APP_NAME>:latest \
  up -d

Publishing restrictions

A Compose application cannot be published directly as a portable OCI artifact if it contains host bind mounts, services with only build and no image, or local files referenced through include that have not been published. Publish the service images and referenced Compose configurations first.

Cloud Native Build

The following example packages a Compose application configuration from the repository and pushes it to the CNB OCI Artifact Registry:

.cnb.yml

main:
  push:
    - services:
        - docker
      stages:
        - name: docker compose publish
          # <APP_NAME> is the Compose application name
          script: docker compose publish --yes --resolve-image-digests "${CNB_OCI_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}/<APP_NAME>:latest"

Manage Model Artifacts with llmman

llmman can package models such as GGUF and safetensors as OCI artifacts that conform to the CNCF Model Format and push them to the CNB OCI Artifact Registry.

Local CLI

Package a local model directory and push it to CNB:

llmman build \
  --tag oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest \
  <MODEL_DIR>

llmman push \
  oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest

Pull and run the model:

llmman pull "oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest"
llmman run "oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest" "Introduce yourself in one sentence"

Cloud Native Build

The following example packages a local model directory from the repository and pushes it to the CNB OCI Artifact Registry:

.cnb.yml

main:
  push:
    - docker:
        image: docker.io/ai/llmman:server
      stages:
        - name: llmman login
          script: llmman login "${CNB_OCI_REGISTRY}" -u "${CNB_TOKEN_USER_NAME}" -p "${CNB_TOKEN}"
        - name: llmman build & push
          # <MODEL_DIR> is the model directory, such as ./model
          # <MODEL_NAME> is the model name
          script: |
            llmman build --tag "${CNB_OCI_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest" <MODEL_DIR>
            llmman push "${CNB_OCI_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest"

Manage Model Artifacts with Docker Model

Local CLI

Docker Model can package, push, and pull GGUF models with the docker model command:

docker model package --gguf <MODEL_FILE> \
  --push oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest

docker model pull \
  oci.cnb.cool/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest

Cloud Native Build

The following example packages a GGUF model file from the repository and pushes it to the CNB OCI Artifact Registry:

.cnb.yml

main:
  push:
    - services:
        - docker
      stages:
        - name: docker model package & push
          # <MODEL_FILE> is the model file path, such as ./model.gguf
          # <MODEL_NAME> is the model name
          script: docker model package --gguf <MODEL_FILE> --push ${CNB_OCI_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}/<MODEL_NAME>:latest

Previous pageHelm Artifact Registry

Next pageMaven Artifact Registry