Distributing OCI Artifacts to Remote Registries

Remote OCI registries allow you to share container images and other artifacts. There are many public and private remote registries available, but this example uses GitHub Container Registry (GHCR). This document covers the steps you need to preform to share artifacts on a remote registry. You may also experiment with ORAS using a local container registry on your computer.

Authentication

Most remote registry will require you to authenticate before you can push or pull artifacts. The oras login command is used for authentication.

On GHCR, you can get an authentication token by going to user Settings, Developer Settings, Personal Access Tokens, and Tokens (classic). GHCR currently only supports classic tokens for authentication. Click on Generate New Token (classic) and allow read, write and delete packages. Copy the generated token and set it to an environment variable. The URL for GHCR is ghcr.io.

GHCR_USER='my_github_username'
GHCR_TOKEN='ghp_MYTOKEN'
echo "${GHCR_TOKEN}" | oras login --username "${GHCR_USER}" --password-stdin ghcr.io

Create an artifact

An artifact shared on a registry could be a container image, helm chart or just a simple file. This example will use a simple file:

echo "hello world" > artifact.txt

Push the artifact

The oras push is used to push artifacts to registries.

oras push ghcr.io/${GHCR_USER}/my-repository:v1 artifact.txt

The output will look something like this:

✓ Uploaded  application/vnd.oci.empty.v1+json                                                                2/2  B 100.00%  913ms
  └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
✓ Uploaded  artifact.txt                                                                                   12/12  B 100.00%  912ms
  └─ sha256:a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447
✓ Uploaded  application/vnd.oci.image.manifest.v1+json                                                   591/591  B 100.00%  717ms
  └─ sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6
Pushed [registry] ghcr.io/my_github_username/my-repository:v1
ArtifactType: application/vnd.unknown.artifact.v1
Digest: sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6

Pull the artifact

Use the oras pull command to download the artifact.

oras pull ghcr.io/${GHCR_USER}/my-repository:v1

The output will look something like this:

✓ Pulled      artifact.txt                                                                                 12/12  B 100.00%    2ms
  └─ sha256:a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447
✓ Pulled      application/vnd.oci.image.manifest.v1+json                                                 591/591  B 100.00%  329µs
  └─ sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6
Pulled [registry] ghcr.io/my_github_username/my-repository:v1
Digest: sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6

The file will be recreated if you deleted it:

% cat artifact.txt 
hello world
% 

Referencing an artifact

Use the oras attach command to add a reference to another artifact.

oras attach ghcr.io/${GHCR_USER}/my-repository:v1 --artifact-type 'doc/example' --annotation 'key=val' ref-artifact.txt 

The output will look something like this:

✓ Uploaded  ref-artifact.txt                                                                                           13/13  B 100.00%  490ms
  └─ sha256:9e820c753b29c9ea7b85a7d1b9d88107330d625546c216facba451effe1b8dbd
✓ Exists    application/vnd.oci.empty.v1+json                                                                            2/2  B 100.00%     0s
  └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
✓ Uploaded  application/vnd.oci.image.manifest.v1+json                                                               746/746  B 100.00%  930ms
  └─ sha256:a461956f5500056ca03ee325c4c607ef421dfff6ad1902eeb2da67686c62004b
Attached to [registry] ghcr.io/my_github_username/my-repository@sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6
Digest: sha256:a461956f5500056ca03ee325c4c607ef421dfff6ad1902eeb2da67686c62004b

View referrers

Use oras discover to view referrers.

oras discover ghcr.io/${GHCR_USER}/my-repository:v1

The output will look something like this:

ghcr.io/my_github_username/my-repository@sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6
└── doc/example
    └── sha256:a461956f5500056ca03ee325c4c607ef421dfff6ad1902eeb2da67686c62004b