Skip to main content
A State Store System is the canonical source for the desired state of your system: configurations, application manifests, and infrastructure definitions. In GitOps workflows this authoritative state is most commonly a Git repository because Git provides provenance, immutability, branching, and pull requests for collaborative change management. However, Git is not the only option. OCI (Open Container Initiative) registries can act as a unified state store for many artifact types used in Kubernetes ecosystems — container images, Helm charts, plain manifests, overlays, policy bundles, and more — letting you reuse the same registry, authentication, and access controls across those artifact types. Why use OCI as a state store?
  • Consolidates multiple artifact types into a single registry.
  • Reuses existing authentication/authorization and lifecycle tooling.
  • Enables GitOps operators (Flux, Argo CD) to pull artifacts from registries that support OCI artifacts.
OCI defines standards for container image formats and runtimes. The OCI Artifact model extends container images so registries can store arbitrary artifact types (images, Helm charts, manifest bundles, policies) as first-class artifacts.
The image explains OCI Artifacts, showing how various data types like images, Helm charts, and Kubernetes manifests are stored and distributed using OCI registries. It includes a diagram illustrating the structure of a registry with different artifact versions.
A single OCI registry can host multiple repositories; each repository can contain multiple artifacts and versions. Common OCI registry providers include GitHub Container Registry, Docker Hub, Azure Container Registry, and Google Artifact Registry. Table: Typical storage locations vs. OCI as a consolidated option Callouts
Using a single OCI registry for multiple artifact types simplifies access management: you can reuse the same credentials, RBAC rules, and audit trails for images, charts, and other artifacts.
Do not embed long-lived credentials in scripts. Prefer short-lived tokens, OIDC-based flows, or CI/CD secret managers. Always revoke or rotate Personal Access Tokens (PATs) used for registry access.
Below are practical examples showing how to push images, Helm charts, and plain Kubernetes manifests into an OCI-compliant registry. The examples use GitHub Container Registry (ghcr.io) but the commands and concepts apply to other OCI registries (Docker Hub, Azure Container Registry, Google Artifact Registry).

​
Pushing container images to an OCI registry

Steps:
  1. Authenticate to the registry (use a Personal Access Token or other secure credentials).
  2. Tag the local image using the registry repository name.
  3. Push the tagged image.
Example (replace <<GITHUB_PERSONAL_ACCESS_TOKEN>> with your token):
Once pushed, Kubernetes workloads (or other consumers) can pull the image using the ghcr.io/sidd-harth/nginx:1.1.0 reference provided they have access.

​
Pushing Helm charts to an OCI registry

Modern Helm supports saving and pushing charts as OCI artifacts. Typical flow:
  1. Create or have a chart (e.g., helm create app1).
  2. Package the chart as a .tgz.
  3. Login to the registry with Helm.
  4. Save/push the chart as an OCI artifact.
Example (replace <<GITHUB_PERSONAL_ACCESS_TOKEN>> with your token):
After pushing, consumers can pull the chart directly from the OCI registry using Helm’s OCI registry support.

​
Publishing plain Kubernetes manifests to an OCI registry (using Flux)

You can package a directory of Kubernetes manifests and push it as an OCI artifact. Flux provides flux push artifact to create a manifest bundle and push it to an OCI registry; a GitOps operator can then reference that bundle. Example using Flux (replace <<GITHUB_PERSONAL_ACCESS_TOKEN>> with your token):
Once the manifest bundle is published, configure your GitOps operator (e.g., Flux or Argo CD) to reference the OCI artifact location and reconciliation will apply those manifests to your cluster.

​
How GitOps operators consume OCI artifacts

  • Argo CD and Flux both support pulling from OCI registries:
    • Argo CD: supports OCI images and some extensions for OCI-based applications.
    • Flux: has first-class support for Kustomization/HelmRepository using oci:// sources and flux push artifact.
  • Typical operator flow: fetch OCI artifact → verify digest/revision → render/apply manifests or charts → report status.

​
Best practices

  • Consolidate related artifacts under predictable repository paths (e.g., ghcr.io/<org>/<app>).
  • Use image and artifact digests (sha256) in production manifests to guarantee immutability.
  • Use short-lived credentials or OIDC where possible; avoid embedding PATs in long-lived scripts.
  • Apply RBAC and least privilege on the registry to limit artifact access.

​
References

That’s all for this lesson.

Watch Video