Version: 1.3.0-beta.1

Compatible OCI Registries

This page contains a list of projects leveraging ORAS, as well as registries that are known to support OCI Artifacts.

Note that this list is not comprehensive. Would like your registry and/or project listed here? Please submit an issue or raise a PR directly. We're happy to promote all usage, as well as provide feedback.

Registries supporting OCI Artifacts

CNCF Distribution - local/offline verification
Amazon Elastic Container Registry
Azure Container Registry
Google Artifact Registry
GitHub Packages container registry
Docker Hub
Zot Registry
Red Hat Quay
Artifactory
Harbor

CNCF Distribution

https://github.com/distribution/distribution version 2.7+

CNCF Distribution is a reference implementation of the OCI distribution-spec. Running distribution locally, as a container, provides local/offline verification of ORAS and OCI Artifacts.

Using a local, unauthenticated container registry

Run the docker registry image locally:

docker run -it --rm -p 5000:5000 registry

This will start a distribution server at localhost:5000 (with wide-open access and no persistence outside of the container).

Using Docker Registry with authentication

Create a valid htpasswd file (must use -B for bcrypt):
```
htpasswd -cB -b auth.htpasswd myuser mypass
```

Start a registry using the password file for authentication:

docker run -it --rm -p 5000:5000 \
    -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \
    -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \
    registry

In a new window, login with oras:

oras login -u myuser -p mypass localhost:5000

You will notice a new entry for localhost:5000 appear in ~/.docker/config.json.

To remove the entry from the credentials file, use oras logout:

oras logout localhost:5000

Using an insecure Docker registry

To login to the registry without a certificate, a self-signed certificate, or an unencrypted HTTP connection Docker registry, oras supports the --insecure flag.

Create a valid htpasswd file (must use -B for bcrypt):
```
htpasswd -cB -b auth.htpasswd myuser mypass
```

Generate your self-signed certificates:

$ mkdir -p certs
$ openssl req \
  -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
  -x509 -days 365 -out certs/domain.crt

Start a registry using that file for auth and listen the 0.0.0.0 address:

docker run -it --rm -p 5000:5000 \
    -v `pwd`/certs:/certs \
    -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \
    -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \
    -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 \
    -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
    -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
    registry

In a new window, login with oras using the ip address not localhost:
```
oras login -u myuser -p mypass --insecure <registry-ip>:5000
```

You will notice a new entry for <registry-ip>:5000 appear in ~/.docker/config.json.

Then you can pull files from the registry or push files to the registry.

To push single file to this registry:

oras push <registry-ip>:5000/library/hello:latest hi.txt --insecure

To pull files from this registry:

oras pull <registry-ip>:5000/library/hello:latest --insecure

To remove the entry from the credentials file, use oras logout:
```
oras logout <registry-ip>:5000
```

Using a plain HTTP Docker registry

To pull or push the HTTP Docker registry. oras support --plain-http flag to pull or push.

The --plain-http flag mean that you want to use http instead of https to connect the Docker registry.

Create a valid htpasswd file (must use -B for bcrypt):
```
htpasswd -cB -b auth.htpasswd myuser mypass
```

Start a registry using that file for auth and listen the 0.0.0.0 address:

docker run -it --rm -p 5000:5000 \
  -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \
  -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 \
  registry

In a new window, login with oras using the ip address not localhost:
```
oras login -u myuser -p mypass --insecure <registry-ip>:5000
```

You will notice a new entry for <registry-ip>:5000 appear in ~/.docker/config.json.

Then you can pull files from the registry or push files to the registry.

To push single file to this registry:

oras push <registry-ip>:5000/library/hello:latest hi.txt --plain-http

To pull files from this registry:

oras pull <registry-ip>:5000/library/hello:latest --plain-http

To remove the entry from the credentials file, use oras logout:
```
oras logout <registry-ip>:5000
```

Amazon Elastic Container Registry (ECR)

ECR Artifact Blog Post: OCI Artifact Support in Amazon ECR

Authenticating with ECR using the AWS CLI

aws ecr get-login-password --region $AWS_REGION --profile $PROFILE | oras login \
    --password-stdin \
    --username AWS \
    "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

Pushing Artifacts to ECR

oras push $REPO_URI:1.0 \
    --artifact-type application/vnd.unknown.config.v1+json \
    ./artifact.txt:application/vnd.unknown.layer.v1+txt

Pulling Artifacts from ECR
```
oras pull $REPO_URI:1.0
```

Azure Container Registry (ACR)

ACR Artifact Documentation: aka.ms/acr/artifacts

Authenticating with ACR using Service Principals

oras login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD

Authenticating with ACR using AAD credentials and the az cli
```
az login
az acr login --name myregistry
```

Pushing Artifacts to ACR

oras push myregistry.azurecr.io/samples/artifact:1.0 \
    --artifact-type application/vnd.unknown.config.v1+json \
    ./artifact.txt:application/vnd.unknown.layer.v1+txt

Pulling Artifacts from ACR

oras pull myregistry.azurecr.io/samples/artifact:1.0

Google Artifact Registry (GAR)

Authenticating with GAR using the gcloud command-line tool
```
gcloud auth configure-docker ${REGION}-docker.pkg.dev
```

Pushing Artifacts to GAR

oras push ${REGION}-docker.pkg.dev/${GCP_PROJECT}/samples/artifact:1.0 \
  ./artifact.txt:application/vnd.unknown.layer.v1+txt

Pulling Artifacts from GAR

oras pull ${REGION}-docker.pkg.dev/${GCP_PROJECT}/samples/artifact:1.0

GitHub Packages container registry (GHCR)

Authenticating with GHCR

echo $GITHUB_PAT | oras login ghcr.io -u GITHUB_USERNAME --password-stdin

Pushing Artifacts to GHCR

oras push ghcr.io/${GITHUB_OWNER}/samples/artifact:1.0 \
  ./artifact.txt:application/vnd.unknown.layer.v1+txt

Pulling Artifacts from GHCR

oras pull ghcr.io/${GITHUB_OWNER}/samples/artifact:1.0

Docker Hub

Authenticating with Docker Hub

echo $ACCESS_TOKEN | docker login -u $DH_USER --password-stdin

Pushing Artifacts to Docker Hub

oras push docker.io/${DH_USER}/artifact:1.0 \
  ./artifact.txt:application/vnd.unknown.layer.v1+txt

Pulling Artifacts from Docker Hub

oras pull docker.io/${DH_USER}/artifact:1.0

Zot Registry

Authenticating with Zot Registry

echo $ZR_PASSWORD | oras login <registry-ip>:5000 -u $ZR_USER --password-stdin

Pushing Artifacts to Zot Registry

oras push --plain-http <registry-ip>:5000/hello-artifact:v2 \
      --config config.json:application/vnd.acme.rocket.config.v1+json \
      artifact.txt:text/plain -d -v

Pulling Artifacts from Zot Registry

oras pull --plain-http <registry-ip>:5000/hello-artifact:v2 -d -v

Red Hat Quay

Authenticating to quay.io using a Robot Account and Token

echo $TOKEN | oras login -u $ROBOT_ACCOUNT --password-stdin quay.io

Pushing an artifact to quay.io

oras push quay.io/$USER/$REPOSITORY/myartifact:v1 --artifact-type application/text ./myartifact.txt

Pulling an artifact from quay.io

oras pull quay.io/$USER/$REPOSITORY/myartifact:v1

Artifactory

Authenticating with Artifactory

echo $ARTIFACTORY_PAT | oras login artifactory.your-company.com -u ARTIFACTORY_USERNAME --password-stdin

Pushing an artifact to Artifactory

oras push artifactory.your-company.com/$ARTIFACTORY_OCI_REPOSITORY/myartifact:v1 --artifact-type application/text ./myartifact.txt

Pulling an artifact from Artifactory

oras pull artifactory.your-company.com/$ARTIFACTORY_OCI_REPOSITORY/myartifact:v1

Harbor

Authenticating with Harbor

echo $HARBOR_PASSWORD | oras login <registry-ip>:5000 -u $HARBOR_USER --password-stdin

Pushing Artifacts to Harbor registry

oras push --plain-http <registry-ip>:5000/hello-artifact:v2 \
      artifact.txt:text/plain

Pulling Artifacts from Harbor registry

oras pull --plain-http <registry-ip>:5000/hello-artifact:v2

Registries supporting OCI Artifacts​

CNCF Distribution​

Using a local, unauthenticated container registry​

Using Docker Registry with authentication​

Using an insecure Docker registry​

Using a plain HTTP Docker registry​