Flux OCI Source Quick Fix - OCIRepository Configuration

Flux OCIRepository source pulls Kubernetes manifests from OCI-compliant container registries. Misconfigured registry URLs or missing auth cause artifact resolution failures. This guide covers the fix.

Quick Fix

Wrong

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: app-config
spec:
  interval: 5m
  url: oci://ghcr.io/org/app-config:v1.0

The issue: using version tag v1.0 causes Flux to pin to that specific version and never receive updates. Missing secretRef for private registry authentication.

Right

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: app-config
spec:
  interval: 5m
  url: oci://ghcr.io/org/app-config
  ref:
    semver: ">=1.0.0"
  secretRef:
    name: registry-auth
  sourceIndex:
    provider: ghcr

# Expected output after applying the fix
# OCIRepository created with semver range
# Latest matching artifact pulled from ghcr.io
# Authentication via registry-auth secret
# Auto-updates within semver range
# Status: True (Ready)

Prevention

• Use ref.semver instead of tags for automatic updates
• Configure secretRef for private registry authentication
• Use sourceIndex.provider for registry metadata (ghcr, ecr, acr)
• Pin to specific ref.tag for production stability
• Verify OCI artifact exists with crane ls <repository>

DodaTech Tools

Doda Browser's OCI repository browser shows artifact tags and metadata. DodaZIP archives OCI source configurations. Durga Antivirus Pro validates registry URLs.

FAQ