# Docker/OCI Image Reference

Key: `technology.development.docker_ref`

OCI container image reference in the form \[registry/\]repository\[:tag\]\[@digest\]. Used in Dockerfiles, Kubernetes manifests, and CI/CD pipelines.

Page: <https://meridian.online/docs/projects/finetype/types/technology/development/docker_ref>

Samples: `nginx:latest`, `ghcr.io/myorg/myapp:v1.2.3`, `docker.io/library/postgres:16-alpine`, `gcr.io/project/service@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890`

## Background

### Origin

The Open Container Initiative was launched on 22 June 2015 by Docker, CoreOS and other leaders in the container industry.[[1]](https://opencontainers.org/about/overview/) The Open Container Initiative maintains three specifications: the Runtime Specification, the Image Specification and the Distribution Specification.[[1]](https://opencontainers.org/about/overview/) The OCI Distribution Specification defines an API protocol to facilitate and standardise the distribution of content.[[2]](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) The OCI Distribution Specification project launched in April 2018 to standardise image distribution around the Docker Registry HTTP API V2 protocol.[[3]](https://opencontainers.org/posts/blog/2021-05-05-oci-dist-spec-v1/)

The Go package github.com/distribution/reference gives the grammar of a reference as a name, an optional colon and tag, and an optional at sign and digest.[[4]](https://pkg.go.dev/github.com/distribution/reference) In the distribution/reference grammar, a name is an optional domain followed by a slash and then a remote name, and a domain is a host with an optional port number.[[4]](https://pkg.go.dev/github.com/distribution/reference) The distribution/reference package sets RepositoryNameTotalLengthMax, the maximum total number of characters in a repository name, to 255.[[4]](https://pkg.go.dev/github.com/distribution/reference) The OCI Distribution Specification describes a digest as a unique identifier created from a cryptographic hash of a blob's content.[[2]](https://github.com/opencontainers/distribution-spec/blob/main/spec.md)

### Use

Docker's documentation gives the image name format as \[HOST\[:PORT\]/\]NAMESPACE/REPOSITORY\[:TAG\].[[5]](https://docs.docker.com/reference/cli/docker/image/tag/) Kubernetes documentation gives busybox as equivalent to docker.io/library/busybox:latest.[[6]](https://kubernetes.io/docs/concepts/containers/images/)

Kubernetes documentation says tags can be moved to point to different images, but digests are fixed.[[6]](https://kubernetes.io/docs/concepts/containers/images/) Kubernetes documentation advises avoiding the :latest tag when deploying containers in production.[[6]](https://kubernetes.io/docs/concepts/containers/images/) Kubernetes documentation says that when an image name carries both a tag and a digest, only the digest is used for pulling.[[6]](https://kubernetes.io/docs/concepts/containers/images/)

### Where you'll meet it

GitHub's Container registry is served at ghcr.io, and GitHub's documentation pushes images with references of the form ghcr.io/NAMESPACE/IMAGE\_NAME:latest.[[7]](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) GitHub's Container registry documentation pulls images by digest with references of the form ghcr.io/NAMESPACE/IMAGE\_NAME@sha256: followed by the hash.[[7]](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)

## Sources

1. [About the Open Container Initiative](https://opencontainers.org/about/overview/) — organisation
2. [distribution-spec/spec.md at main · opencontainers/distribution-spec · GitHub](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) — standard
3. [OCI Distribution Specification v1.0 - Open Container Initiative](https://opencontainers.org/posts/blog/2021-05-05-oci-dist-spec-v1/) — organisation
4. [reference package - github.com/distribution/reference - Go Packages](https://pkg.go.dev/github.com/distribution/reference) — documentation
5. [docker image tag](https://docs.docker.com/reference/cli/docker/image/tag/) — documentation
6. [Images](https://kubernetes.io/docs/concepts/containers/images/) — documentation
7. [Working with the Container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) — organisation