Flux Mirror

Flux Mirror is a CLI for mirroring Helm charts, OCI artifacts and container images between registries using a declarative approach.

The intended use case is feeding an internal mirror registry that backs Flux OCIRepository and Kubernetes Deployments, so clusters never reach out to upstream registries at reconcile time.

It also enables migration away from HTTP/S HelmRepository sources: chart versions are republished as OCI Helm artifacts that HelmRelease consumes via an OCIRepository in spec.chartRef, dropping the runtime dependency on upstream chart repositories.

Features

• OCI artifacts — mirror container images, OCI Helm charts, Flux OCI artifacts, and any other OCI-addressable artifact between registries. Manifests and blobs are copied byte-for-byte; multi-arch manifest lists are mirrored as a whole, no platform filtering.
• Helm charts — mirror charts from HTTP/S Helm repositories to an OCI registries. Chart bytes are re-published as a deterministic Helm-OCI artifact, so drift detection on re-runs is content-based and stable.
• OCI 1.1 referrers — opt-in mirror of signatures, SBOMs, and attestations attached to artifacts.
• Cosign verification — opt-in keyless signature verification for selected source artifacts before they are mirrored, with optional minimum signature age.
• Selector pipeline — for OCI artifacts, a four-step regex → semver → sort → top-N filter. For charts, a semver constraint plus top-N. Sort by semver, alphabetical, or numerical.
• Idempotent — destination digests are compared per tag/version. Re-runs copy only what’s missing or drifted.
• Drift gating — destination drift (different content under the same tag) is reported as a distinct outcome and exit code, so audit pipelines can differentiate “out of date” from “mutated tags”.
• Registry auth — OCI auth supports Docker config and credential helpers, cloud workload identity for ECR/ACR/GAR, and per-host bearer credentials from GitHub/Forgejo OIDC, GCP, Azure, AWS STS, SPIFFE JWT-SVID, env vars, files, or JWK-signed JWTs. Per-host TLS/mTLS (custom CA, client cert, or SPIFFE X.509-SVID) is also supported. Helm HTTP/S credentials come from Helm’s repositories config.
• Structured output — text and yaml/json for downstream tooling, plus a verbose mode that streams every blob and manifest digest for diagnosing TLS, auth, or push failures.

Install

Install the plugin with the Flux CLI:

flux plugin install mirror

Quickstart

Authenticate once against the destination and optionally source registries:

docker login ghcr.io

For private HTTP/S Helm repositories, login with Helm:

helm repo add private https://charts.example.com --username "$USER" --password "$TOKEN"

Write a config file describing what to mirror:

# flux-mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta1
kind: Config
charts:
  - name: external-dns
    source: https://kubernetes-sigs.github.io/external-dns/
    destination: oci://ghcr.io/my-org/charts
    version: "*"
    limit: 3
artifacts:
  - source: registry.k8s.io/external-dns/external-dns
    destination: ghcr.io/my-org/external-dns
    selector:
      semver: ">=0.15.0"
      limit: 3
    includeReferrers: true

Run the sync:

flux mirror sync flux-mirror.yaml

You can also read the config from stdin:

flux mirror sync - < flux-mirror.yaml

Preview without writing:

flux mirror sync flux-mirror.yaml --dry-run

Force a resync of drifted tags e.g. latest:

flux mirror sync flux-mirror.yaml --overwrite

See examples/ for more configurations and docs/sync.md for the full flag reference.