This feature is experimental and it’s subject to change.

Container images repositories are expected to be hosted in OCI registries. Each repository represents one package in Artifact Hub, and multiple versions of that package will be created from each of the tags configured when the repository is added. The repository name in the url will be used as the package name. At the moment tags have to be configured manually from the control panel, and they can be marked as mutable or immutable. Immutable tags will be only processed once, whereas mutable ones will be processed periodically and reindexed when they change. A repository can have a maximum of 10 tags listed. In some cases, adding a single mutable tag like latest will be enough to have presence on Artifact Hub. We have plans to add a new API endpoint that will allow publishers to push tags programatically as needed replacing old ones.

To add a container image repository, the url used must follow the following format:

• oci://registry/[namespace]/repository (example: oci://index.docker.io/artifacthub/ah)

The registry host is required, please use index.docker.io when referring to repositories hosted in the Docker Hub. The url should not contain any tag.

For an image tag to be listed on Artifact Hub, it must contain some metadata. Depending on the image manifest format, metadata must be provided one way or another: images using OCI manifests must use annotations, whereas images using Docker V2 manifests must use config labels. Docker V1 manifests are not supported.

The following annotations/labels are supported at the moment:

(all must be provided as strings)

You can add annotations and labels to your images at build time (by using podman, buildah or docker), or later at any time by mutating the image with tools like crane:

crane mutate \
    --label org.opencontainers.image.description='Artifact Hub command line tool' \
    --label org.opencontainers.image.version='1.6.0' \
    --label org.opencontainers.image.created='2022-02-08T15:38:15Z' \
    --label org.opencontainers.image.documentation='https://artifacthub.io/docs/topics/cli' \
    --label org.opencontainers.image.source='https://github.com/artifacthub/hub/tree/c2a6e0866ab13422221f2f458026b4506acd6b53/cmd/ah' \
    --label org.opencontainers.image.vendor='Artifact Hub' \
    --label io.artifacthub.package.readme-url='https://raw.githubusercontent.com/artifacthub/hub/c2a6e0866ab13422221f2f458026b4506acd6b53/docs/cli.md' \
    --label io.artifacthub.package.maintainers='[{"name":"Artifact Hub maintainers","email":"cncf-artifacthub-maintainers@lists.cncf.io"}]' \
    --label io.artifacthub.package.logo-url='https://raw.githubusercontent.com/artifacthub/hub/master/docs/logo/logo.svg' \
    --label io.artifacthub.package.keywords='artifact hub,cli,lint' \
    --label io.artifacthub.package.license='Apache-2.0' \
    --label io.artifacthub.package.alternative-locations='public.ecr.aws/artifacthub/ah:v1.6.0' \
artifacthub/ah:latest

There is an Artifact Hub repository metadata file named artifacthub-repo.yml, which can be used to setup features like Verified publisher or Ownership claim.

Once your repository metadata file is ready, you can push it to the OCI registry using oras:

oras push \
  registry/namespace/repository:artifacthub.io \
  --config /dev/null:application/vnd.cncf.artifacthub.config.v1+yaml \
  artifacthub-repo.yml:application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml

or you can use regclient to do the same:

regctl artifact put \
  --format '{{ .Manifest.GetDescriptor.Digest }}' \
  --artifact-type application/vnd.cncf.artifacthub.config.v1+yaml \
  -f artifacthub-repo.yml \
  --file-media-type "application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml" \
  registry/namespace/repository:artifacthub.io

The repository metadata file is pushed to the registry using a special tag named artifacthub.io. Artifact Hub will pull that artifact looking for the application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml layer when the repository metadata is needed.

The OCI Artifacts support has been landed on Docker Hub recently, so you can now start publishing your repository metadata file to the Docker Hub without having any problem. You can use the following command to do so:

oras push \
  docker.io/repository:artifacthub.io \
  --config /dev/null:application/vnd.cncf.artifacthub.config.v1+yaml \
  artifacthub-repo.yml:application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml

or you can use regclient to do the same:

regctl artifact put \
  --format '{{ .Manifest.GetDescriptor.Digest }}' \
  --artifact-type application/vnd.cncf.artifacthub.config.v1+yaml \
  -f artifacthub-repo.yml \
  --file-media-type "application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml" \
  docker.io/repository:artifacthub.io

Please note that publishing an Artifact Hub repository metadata file requires that the registry supports OCI artifacts.