ADR-055: Container image registry and tagging strategy

Category: development Provenance: human

Decision

Publish container images to GitHub Container Registry (ghcr.io). Use semantic version tags (major, minor, patch) plus latest tag. Support multi-arch builds (amd64, arm64).

Rationale

GitHub Container Registry integrates with GitHub Actions, provides free hosting for public images, supports OCI standards. Semantic version tags enable users to pin to specific compatibility levels (major for breaking changes, minor for features, patch for fixes). Latest tag provides convenience for development but should not be used in production. Multi-arch support enables deployment on ARM-based Kubernetes (AWS Graviton, Raspberry Pi clusters). Digest pinning provides immutable image references for GitOps and security compliance. No Docker Hub to avoid rate limits and maintain single source of truth.

Agent Instructions

Primary registry: ghcr.io/vriesdemichael/keycloak-operator. Tagging strategy: latest (tracks main branch), vX (major), vX.Y (minor), vX.Y.Z (patch). Example: v1, v1.2, v1.2.3, latest. Multi-arch: linux/amd64, linux/arm64 via Docker buildx. Images built in GitHub Actions workflow .github/workflows/ci-cd.yml. Release tags trigger semantic version tags. Main branch pushes update latest tag. Use digest pinning in production: image@sha256:... instead of tags for reproducibility.

Rejected Alternatives

Docker Hub as primary registry

Rate limiting on free tier. ghcr.io better integrated with GitHub workflow.

Only latest tag

No way to pin to specific versions. Users can't control upgrade timing. Breaks GitOps version pinning.

Only amd64 architecture

Excludes ARM-based deployments which are increasingly common (cost savings, edge computing).

Quay.io or other registry

Additional external dependency. ghcr.io is free, integrated, and sufficient.