Flux – Flux Mirror

Flux: Flux Mirror Config

Mon, 01 Jan 0001 00:00:00 +0000

The Config API defines what flux mirror mirrors and how it authenticates to the registries involved. A single config lists the registry hosts to authenticate, the OCI artifacts to copy between OCI registries, and the Helm charts to pull from HTTP/S Helm repositories and publish to an OCI registry. Config files support ${VAR} environment substitution in field keys and values; every referenced environment variable must be set when the config is loaded. Use the global --no-envsubst flag to disable substitution and parse ${VAR} strings literally.

Sources can be OCI registries or HTTP/S Helm repositories; destinations are always OCI registries.

The config shape is published as a JSON Schema in config-v1beta2.json; the deprecated config-v1beta1.json remains published for existing configs. It is consumed by flux mirror sync, flux mirror login, and flux mirror secret.

Example

The following config mirrors a container image and a Helm chart, and authenticates to the destination registry with a per-host credential:

apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
artifacts:
 - source: docker.io/stefanprodan/podinfo
 destination: quay.io/my-org/podinfo
 selector:
 semver: "6.x"
 limit: 2
 includeReferrers: true
 verify:
 provider: cosign
 minAge: 48h
 matchOIDCIdentity:
 - issuer: https://token.actions.githubusercontent.com
 subject: ^https://github\.com/stefanprodan/.*$
charts:
 - name: podinfo
 source: https://stefanprodan.github.io/podinfo
 destination: oci://quay.io/my-org/charts
 version: "6.x"
 limit: 2
hosts:
 - host: quay.io
 credential:
 username: 'my-org+robot-user'
 value: ${QUAY_TOKEN}

In the above example:

The image at docker.io/stefanprodan/podinfo is mirrored to quay.io/my-org/podinfo. The two highest 6.x tags are selected, their cosign signatures, SBOMs, and attestations are mirrored alongside them, and each tag is verified against the listed GitHub Actions OIDC identity (and required to be at least 48h old) before it is copied.
The podinfo Helm chart is pulled from the HTTP/S repository at https://stefanprodan.github.io/podinfo and published as an OCI Helm chart to quay.io/my-org/charts/podinfo. The two highest 6.x versions are mirrored.
Requests to quay.io authenticate with the Quay robot token read from the QUAY_TOKEN environment variable, presented as a username/password pair because credential.username is set.

You can run this with:

flux mirror sync ./config.yaml

Writing a Config spec

A config is a single YAML document with apiVersion: mirror.plugin.fluxcd.io/v1beta2, kind: Config, and any of the artifacts, charts, and hosts lists.

At least one artifacts or charts entry is required, except for flux mirror login and flux mirror secret, which read only the hosts section and accept a hosts-only config.

API version

mirror.plugin.fluxcd.io/v1beta2 is the current apiVersion. The previous mirror.plugin.fluxcd.io/v1beta1 is deprecated: a config that still declares it still loads (it is converted to v1beta2 in memory), but prints a migration warning. v1beta2 is a breaking change that adds an optional credential.type (defaults to jwt), renames the credential claims (aud→audiences, iss→issuer, sub→subject, exp→expiration), moves hosts[].username under credential, renames the SPIFFE credential provider (jwt-svid→spiffe), and replaces the .tls serverAuth/clientAuth blocks with .tls.path (a directory), inline .ca.crt, .tls.crt, and .tls.key values, or .tls.spiffe.serverIDs (SPIFFE mutual TLS). Update the apiVersion and the renamed fields to silence the warning. Inline v1beta1 .tls values and SPIFFE serverAuth with clientAuth: x509-svid convert automatically; per-file paths, one-sided SPIFFE, and authorizeAny fail with a migration error and must be rewritten as .tls.path, inline certificate fields, or .tls.spiffe.

Artifacts

.artifacts is an optional field that lists OCI artifacts to mirror between OCI registries. The manifest and every referenced blob are copied byte-for-byte, preserving digests; multi-arch images are mirrored faithfully as manifest lists, with no platform filtering.

An entry handles any OCI-addressable content: container images, OCI Helm charts, Flux OCI artifacts, or anything else stored in an OCI registry. To mirror a Helm chart that is published to an HTTP/S Helm repository (and not yet in an OCI registry), use .charts instead.

Each entry has two required fields:

.source, the OCI repository the artifact is pulled from, written without a scheme (e.g. ghcr.io/fluxcd/flux-cli).
.destination, the OCI repository the artifact is pushed to, written without a scheme. Selected tags are mirrored to the same tag at the destination.

It also has optional fields documented below: .selector ( Tag selection), .includeReferrers ( Referrers), .verify ( Signature verification), .overwrite and .ignoreDriftForExitCode ( Overwrite and drift behavior).

artifacts:
 - source: ghcr.io/fluxcd/flux-cli
 destination: quay.io/example/flux-cli
 selector:
 semver: ">=2.7.0 <3.0.0"
 limit: 10
 includeReferrers: true
 ignoreDriftForExitCode: true

Tag selection

.artifacts[].selector is a required field that decides which tags of the source repository are mirrored. It runs as a four-step pipeline — a regex prefilter, a semver range filter, a sort, then a limit — always ordering highest first and keeping the top N. The field offers the following subfields:

.regex, an optional Go regular expression prefilter applied to every tag before the sort and semver steps. It has a required .pattern (tags that do not match are dropped) and an optional .extract replacement string referencing named capture groups (e.g. $version). When .extract is set, the extracted value — not the raw tag — is used as the comparison key, so tags with prefixes or suffixes can still feed into a semver or numerical sort.
.semver, an optional semver range (e.g. >=2.7.0 <3.0.0 or 6.x). Tags whose comparison key is not a valid semantic version are dropped.
.sortBy, the sort strategy. The default is semver.
.limit, how many tags to mirror, taken from the top of the sorted result. It defaults to 1; 0 disables the cap and mirrors every matching tag.

The supported sort strategies are:

semver parses each tag as a semantic version and orders by semver precedence. Tags that do not parse are silently dropped; use .regex to control what qualifies.
alphabetical orders tags lexicographically. This suits tags shaped like RELEASE.2024-11-12T08-30-15Z, where lexical order matches chronological order.
numerical parses each tag as a number and orders numerically. Tags that do not parse are silently dropped; this is typically paired with .regex to extract a numeric portion from a composite tag.

For example, to select the highest five tags by an embedded timestamp:

selector:
 regex:
 pattern: '^.+-[0-9a-f]+-(?P<ts>\d+)$'
 extract: '$ts'
 sortBy: numerical
 limit: 5

Referrers

.artifacts[].includeReferrers is an optional field that, when true, also mirrors the referrers of each selected tag — cosign signatures, SBOMs, and attestations attached via the OCI 1.1 referrers API. It defaults to false.

Signature verification

.artifacts[].verify is an optional field that verifies the source artifact’s signature before any tag is copied. Every selected tag is verified at plan time; if a selected tag has no matching valid signature, planning fails for that entry and no copy job is scheduled. The field offers three subfields:

.provider, the verification provider. It must be cosign. Verification uses Cosign keyless bundles attached to the source artifact as OCI referrers, so the signing side must publish them as referrers.
.matchOIDCIdentity, a list of accepted Fulcio certificate identities. Each entry provides an .issuer (the OIDC issuer URL, e.g. https://token.actions.githubusercontent.com) and a .subject (a Go regular expression matched against the certificate subject alternative name). The entries are evaluated in an OR fashion: a signature is accepted when any one identity matches.
.minAge, an optional duration that requires a signature to be at least this old, measured from its verified transparency-log (Rekor) integrated timestamp. Tags whose signatures are valid but too recent are reported as skipped (reason signature-too-new) and not copied; signatures without an enforceable verified integrated timestamp fail verification. Use this to let signatures settle in the transparency log before mirroring.

artifacts:
 - source: ghcr.io/stefanprodan/podinfo
 destination: quay.io/my-org/podinfo
 selector:
 semver: "*"
 limit: 1
 includeReferrers: true
 verify:
 provider: cosign
 minAge: 168h # 7 days
 matchOIDCIdentity:
 - issuer: https://token.actions.githubusercontent.com
 subject: ^https://github\.com/stefanprodan/.*$

Charts

.charts is an optional field that lists Helm charts to mirror from an HTTP/S Helm repository to an OCI destination. For each selected version, the chart .tgz is downloaded from the source and re-published to the destination as a Helm OCI artifact (a config blob with the chart metadata and a layer with the tarball bytes). Charts use the same outcomes and overwrite/dry-run semantics as artifacts; drift is detected by comparing the source tarball’s content digest against the destination chart-layer digest, so re-runs against an unchanged source are idempotent.

Each entry offers the following subfields:

.name, the chart name within the source repository. Required.
.source, the HTTP/S Helm repository URL the chart is pulled from. Required; the scheme must be http or https, and the repository must serve a classic index.yaml plus chart tarballs.
.destination, the OCI base URL the chart is published to. Required; the scheme must be oci.
.version, an optional semver range (e.g. >=2.7.0 <3.0.0). Versions outside the range are dropped. It defaults to * (all versions).
.limit, how many matching versions to mirror, highest first. It defaults to 1; 0 disables the cap.
.overwrite, see Overwrite and drift behavior.

Helm repository authentication is not configured under hosts. It is loaded automatically from the ambient Helm repositories config — Helm’s default repositories.yaml, or $HELM_REPOSITORY_CONFIG when set — so adding the repository with helm repo add is enough for flux mirror to pick up matching credentials. To mirror a chart that already lives in an OCI registry, list it under .artifacts instead, where it is copied OCI-to-OCI as a plain OCI artifact (authenticated through hosts).

The chart .name is appended to .destination automatically: for destination: oci://quay.io/example/charts and name: nginx, versions land at quay.io/example/charts/nginx:<version>. Because OCI tags do not accept +, semver build metadata (e.g. 1.2.3+meta) is encoded with _ in the destination tag (1.2.3_meta); listing and comparison treat both forms as the same version.

charts:
 - name: nginx
 source: https://charts.example.com
 destination: oci://quay.io/example/charts
 version: ">=15.0.0 <16.0.0"
 limit: 5

Hosts

.hosts is an optional field that configures per-host authentication for OCI registry requests, covering both source pulls and destination pushes. A host listed here takes priority over the ambient Docker config; requests to hosts that are not listed fall back to the Docker config and its credential helpers (~/.docker/config.json, or $DOCKER_CONFIG when set).

Note: the hosts section does not apply to HTTP/S Helm repositories (.charts[].source), which authenticate through the ambient Helm repositories config.

Each entry has one required field, .host, the registry host (with optional port) the entry applies to (e.g. registry.example.com or localhost:5000). A host may appear more than once only when the entries are split by .direction; overlapping entries are rejected. Beyond that, an entry configures a .credential and/or a .tls block, or a cloud .provider. A cloud provider is mutually exclusive with tls, because a cloud registry is managed and its transport is not customized; the default generic provider is an ordinary registry and composes with both. A cloud provider may also carry a credential: its identity is then exchanged for the cloud provider’s registry credentials instead of using the ambient cloud identity. .maxChunkSize tunes blob uploads independently of auth. At least one of credential, a cloud provider, tls, or maxChunkSize must be set.

hosts:
 # A per-host credential (HTTP-layer token).
 - host: registry.example.com
 credential:
 provider: github
 # A cloud registry provider, via ambient workload identity.
 - host: 123456789012.dkr.ecr.us-east-1.amazonaws.com
 provider: ecr
 # A cloud registry provider authenticated with a GitHub credential.
 - host: myregistry.azurecr.io
 provider: acr
 acr:
 tenantID: ${AZURE_TENANT_ID}
 clientID: ${AZURE_CLIENT_ID}
 credential:
 provider: github
 audiences:
 - api://AzureADTokenExchange

Host direction

.hosts[].direction limits an entry to one side of a mirror:

both (default) applies the entry to source pulls and destination pushes.
source applies it only to source pulls.
destination applies it only to destination pushes.

This is what lets the same registry host carry different credentials for the source and destination, for example when copying between two repositories on ghcr.io.

hosts:
 - host: ghcr.io
 direction: source
 credential:
 value: ${LEGACY_GHCR_TOKEN}
 - host: ghcr.io
 direction: destination
 credential:
 provider: github

Per-host credential

.hosts[].credential configures an HTTP-layer registry credential for the host. .type is optional and selects the credential material. It defaults to jwt; only jwt is supported today, with x509 reserved for a future release. Exactly one token source subfield selects how the credential is obtained:

.provider, mints a fresh, per-request credential for the audiences using a cloud, CI, or SPIFFE identity, then caches and refreshes it on demand. One of github, forgejo, gcp, azure, aws, or spiffe — see Token providers for what each obtains and what the registry must accept.
.value, sends the JSON Web Token configured inline as-is (e.g. a GitLab CI/CD id_token). Use ${VAR} to substitute it from the environment while loading the config.
.fromPath, sends the token read from the file at the path, with surrounding whitespace trimmed. The file is re-read on every request, so the token can be rotated without restarting (useful for a projected ServiceAccount token).
.jwkPath, signs a fresh JWT per request with the private JSON Web Key in the file at the path. The key may be a bare JWK or a single-key JWK set ({"keys":[...]}), and its kid is carried in the JWT header. Generate a key pair with flux mirror keygen.
.jwkValue, signs a fresh JWT per request with the private JSON Web Key configured inline. Use ${VAR} to substitute it from the environment while loading the config.

The signed and minted sources take additional claim subfields:

.issuer and .subject, the issuer and subject claims. Both are required with .jwkPath or .jwkValue, and not allowed with the other sources.
.audiences, the audience claim as a list. Allowed with .jwkPath, .jwkValue, or .provider, and defaults to the host. The audience pins the credential to a specific registry, so it must match what the registry (or the cloud identity provider) expects. On a cloud provider host, an unset .audiences uses the cloud provider’s own default (sts.amazonaws.com for ECR, api://AzureADTokenExchange for ACR) instead of the host. Every source accepts multiple values except the gcp and azure providers, which mint a token with a single aud and therefore reject a list longer than one.
.expiration, the signed JWT lifetime, as a duration. Allowed only with .jwkPath or .jwkValue — the sources whose lifetime flux mirror controls — and defaults to 60s. A longer-lived token is cached and re-minted at half its lifetime. Every other source’s lifetime is fixed by its issuer.

Two subfields apply to every token source:

.envelope, an optional Go template applied to the resolved credential just before it is sent to the registry, for registries that expect the token in a specific serialized form. The template data is a single .Token field holding the credential, and two functions are available: base64 (standard base64) and hex (lowercase hexadecimal). For example, envelope: "token-{{ hex .Token }}" sends the hex-encoded credential with a token- prefix. The envelope applies to both transport styles: it transforms the bearer token, or the password when .credential.username is set. An unset envelope sends the credential unchanged.
.username, controls how the resolved credential is transported, and therefore what the registry must accept — see Bearer token vs. username/password.

Token providers

When .credential.provider is set, the credential is obtained from the provider’s ambient identity for the audiences (defaulting to the host). This is what the registry on the other side has to accept:

github and forgejo request an OIDC ID token from the CI Actions OIDC endpoint (ACTIONS_ID_TOKEN_REQUEST_URL / ACTIONS_ID_TOKEN_REQUEST_TOKEN). The registry must trust the GitHub/Forgejo Actions issuer and match the token’s audience and subject (e.g. repo:my-org/my-repo:ref:refs/heads/main). On a cloud provider host (ecr, acr, or gar), the same token is instead exchanged with the cloud provider for registry credentials, so the cloud identity provider must trust the GitHub/Forgejo Actions issuer. The two mint tokens the same way today but are kept distinct so each platform can diverge. Each audience is sent as a repeated audience query parameter; how the endpoint folds them into the token is up to the provider.
gcp obtains a Google ID token for the audience via Application Default Credentials (the GKE/GCE metadata server, a service account key, or workload identity federation). The registry must trust Google’s OIDC issuer and the configured audience. User credentials (authorized_user, e.g. from gcloud auth application-default login) cannot mint a token for a custom audience: with .audiences set the run fails, and with .audiences unset it falls back to the default-audience ID token carried in the ADC response, whose audience is the gcloud OAuth client ID and whose identity is the signed-in user.
azure obtains a Microsoft Entra ID access token via the default Azure credential chain (AKS/managed identity, workload identity federation, environment credentials). The audience is requested as the <aud>/.default scope, so .audiences must contain a single application ID URI (or client ID) of a registered Entra application the registry validates tokens against.
aws is not an OIDC token. AWS mints no JWT, so flux mirror signs an sts:GetCallerIdentity request with the ambient role credentials (IRSA, EC2 instance role, environment, …) and wraps it in a JWT-shaped envelope whose header is {"alg":"none","typ":"aws-sigv4-getcalleridentity"}. The audiences are carried as signed X-Audience header values, not as an OIDC audience claim: the registry accepts the request only if the signed list contains an identity it recognizes, so a single audience ties the request to that one registry while several authorize each registry listed. The registry verifies the caller by replaying the signed request to AWS STS and reading the returned account/ARN, so the destination must understand this scheme — a plain OIDC registry will not.
spiffe fetches a JWT-SVID from the SPIFFE Workload API (SPIFFE_ENDPOINT_SOCKET) for the audiences and sends it as the credential. The extra audiences are carried as additional JWT-SVID audiences. The registry must trust the SPIFFE trust domain’s JWT bundle. On a cloud provider host, the JWT-SVID is exchanged with the cloud provider, which must trust the SPIFFE trust domain. This is the HTTP-layer counterpart to the transport-layer SPIFFE X.509-SVID mTLS configured under .tls; the two are independent.

Resolving file paths

.fromPath, .jwkPath, and the .tls.path directory are resolved relative to the config file’s directory, and a config may only reference files under its own directory tree. When the config is read from stdin (-f -), the process working directory is used as the confinement root instead.

Bearer token vs. username/password

.credential.username controls how the resolved credential is transported, and therefore what the registry on the other side must accept:

credential.username unset (default) — the credential is treated as a bearer token. sync sends it as an HTTP Bearer credential on every request, with no auth challenge, and login/secret write it to the Docker config’s registrytoken field. This suits registries that natively validate an OIDC token (or another self-contained bearer credential). registrytoken is understood by go-containerregistry (crane, and Flux’s OCIRepository/HelmRepository), but not by kubelet image pulls. Because credential helpers only store username/secret pairs, a registrytoken is always written to the config file, never to a keychain helper.
credential.username set — the credential becomes the password of a username/password pair. sync goes through the standard registry auth challenge (credentials are exchanged at the token endpoint, like the cloud providers), and login/secret write username/password/auth. Use this for registries such as Docker Hub, GHCR, and Quay, which expect a username/password login even when the username is a placeholder the registry ignores.

Choose credential.username deliberately: set it when the registry expects a username/password login (or the credential will be consumed by kubelet), and leave it unset when the registry validates a self-contained bearer token.

Cloud registry providers

.hosts[].provider selects how the host’s registry credentials are obtained. It defaults to generic, an ordinary registry for which credential and/or tls configure the connection directly. The other values authenticate the host with a cloud registry provider’s workload identity — the same mechanism the flux push artifact family uses — and obtain the registry’s native credentials directly. A cloud provider is mutually exclusive with tls; it composes with a credential, whose identity is exchanged for the cloud provider’s registry credentials instead of using the ambient cloud identity. The supported values are:

generic (default), an ordinary registry whose authentication is configured through credential and/or tls. It is the implicit value when provider is omitted, and composes with both.
ecr, for Amazon ECR. It uses the AWS credential chain (IRSA, EC2 instance role, environment, SSO), reading the region from the host. With a credential, the identity is exchanged via AssumeRoleWithWebIdentity (set .audiences to the role’s expected audience, typically sts.amazonaws.com, and grant the role trust to the credential issuer).
acr, for Azure ACR. It uses the default Azure credential chain (managed identity, workload identity, environment, …). With a credential, the identity is exchanged as a client assertion, typically with the api://AzureADTokenExchange audience.
gar, for Google GAR. It uses Google Application Default Credentials. With a credential, the identity is exchanged through Google Workload Identity Federation.

When a cloud provider carries a credential, the matching .ecr, .acr, or .gar block is required:

.ecr.roleARN is the IAM role assumed with the credential identity via AssumeRoleWithWebIdentity. The region is derived from the ECR host, as in the rest of Flux. .ecr.stsEndpoint optionally overrides the STS endpoint.
.acr.tenantID and .acr.clientID identify the Microsoft Entra application used as the client assertion.
.gar.workloadIdentityProvider is the workload identity pool provider resource name; .gar.gcpServiceAccount optionally impersonates a service account. The built-in GKE workload identity pool only trusts GKE ServiceAccount tokens, so an external credential provider always needs an explicit .gar block.

hosts:
 - host: 123456789012.dkr.ecr.us-east-1.amazonaws.com
 provider: ecr
 ecr:
 roleARN: arn:aws:iam::123456789012:role/flux-mirror
 # stsEndpoint: https://sts.us-east-1.amazonaws.com
 credential:
 provider: github
 audiences:
 - sts.amazonaws.com
 - host: myregistry.azurecr.io
 provider: acr
 acr:
 tenantID: ${AZURE_TENANT_ID}
 clientID: ${AZURE_CLIENT_ID}
 credential:
 provider: forgejo
 - host: us-docker.pkg.dev
 provider: gar
 gar:
 workloadIdentityProvider: projects/123/locations/global/workloadIdentityPools/gh/providers/gh
 # gcpServiceAccount: flux-mirror@my-project.iam.gserviceaccount.com
 credential:
 provider: github

The cloud providers’ resolved credentials are presented to the registry as a username/password pair through the standard registry auth challenge, and written as username/password/auth by login and secret.

Transport TLS

.hosts[].tls configures transport-layer TLS for the host’s registry requests, separately from the HTTP-layer credential. It is applied by sync (which connects to the registry); login and secret do not open registry connections and ignore it. It is not allowed on a cloud provider host. Exactly one of the following must be set:

.path, a directory laid out like a mounted Flux certSecretRef Secret:
- ca.crt supplies the CA bundle used to verify the registry’s server certificate (one or more concatenated PEM certificates).
- tls.crt and tls.key supply a client certificate and key for mTLS.
At least one of ca.crt or the tls.crt/tls.key pair must be present, and the two files of the pair must be set together. Legacy Flux key names (caFile, certFile, keyFile) are accepted as fallbacks, with the standard names taking precedence. The directory is read with the same key names and validation as the Flux controllers; relative paths are resolved against the config file’s directory and confined within it, exactly like the credential file paths.
inline PEM values, set directly as .ca.crt, .tls.crt, and .tls.key. Use these when the PEM material is already available to the config, for example through ${VAR} substitution, and cannot be mounted as a directory. tls.crt and tls.key must be set together, and at least one of ca.crt or the pair must be present.
.spiffe, SPIFFE mutual TLS. .spiffe.serverIDs is required and lists the registry server identities to authorize. The client X.509-SVID and trust bundle come from the ambient Workload API socket (SPIFFE_ENDPOINT_SOCKET) and rotate automatically.

SPIFFE is always mutual TLS: when .spiffe is set, flux-mirror presents its own X.509-SVID as the client certificate as part of the handshake. The independent server/client halves of earlier revisions are gone, as is client-only SPIFFE.

Each .spiffe.serverIDs entry accepts the SPIFFE ID formats defined by Flux RFC-0014.

hosts:
 # Custom CA for server verification and a static client cert for mTLS.
 - host: registry.example.com
 tls:
 path: ./certs # contains ca.crt, tls.crt, and tls.key

 # CA-only: verify the server with a custom CA, no client certificate.
 - host: ca-only.example.com
 tls:
 path: ./certs/ca-only # contains ca.crt

 # Inline PEM values, e.g. injected from CI secrets.
 - host: inline.example.com
 tls:
 ca.crt: ${REGISTRY_CA_PEM}
 tls.crt: ${REGISTRY_CLIENT_CERT_PEM}
 tls.key: ${REGISTRY_CLIENT_KEY_PEM}

 # SPIFFE mutual TLS: X.509-SVID client cert and SPIFFE server verification.
 - host: spiffe.example.com
 tls:
 spiffe:
 serverIDs:
 - spiffe://example.org/registry  # exact SPIFFE ID
 # - spiffe://example.org/registry/ # any ID under this prefix
 # - spiffe://example.org # any SVID in this trust domain
 # - spiffe://self # any SVID in our own trust domain

Blob upload chunking

.hosts[].maxChunkSize is the maximum size, in KiB (1024 bytes), of a blob-upload PATCH request to this host; larger blobs are split into chunked uploads. It defaults to 0, which disables chunking and sends one monolithic PATCH per blob. Set it for registries or proxies that cap request body sizes.

Working with Config

Overwrite and drift behavior

.artifacts[].overwrite and .charts[].overwrite are optional fields that control what happens when a tag or version already exists at the destination. flux mirror does not overwrite by default, which keeps the safe path the default on immutable registries (ECR with IMMUTABLE tag mutability, GAR with tag immutability, Harbor with retention rules) and avoids redundant writes on mutable ones.

When a tag already exists at the destination, the source and destination digests are compared:

Same digest — skipped silently.
Different digest, overwrite: false — a warning is logged and the tag is left alone, reported as drifted. The mirror has diverged from source but is not brought back in sync without explicit consent.
Different digest, overwrite: true — the new digest is pushed, replacing the destination tag. This fails if the destination registry enforces tag immutability.

The drift warning is useful even on immutable registries where the divergence cannot be resolved automatically: it surfaces in the run output and the exit code, which audit and alerting can hook into. The --overwrite CLI flag forces overwrite: true for every entry, overriding per-entry values, for one-off resyncs.

.artifacts[].ignoreDriftForExitCode is an optional boolean, false by default. When true, drifted tags for that entry are still logged and reported as drifted, but they do not contribute to the drift exit code. If every drifted tag belongs to an entry with ignoreDriftForExitCode: true, the run exits 0 and --drift-exit-code is not applied. Use it for an artifact whose destination is expected to diverge, without muting drift for the rest of the config.

With includeReferrers: true, the same rule applies to referrers. Referrers missing at the destination are always mirrored (there is nothing to overwrite) — the common case when an upstream signature is published after the artifact was first mirrored. Referrers that exist with a different digest are skipped (default) or replaced (overwrite: true).

Defaults

Field	Default
`artifacts[].selector.sortBy`	`semver`
`artifacts[].selector.limit`	`1`
`artifacts[].overwrite`	`false`
`artifacts[].includeReferrers`	`false`
`artifacts[].ignoreDriftForExitCode`	`false`
`artifacts[].verify`	unset
`charts[].version`	`*`
`charts[].limit`	`1`
`charts[].overwrite`	`false`
`hosts[].direction`	`both`
`hosts[].provider`	`generic`
`hosts[].ecr`	unset
`hosts[].acr`	unset
`hosts[].gar`	unset
`hosts[].credential.audiences`	`host`
`hosts[].credential.expiration`	`60s`
`hosts[].credential.envelope`	unset
`hosts[].maxChunkSize`	`0`

A limit of 0 disables the cap and mirrors every matching tag or version. Use it with care: unrestricted mirrors can consume significant bandwidth and storage and may trip rate limits on upstream registries.

Flux: Flux Mirror Sync Command

Mon, 01 Jan 0001 00:00:00 +0000

The flux mirror sync command mirrors Helm charts and OCI artifacts between registries based on a declarative Config. It is idempotent: re-running against the same config produces the same destination state, copying only what is missing or drifted. OCI artifacts are copied by the source digest used for comparison, even if the source tag changes during the operation.

Synopsis

flux mirror sync [CONFIG|-] [flags]

Configuration source

The config path is resolved in the following order:

The first positional argument (- reads the config from stdin).
The FLUX_MIRROR_CONFIG environment variable.

If neither is set, the command errors. Unlike login and secret, sync has no executable-relative default path.

flux mirror sync ./flux-mirror.yaml
flux mirror sync - < ./flux-mirror.yaml
FLUX_MIRROR_CONFIG=./flux-mirror.yaml flux mirror sync

Authentication

sync authenticates OCI registry requests — artifacts source/destination and charts oci:// destinations — per registry host:

Hosts listed under hosts use their configured authentication:
- provider: ecr|acr|gar obtains the registry’s native credentials from the cloud provider’s workload identity. Combined with a credential, it exchanges the credential identity for those credentials instead.
- credential resolves a per-host token from a cloud/CI identity, a JWK signature, or an environment variable or file. With no credential.username it is sent as an HTTP Bearer credential; with credential.username it is the password in the standard registry auth challenge.
Hosts not listed under hosts use the ambient Docker config and credential helpers (~/.docker/config.json, or $DOCKER_CONFIG when set).

A host whose provider is unset or generic may also set tls to configure transport-layer TLS for its registry connections: a directory or inline PEM values with a custom CA and/or client certificate, or SPIFFE mutual TLS.

With the default registry transport, --insecure skips TLS verification for OCI requests, including chart destinations and referrer lookups.

Provider credentials obtained from a cloud registry provider or a credential token source are cached for the duration of the sync run. This avoids minting a new cloud/CI identity token and exchanging it for registry credentials on every request. Use --token-cache-max-size and --token-cache-max-duration to tune the cache, or set the size to 0 to disable it.

HTTP/S Helm repository authentication (for charts sources) is separate from OCI auth and always comes from the ambient Helm repositories config:

Helm’s default repositories.yaml path, or $HELM_REPOSITORY_CONFIG when set.
The username/password, certFile, keyFile, caFile, insecure_skip_tls_verify, and pass_credentials_all fields are honored.

Add repositories with helm repo add and flux mirror picks up matching HTTP/S repository credentials automatically.

Flags

Flag	Default	Description
`-o, --output text\|yaml\|json`	`text`	Output format. `text` is human-friendly; `yaml` and `json` print the structured sync report to stdout.
`--concurrency N`	`4`	Maximum number of copy and tag-planning operations to run in parallel. Must be greater than `0`.
`--retries N`	`3`	Maximum number of retry attempts per job, within the `--timeout` budget. Must be greater than or equal to `0`.
`--timeout DURATION`	`5m`	Per-job total budget covering all retry attempts. Must be greater than `0`.
`--overwrite`	`false`	Force `overwrite: true` on every entry, regardless of per-entry config. See Overwrite and drift behavior.
`--drift-exit-code N`	`2`	Exit code to use when drift is detected without failures (0–255). Set to `0` for immutable destinations that should not fail CI on drift. Drift on entries with `ignoreDriftForExitCode: true` does not trigger it.
`--dry-run`	`false`	Run the plan and comparison pipeline without performing any writes. Reported as `would-copy` / `would-overwrite`.
`--verbose`	`false`	Log every operation and the involved digests on stderr. Suppresses the spinner.
`--no-progress`	`false`	Disable the live progress spinner. Per-job lines and the summary still print.
`--insecure`	`false`	Allow plaintext HTTP and skip TLS verification. Test/dev only.
`--token-cache-max-size N`	`100`	Maximum number of provider credentials cached. Set to `0` to disable the cache.
`--token-cache-max-duration DURATION`	`1h`	Maximum duration a cached provider token is reused before it is refreshed.

Global flags: --timeout sets the default operation timeout, and --no-envsubst disables config environment substitution.

Output

Text mode (default)

✓ ghcr.io/stefanprodan/charts/podinfo:6.10.2 (skipped)
→ localhost:5050/charts/podinfo:6.10.2
✓ ghcr.io/stefanprodan/charts/podinfo:6.11.0 (copied)
→ localhost:5050/charts/podinfo:6.11.0
✗ ghcr.io/stefanprodan/charts/podinfo2 — plan failed: NAME_UNKNOWN
Summary: 1 copied, 1 skipped, 1 failed in 4.2s.

Verbose mode

--verbose replaces the pretty output with a full diagnostic log stream on stderr — every layer push, blob check, manifest digest, referrer fallback-tag update, and registry-side warning. Reach for it when diagnosing TLS, auth, missing-blob, or push-rejection issues.

2026/05/13 09:00:00 sync started entries=3 concurrency=4 retries=3 timeout=5m0s
2026/05/13 09:00:00 mirroring tag src=ghcr.io/foo/bar:1.0 dst=localhost:5050/bar:1.0
2026/05/13 09:00:00 Copying from ghcr.io/foo/bar:1.0 to localhost:5050/bar:1.0
2026/05/13 09:00:00 pushed blob: sha256:fdf53ef8e04176eedbd42713efb2d002f1741c310627b38f444c6f6d92a598f7
2026/05/13 09:00:01 tag done src=ghcr.io/foo/bar:1.0 status=copied elapsed=812ms
…
2026/05/13 09:00:04 sync complete entries=3 copied=1 overwritten=0 skipped=1 drifted=0 failed=1 duration=4.213s

Structured output

-o yaml and -o json print a versioned report to stdout: a top-level envelope (apiVersion, kind, $schema, report) wrapping run metadata (reporter, timestamp, durationMs), an aggregate summary of per-status tag counts, and results[] where each entry carries a status (completed/failed) and a tags[] array of per-tag rows. Every row has a status and, when known, a source digest; skipped rows carry a reason; verified rows carry a verification block; and, with includeReferrers: true, a referrers[] array. The envelope is documented by the sync report schema.

# Status of every tag, per entry
flux mirror sync config.yaml -o json | jq '.report.results[].tags[] | {tag, status}'

# Tags that were copied
flux mirror sync config.yaml -o json | jq '.report.results[].tags[] | select(.status == "copied") | .tag'

# Aggregate counts
flux mirror sync config.yaml -o json | jq '.report.summary'

Status

Each tag row (and each referrer row) lands in exactly one of these statuses:

Status	Meaning
`copied`	Destination did not have the tag; mirrored from source.
`overwritten`	Destination had a different digest; replaced (only with `overwrite: true`).
`skipped`	Nothing was copied; the row’s `reason` says why.
`drifted`	Destination has a different digest, `overwrite: false` — left alone, surfaced in the summary.
`would-copy`	Dry-run forecast: would have been copied.
`would-overwrite`	Dry-run forecast: would have been overwritten.
`failed`	The operation errored; the row’s `error` carries the message.

A skipped row’s reason is either up-to-date (the destination already has the same digest) or signature-too-new (a valid signature deferred by verify.minAge).

A failed signature verification (bad/missing signature, OIDC mismatch) is recorded as a failed tag row carrying the verify error; verification runs at plan time, so the first failure stops the entry (tags verified before it still run) while the entry itself stays completed. A true plan-time failure (e.g. the source registry rejected a ListTags) surfaces as an entry with status: "failed", an error, and an empty tags array, reported live as a ✗ <entry> — plan failed: <err> line. Both kinds count toward failed.

Referrers

When an entry sets includeReferrers: true, each tag row gains a referrers[] array — one row per mirrored sub-artifact (cosign signature bundle, SBOM, attestation), each with its own digest, artifactType, status, and (when skipped) reason. Referrers are evaluated under --dry-run too.

Exit codes

Code	Meaning
`0`	Clean run — every tag was copied or skipped as expected, no drift, no failures.
`1`	At least one tag job failed (network error, push rejected, retries exhausted, plan failure).
`2`	No failures, but at least one tag drifted with `overwrite: false`. The destination is out of date relative to source.

Failures take precedence over drift. --dry-run does not bump the exit code for would-copy / would-overwrite, but drift detection still produces 2 by default. Use --drift-exit-code=0 when the destination registry is known to be immutable and drift should be logged without failing CI.

Drift on an artifact entry with ignoreDriftForExitCode: true is still logged and reported as drifted, but does not contribute to this exit code. A run where all drifted tags belong to such entries exits 0, and --drift-exit-code is not applied.

Examples

Mirror HTTP/S Helm charts into OCI Helm charts

Many common Kubernetes ecosystem components are still published only to classic HTTP/S Helm repositories and do not offer OCI Helm charts. The charts section pulls those charts over HTTP/S and re-publishes them as OCI Helm charts so a cluster can consume them from a single OCI registry.

This config mirrors a few such charts into GitHub Container Registry (GHCR):

# flux-mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
charts:
 - name: ingress-nginx
 source: https://kubernetes.github.io/ingress-nginx
 destination: oci://ghcr.io/my-org/charts
 version: ">=4.11.0"
 limit: 3
 - name: cert-manager
 source: https://charts.jetstack.io
 destination: oci://ghcr.io/my-org/charts
 version: ">=1.15.0"
 limit: 3
 - name: metrics-server
 source: https://kubernetes-sigs.github.io/metrics-server
 destination: oci://ghcr.io/my-org/charts
 version: ">=3.12.0"
 limit: 3
 - name: kube-prometheus-stack
 source: https://prometheus-community.github.io/helm-charts
 destination: oci://ghcr.io/my-org/charts
 version: ">=60.0.0"
 limit: 3
hosts:
 # GHCR is the push destination. It expects a username/password login (the
 # username is any non-empty value; GHCR authorizes by the token), so
 # `credential.username` is set and GITHUB_TOKEN is the password.
 - host: ghcr.io
 credential:
 username: my-org
 value: ${GH_TOKEN}

Each chart lands at ghcr.io/my-org/charts/<name>:<version>. Run it from GitHub Actions with packages: write so the workflow’s GITHUB_TOKEN can push:

# .github/workflows/mirror-charts.yaml
name: mirror-charts
on:
 schedule:
 - cron: "0 */6 * * *"
 workflow_dispatch:
permissions:
 contents: read
 packages: write
jobs:
 sync:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v6
 - uses: fluxcd/flux-mirror/actions/setup@main
 - run: flux-mirror sync ./flux-mirror.yaml --no-progress
 env:
 GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Mirror OCI Helm charts into OCI Helm charts

A Helm chart that already lives in an OCI registry is mirrored OCI-to-OCI as a plain OCI artifact. The artifacts section is the only way to mirror an OCI Helm chart between OCI repositories — the charts section is exclusively for HTTP/S sources.

apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
artifacts:
 - source: ghcr.io/stefanprodan/charts/podinfo
 destination: ghcr.io/my-org/charts/podinfo
 selector:
 semver: ">=6.0.0"
 limit: 5

Mirror images from GHCR into a private registry

This mirrors ghcr.io/fluxcd controller images into a private registry from GitHub Actions. The destination authenticates with a username and password from GitHub Actions secrets. The GHCR source is authenticated with GITHUB_TOKEN (rather than pulled anonymously) to avoid anonymous pull rate limits — GHCR expects a username/password login, so credential.username is set there too.

# flux-mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
artifacts:
 - source: ghcr.io/fluxcd/source-controller
 destination: registry.internal.example.com/fluxcd/source-controller
 selector:
 semver: ">=1.0.0"
 limit: 5
 includeReferrers: true
 - source: ghcr.io/fluxcd/kustomize-controller
 destination: registry.internal.example.com/fluxcd/kustomize-controller
 selector:
 semver: ">=1.0.0"
 limit: 5
 includeReferrers: true
hosts:
 # Source: authenticate to GHCR to avoid anonymous rate limits.
 - host: ghcr.io
 credential:
 username: my-org
 value: ${GH_TOKEN}
 # Destination: a private registry expecting a username/password login. The
 # username and password are substituted from the environment while loading the
 # config.
 - host: registry.internal.example.com
 credential:
 username: ${REGISTRY_USERNAME}
 value: ${REGISTRY_PASSWORD}

# .github/workflows/mirror-images.yaml
name: mirror-images
on:
 schedule:
 - cron: "0 */6 * * *"
permissions:
 contents: read
 packages: read
jobs:
 sync:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v6
 - uses: fluxcd/flux-mirror/actions/setup@main
 - name: Substitute the destination username into the config
 run: envsubst '${REGISTRY_USERNAME}' < flux-mirror.yaml > rendered.yaml
 env:
 REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
 - run: flux-mirror sync ./rendered.yaml --no-progress
 env:
 GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}

Mirror into ECR, ACR, or GAR from GitHub Actions

To mirror container images, OCI Helm charts, and Flux OCI artifacts into a cloud registry, authenticate to the cloud provider with its GitHub Actions OIDC login action, then set hosts[].provider on the destination host so flux-mirror reuses that ambient identity. The source here is GHCR, authenticated with GITHUB_TOKEN.

The config is the same for all three clouds except for the destination host and provider:

# flux-mirror.yaml — Amazon ECR destination
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
artifacts:
 - source: ghcr.io/fluxcd/source-controller  # container image
 destination: 123456789012.dkr.ecr.us-east-1.amazonaws.com/fluxcd/source-controller
 selector: { semver: ">=1.0.0", limit: 5 }
 includeReferrers: true
 - source: ghcr.io/stefanprodan/charts/podinfo # OCI Helm chart
 destination: 123456789012.dkr.ecr.us-east-1.amazonaws.com/charts/podinfo
 selector: { semver: ">=6.0.0", limit: 5 }
 - source: ghcr.io/stefanprodan/manifests/podinfo # Flux OCI artifact
 destination: 123456789012.dkr.ecr.us-east-1.amazonaws.com/manifests/podinfo
 selector: { regex: { pattern: "^latest$" }, sortBy: alphabetical }
hosts:
 - host: ghcr.io
 credential:
 username: my-org
 value: ${GH_TOKEN}
 - host: 123456789012.dkr.ecr.us-east-1.amazonaws.com
 provider: ecr

For ACR or GAR, change only the destination host and provider:

# Azure ACR
 - host: myregistry.azurecr.io
 provider: acr
# Google GAR
 - host: us-docker.pkg.dev
 provider: gar

The workflow differs only in the cloud login step, all using GitHub Actions OIDC (no long-lived cloud keys):

# .github/workflows/mirror-to-ecr.yaml
name: mirror-to-ecr
on:
 schedule:
 - cron: "0 */6 * * *"
permissions:
 contents: read
 packages: read
 id-token: write  # required for GitHub Actions OIDC
jobs:
 sync:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v6
 - uses: fluxcd/flux-mirror/actions/setup@main
 # --- Amazon ECR ---
 - uses: aws-actions/configure-aws-credentials@v4
 with:
 role-to-assume: arn:aws:iam::123456789012:role/flux-mirror
 aws-region: us-east-1
 # --- Azure ACR (instead of the AWS step) ---
 # - uses: azure/login@v2
 # with:
 # client-id: ${{ secrets.AZURE_CLIENT_ID }}
 # tenant-id: ${{ secrets.AZURE_TENANT_ID }}
 # subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
 # --- Google GAR (instead of the AWS step) ---
 # - uses: google-github-actions/auth@v2
 # with:
 # workload_identity_provider: projects/123/locations/global/workloadIdentityPools/gh/providers/gh
 # service_account: flux-mirror@my-project.iam.gserviceaccount.com
 - run: flux-mirror sync ./flux-mirror.yaml --no-progress
 env:
 GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Mirror into ECR, ACR, or GAR from a CronJob with workload identity

Inside a cluster, a CronJob can mirror on a schedule using the pod’s workload identity. The destination cloud registry is authenticated with hosts[].provider (which uses the ambient cloud credential chain — IRSA, AKS Workload Identity, or GKE Workload Identity). The source registry here accepts the cluster’s ServiceAccount OIDC tokens, so it is authenticated with a projected ServiceAccount token sent as an HTTP Bearer credential (no credential.username).

First, the ServiceAccount, annotated for each provider’s workload identity. The projected token’s audience must be the source registry host:

# EKS with IRSA (annotation mandatory)
apiVersion: v1
kind: ServiceAccount
metadata:
 name: flux-mirror
 namespace: flux-system
 annotations:
 eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/flux-mirror
# EKS Pod Identity needs no annotation (the association is created via the EKS
# API); the same ServiceAccount works.
---
# AKS Workload Identity (annotation mandatory; the pod also needs the
# azure.workload.identity/use: "true" label)
apiVersion: v1
kind: ServiceAccount
metadata:
 name: flux-mirror
 namespace: flux-system
 annotations:
 azure.workload.identity/client-id: 00000000-0000-0000-0000-000000000000
---
# GKE Workload Identity Federation. With direct KSA-to-IAM bindings no
# annotation is needed; when impersonating a GCP service account, annotate it:
apiVersion: v1
kind: ServiceAccount
metadata:
 name: flux-mirror
 namespace: flux-system
 annotations:
 iam.gke.io/gcp-service-account: flux-mirror@my-project.iam.gserviceaccount.com

The config authenticates the destination with provider and the source with the projected token. Because file-path fields are confined to the config’s own directory, the config and the token are mounted together (below) so a relative fromPath resolves:

# mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
artifacts:
 - source: source-registry.example.com/library/app
 destination: 123456789012.dkr.ecr.us-east-1.amazonaws.com/library/app
 selector: { semver: ">=1.0.0", limit: 5 }
hosts:
 # Source: a registry that validates the cluster's ServiceAccount OIDC token.
 # No credential.username → the token is sent as an HTTP Bearer credential. Its
 # audience (the source host) is set by the projected-token volume, not here.
 - host: source-registry.example.com
 credential:
 fromPath: registry-token
 # Destination: ECR via the pod's IRSA identity (use acr/gar to switch clouds).
 - host: 123456789012.dkr.ecr.us-east-1.amazonaws.com
 provider: ecr

The CronJob runs as the annotated ServiceAccount and projects a token whose audience is the source registry, combined with the config in one volume so the relative fromPath stays within the config directory:

apiVersion: batch/v1
kind: CronJob
metadata:
 name: flux-mirror
 namespace: flux-system
spec:
 schedule: "0 */6 * * *"
 concurrencyPolicy: Forbid
 jobTemplate:
 spec:
 template:
 metadata:
 labels:
 azure.workload.identity/use: "true" # AKS Workload Identity only
 spec:
 serviceAccountName: flux-mirror
 restartPolicy: OnFailure
 containers:
 - name: flux-mirror
 image: ghcr.io/fluxcd/flux-mirror:latest
 args: ["sync", "/config/flux/mirror.yaml", "--no-progress"]
 volumeMounts:
 - name: flux
 mountPath: /config/flux
 readOnly: true
 volumes:
 # One projected volume holds both the config and the registry token,
 # so /config/flux/mirror.yaml can reference ./registry-token.
 - name: flux
 projected:
 sources:
 - configMap:
 name: flux-mirror-config  # holds mirror.yaml
 - serviceAccountToken:
 path: registry-token
 audience: source-registry.example.com
 expirationSeconds: 3600

Mirror with the AWS credential provider into a SPIFFE mTLS registry

This CronJob pulls container images from a registry that authenticates the caller’s AWS identity, and pushes them to a registry that requires SPIFFE X.509-SVID mTLS. The source host uses the aws credential provider, which signs an sts:GetCallerIdentity request the source registry replays to AWS STS, so the pod needs AWS credentials via IRSA. The destination host uses tls.spiffe and no HTTP credential — the registry authorizes the client by its X.509-SVID and the server is verified by its SPIFFE identity. The SPIFFE SVIDs and trust bundle come from the Workload API, which the SPIFFE CSI driver exposes to the pod; go-spiffe locates the socket through SPIFFE_ENDPOINT_SOCKET.

The ServiceAccount is annotated for IRSA so the aws provider can sign as the mapped AWS role:

apiVersion: v1
kind: ServiceAccount
metadata:
 name: flux-mirror
 namespace: flux-system
 annotations:
 eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/flux-mirror

# mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
artifacts:
 - source: source-registry.example.com/library/app
 destination: registry.example.org/library/app
 selector: { semver: ">=1.0.0", limit: 5 }
hosts:
 # Source: a registry that validates the caller's AWS identity.
 # No credential.username → the signed sts:GetCallerIdentity envelope is sent
 # as an HTTP Bearer credential.
 - host: source-registry.example.com
 credential:
 provider: aws
 # Destination: SPIFFE mTLS in both directions, no HTTP credential. Our client
 # X.509-SVID authenticates us; the server's SVID is verified against our own
 # trust domain.
 - host: registry.example.org
 tls:
 spiffe:
 serverIDs:
 - spiffe://self

apiVersion: batch/v1
kind: CronJob
metadata:
 name: flux-mirror
 namespace: flux-system
spec:
 schedule: "0 */6 * * *"
 concurrencyPolicy: Forbid
 jobTemplate:
 spec:
 template:
 spec:
 serviceAccountName: flux-mirror
 restartPolicy: OnFailure
 containers:
 - name: flux-mirror
 image: ghcr.io/fluxcd/flux-mirror:latest
 args: ["sync", "/config/flux/mirror.yaml", "--no-progress"]
 env:
 # go-spiffe reads the Workload API socket from this variable.
 - name: SPIFFE_ENDPOINT_SOCKET
 value: unix:///spiffe-workload-api/spire-agent.sock
 volumeMounts:
 - name: config
 mountPath: /config/flux
 readOnly: true
 - name: spiffe-workload-api
 mountPath: /spiffe-workload-api
 readOnly: true
 volumes:
 - name: config
 configMap:
 name: flux-mirror-config  # holds mirror.yaml
 # The SPIFFE CSI driver exposes the SPIRE Agent Workload API socket.
 - name: spiffe-workload-api
 csi:
 driver: csi.spiffe.io
 readOnly: true

Preview, resync, and CI invocations

# Preview the plan without writing to the destination.
flux mirror sync ./flux-mirror.yaml --dry-run -o yaml

# Force-resync every drifted tag.
flux mirror sync ./flux-mirror.yaml --overwrite

# CI-friendly: no spinner. For immutable destinations, keep CI green on drift.
flux mirror sync ./flux-mirror.yaml --no-progress --drift-exit-code=0

Flux: Flux Mirror Login Command

Mon, 01 Jan 0001 00:00:00 +0000

The flux mirror login command resolves the credentials configured under hosts and stores them in the Docker config, the same way docker login does. It mints the same credentials flux mirror sync would attach, but once — so any tool that reads the Docker config (docker, crane, flux push artifact, helm) can then authenticate as those identities.

Synopsis

flux mirror login [flags]

Configuration source

The config path is resolved as: the --config/-f flag, else $FLUX_MIRROR_CONFIG, else a path next to the executable (<executable>.config). -f - reads the config from stdin.

login reads only the hosts section, so — unlike sync — it accepts a config with no artifacts or charts.

Flags

Flag	Default	Description
`-f, --config`	`$FLUX_MIRROR_CONFIG`, else `<executable>.config`	Path to the flux-mirror config, or `-` for stdin.
`--host`	all hosts	Registry host from the config to log in. Repeatable; defaults to all hosts.
`--docker-config`	`$DOCKER_CONFIG`, else `~/.docker`	Docker config directory, like `docker --config`.
`--plaintext`	`false`	Store the credential base64-encoded in `config.json`, bypassing any OS keychain credential helper.

The global --timeout flag (default 1m) bounds credential resolution, which for provider sources involves a network call to mint the token. The global --no-envsubst flag disables config environment substitution.

Where the credential goes

By default, the credential is written through the Docker credential store, exactly like docker login:

If a credential helper is configured (credsStore/credHelpers) — or, on a fresh config, one is auto-detected for the platform (a docker-credential-* binary on PATH, e.g. osxkeychain, secretservice, pass, wincred) — the secret goes to the OS keychain, not the config file.
Otherwise, it falls back to a base64-encoded entry in config.json (the same plaintext fallback docker login uses when no helper is available).

What gets written depends on the host:

A cloud provider host, or a credential host with credential.username set, writes username/password/auth.
A credential host without credential.username writes the bearer registrytoken field instead. Because credential helpers only store username/secret pairs, a registrytoken always goes to the config file (never a keychain helper). See Bearer token vs. username/password.

Pass --plaintext to force the base64 config.json entry and bypass any configured or auto-detected helper (this applies to the username/password case; registrytoken is always file-based).

Note: a TLS-only host (only tls, no credential and no cloud provider) has nothing to store and is skipped with a • skipping <host> message.

Examples

Log in to ECR, ACR, or GAR from GitHub Actions

Authenticate to the cloud provider with its GitHub Actions OIDC login action, then flux-mirror login with a provider host. login mints the registry’s native credentials from that ambient identity and writes them into the Docker config. Afterwards flux push artifact (and any other Docker-config-aware tool) authenticates without a --provider flag, because the credentials are already in the config.

Instead of running the cloud provider’s login action, set credential.provider to github or forgejo on the host. flux-mirror fetches the Actions OIDC token and exchanges it with the cloud provider. Set credential.audiences to the audience the cloud identity provider expects (e.g. sts.amazonaws.com or api://AzureADTokenExchange). Add the required ecr.roleARN, acr.tenantID/acr.clientID, or gar.workloadIdentityProvider block.

A hosts-only config — switch clouds by changing the host and provider:

# hosts.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
hosts:
 - host: 123456789012.dkr.ecr.us-east-1.amazonaws.com
 provider: ecr
 # - host: myregistry.azurecr.io
 # provider: acr
 # - host: us-docker.pkg.dev
 # provider: gar

# .github/workflows/push.yaml
permissions:
 contents: read
 id-token: write  # required for GitHub Actions OIDC
jobs:
 push:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v6
 - uses: fluxcd/flux-mirror/actions/setup@main
 # --- Amazon ECR ---
 - uses: aws-actions/configure-aws-credentials@v4
 with:
 role-to-assume: arn:aws:iam::123456789012:role/flux-push
 aws-region: us-east-1
 # --- Azure ACR (instead of the AWS step) ---
 # - uses: azure/login@v2
 # with:
 # client-id: ${{ secrets.AZURE_CLIENT_ID }}
 # tenant-id: ${{ secrets.AZURE_TENANT_ID }}
 # subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
 # --- Google GAR (instead of the AWS step) ---
 # - uses: google-github-actions/auth@v2
 # with:
 # workload_identity_provider: projects/123/locations/global/workloadIdentityPools/gh/providers/gh
 # service_account: flux-push@my-project.iam.gserviceaccount.com
 - run: flux-mirror login -f ./hosts.yaml
 # No --provider needed: the credential is already in the Docker config.
 - run: |
 flux push artifact \
 oci://123456789012.dkr.ecr.us-east-1.amazonaws.com/manifests/app:v1.0.0 \
 --path=./manifests --source="$GITHUB_REPOSITORY" --revision="$GITHUB_SHA"

Log in to GHCR from GitHub Actions

GHCR authorizes by the token and ignores the username value, but it still expects a username/password login — so set credential.username to any value (for example a github.* context key) and pass GITHUB_TOKEN as the password via value:

# hosts.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
hosts:
 - host: ghcr.io
 credential:
 username: ${GITHUB_REPOSITORY_OWNER}  # ignored by GHCR; any value works
 value: ${GH_TOKEN}

# .github/workflows/push.yaml
permissions:
 contents: read
 packages: write
jobs:
 push:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v6
 - uses: fluxcd/flux-mirror/actions/setup@main
 - run: flux-mirror login -f ./hosts.yaml
 env:
 GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 - run: |
 flux push artifact oci://ghcr.io/$GITHUB_REPOSITORY_OWNER/manifests/app:v1.0.0 \
 --path=./manifests --source="$GITHUB_REPOSITORY" --revision="$GITHUB_SHA"

Log in to Docker Hub from GitHub Actions

Docker Hub uses a standard username/password login. Set credential.username to the Docker Hub account and pass an access token as the password via value:

# hosts.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
hosts:
 - host: docker.io
 credential:
 username: ${DOCKERHUB_USERNAME}
 value: ${DOCKERHUB_TOKEN}

# .github/workflows/push.yaml
jobs:
 push:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v6
 - uses: fluxcd/flux-mirror/actions/setup@main
 - run: envsubst '${DOCKERHUB_USERNAME}' < hosts.yaml > rendered.yaml
 env:
 DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
 - run: flux-mirror login -f ./rendered.yaml
 env:
 DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
 - run: |
 flux push artifact oci://docker.io/$DOCKERHUB_USERNAME/manifests/app:v1.0.0 \
 --path=./manifests --source="$GITHUB_REPOSITORY" --revision="$GITHUB_SHA"
 env:
 DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}

Common invocations

# Log in to every host in the default config.
flux mirror login

# Specific hosts from a specific config file.
flux mirror login --host registry.example.com --host other.example.com -f ./flux-mirror.yaml

# Read the config from stdin.
flux mirror login -f - < flux-mirror.yaml

# Use an alternate Docker config directory, like 'docker --config'.
flux mirror login --docker-config /tmp/docker

# Force a plaintext config.json entry instead of the OS keychain.
flux mirror login --plaintext

Notes

The credential is short-lived (a freshly minted provider token, a signed JWT, or whatever value/fromPath holds). Re-run login before it expires; for provider sources the registry re-validates each request, so a stored credential stops working once it lapses. To mint a longer-lived login token, use a jwkPath/jwkValue credential with a longer expiration — see keygen.
For aws, the credential is a JWT-shaped envelope wrapping a signed sts:GetCallerIdentity request, not an OIDC token. The destination registry must understand this scheme — see Token providers.

Flux: Flux Mirror Secret Command

Mon, 01 Jan 0001 00:00:00 +0000

The flux mirror secret <name> command resolves the credentials configured under hosts for each selected host and writes them into a Kubernetes Secret of type kubernetes.io/dockerconfigjson — the same shape kubectl create secret docker-registry produces. These are the same credentials sync and login resolve, so the Secret can be referenced as an imagePullSecret, or by a Flux OCIRepository/HelmRepository .spec.secretRef, to pull from a registry that understands the configured identity.

Its main use case is rotating short-lived pull Secrets from a CronJob.

Synopsis

flux mirror secret <name> [flags]

<name> is the name of the Secret to create or replace.

By default the Secret is upserted: if one with the same name already exists it is replaced in place. Pass --create to instead fail if the Secret already exists, matching kubectl create secret docker-registry.

Configuration source

The config path is resolved as: the --config/-f flag, else $FLUX_MIRROR_CONFIG, else <executable>.config. -f - reads the config from stdin. Like login, secret reads only the hosts section and accepts a hosts-only config.

Flags

Flag	Default	Description
`-f, --config`	`$FLUX_MIRROR_CONFIG`, else `<executable>.config`	Path to the flux-mirror config, or `-` for stdin.
`--host`	all hosts	Registry host from the config to include. Repeatable; defaults to all hosts.
`--create`	`false`	Fail if the Secret already exists instead of replacing it.

In addition, the command accepts the standard kubectl connection flags and their env vars — --kubeconfig ($KUBECONFIG), --context, --cluster, -n/--namespace, --user, --server, --token, --request-timeout, --as, --certificate-authority, --insecure-skip-tls-verify, and so on. The namespace defaults to the one from the active kubeconfig context, or the in-cluster ServiceAccount namespace when running inside a pod.

Behavior

Works both locally (kubeconfig) and in-cluster (falls back to the in-cluster config and ServiceAccount namespace).
By default the Secret is upserted (created, or replaced if it exists). With --create, an existing Secret of the same name is an error. On replace, existing labels and annotations are preserved.
With no --host, every host in hosts is included. A --host that is not present in the config is an error.
The Secret’s .dockerconfigjson holds one auths entry per host. A cloud provider host, and a credential host with credential.username set, write username/password/auth (understood by kubelet and Flux). A credential host without credential.username writes the bearer registrytoken field (understood by go-containerregistry and Flux, not by kubelet). See Bearer token vs. username/password.
A TLS-only host (only tls, no credential and no cloud provider) has nothing to put in the Secret and is skipped with a • skipping <host> message.
Credentials are short-lived (provider tokens, freshly signed JWTs). Re-run the command to refresh the Secret before they expire; by default it replaces the existing one in place.

Examples

Rotate ECR, ACR, or GAR pull credentials from a CronJob

A cloud registry such as ECR, ACR, or GAR issues only short-lived credentials, so a CronJob regenerates the pull Secret on a schedule using the pod’s workload identity. A provider host mints the registry’s native username/password from the ambient cloud identity, and secret writes it as a dockerconfigjson Secret usable as an imagePullSecret.

When running in GitHub or Forgejo Actions, the host can instead set credential.provider to github or forgejo; flux-mirror exchanges the Actions OIDC token with the cloud provider, so the pod does not need ambient cloud credentials. Add the required ecr.roleARN, acr.tenantID/acr.clientID, or gar.workloadIdentityProvider block.

The ServiceAccount carries each provider’s workload-identity annotations:

# EKS with IRSA (annotation mandatory; EKS Pod Identity needs none)
apiVersion: v1
kind: ServiceAccount
metadata:
 name: flux-mirror
 namespace: flux-system
 annotations:
 eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/flux-mirror
---
# AKS Workload Identity (annotation mandatory; pod also needs the
# azure.workload.identity/use: "true" label)
apiVersion: v1
kind: ServiceAccount
metadata:
 name: flux-mirror
 namespace: flux-system
 annotations:
 azure.workload.identity/client-id: 00000000-0000-0000-0000-000000000000
---
# GKE Workload Identity Federation (annotation only when impersonating a GSA)
apiVersion: v1
kind: ServiceAccount
metadata:
 name: flux-mirror
 namespace: flux-system
 annotations:
 iam.gke.io/gcp-service-account: flux-mirror@my-project.iam.gserviceaccount.com

The ServiceAccount also needs RBAC to manage the Secret it writes:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
 name: flux-mirror-secret
 namespace: flux-system
rules:
 - apiGroups: [""]
 resources: ["secrets"]
 verbs: ["get", "create", "update"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
 name: flux-mirror-secret
 namespace: flux-system
subjects:
 - kind: ServiceAccount
 name: flux-mirror
 namespace: flux-system
roleRef:
 kind: Role
 name: flux-mirror-secret
 apiGroup: rbac.authorization.k8s.io

A hosts-only config selecting the cloud registry (switch clouds via the host and provider), stored in a ConfigMap:

# mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
hosts:
 - host: 123456789012.dkr.ecr.us-east-1.amazonaws.com
 provider: ecr
 # - host: myregistry.azurecr.io
 # provider: acr
 # - host: us-docker.pkg.dev
 # provider: gar

The CronJob rotates the Secret in its own namespace:

apiVersion: batch/v1
kind: CronJob
metadata:
 name: flux-mirror-regcreds
 namespace: flux-system
spec:
 schedule: "0 */6 * * *" # rotate well within the credential lifetime
 concurrencyPolicy: Forbid
 jobTemplate:
 spec:
 template:
 metadata:
 labels:
 azure.workload.identity/use: "true" # AKS Workload Identity only
 spec:
 serviceAccountName: flux-mirror
 restartPolicy: OnFailure
 containers:
 - name: flux-mirror
 image: ghcr.io/fluxcd/flux-mirror:latest
 # In-cluster: kubeconfig and namespace are auto-detected.
 args: ["secret", "regcreds", "-f", "/config/flux/mirror.yaml"]
 volumeMounts:
 - name: config
 mountPath: /config/flux
 readOnly: true
 volumes:
 - name: config
 configMap:
 name: flux-mirror-config  # holds mirror.yaml

The resulting regcreds Secret holds username/password/auth, so it works both as a pod imagePullSecret and as a Flux OCIRepository/HelmRepository .spec.secretRef.

Rotate credentials for a registry that accepts ServiceAccount OIDC tokens

When the target registry validates the cluster’s ServiceAccount OIDC tokens directly, project a ServiceAccount token whose audience is the registry host and feed it to a credential host via fromPath. Setting credential.username writes the token as the password of a username/password pair (username/password/auth), so the resulting Secret works as a pod imagePullSecret (which kubelet can use) as well as a Flux OCIRepository/HelmRepository .spec.secretRef. The username value is whatever the registry expects alongside the token — many token-validating registries ignore it but require it to be present.

Reuse the ServiceAccount and RBAC from the previous example (here the ServiceAccount needs no cloud annotations — the registry trusts the cluster issuer directly). The config references the token by a relative path, and because file-path fields are confined to the config’s own directory, the config and the token are mounted together:

# mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
hosts:
 - host: registry.example.com
 credential:
 username: sa-oidc  # value the registry expects; often ignored
 fromPath: registry-token  # the audience is set by the projected volume

apiVersion: batch/v1
kind: CronJob
metadata:
 name: flux-mirror-regcreds
 namespace: flux-system
spec:
 schedule: "*/30 * * * *" # rotate ahead of the token's expirationSeconds
 concurrencyPolicy: Forbid
 jobTemplate:
 spec:
 template:
 spec:
 serviceAccountName: flux-mirror
 restartPolicy: OnFailure
 containers:
 - name: flux-mirror
 image: ghcr.io/fluxcd/flux-mirror:latest
 args: ["secret", "regcreds", "-f", "/config/flux/mirror.yaml"]
 volumeMounts:
 - name: flux
 mountPath: /config/flux
 readOnly: true
 volumes:
 # One projected volume holds both the config and the registry token,
 # so /config/flux/mirror.yaml can reference ./registry-token.
 - name: flux
 projected:
 sources:
 - configMap:
 name: flux-mirror-config  # holds mirror.yaml
 - serviceAccountToken:
 path: registry-token
 audience: registry.example.com
 expirationSeconds: 3600

Rotate credentials using a SPIFFE JWT-SVID

When the registry accepts SPIFFE JWT-SVIDs, use the spiffe credential provider: it fetches a JWT-SVID for the audiences (defaulting to the registry host) from the SPIFFE Workload API. Setting credential.username writes the JWT-SVID as the password of a username/password pair, so the resulting Secret works as a pod imagePullSecret (which kubelet can use) as well as a Flux OCIRepository/HelmRepository .spec.secretRef. The Workload API is exposed to the pod by the SPIFFE CSI driver, and go-spiffe locates it through the SPIFFE_ENDPOINT_SOCKET environment variable.

Reuse the ServiceAccount and secret-management RBAC from the first example (no cloud annotations are needed; the registry trusts the SPIFFE trust domain).

# mirror.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
hosts:
 - host: registry.example.com
 credential:
 provider: spiffe
 username: spiffe  # value the registry expects; often ignored
 # audiences default to the host (registry.example.com)

apiVersion: batch/v1
kind: CronJob
metadata:
 name: flux-mirror-regcreds
 namespace: flux-system
spec:
 schedule: "*/30 * * * *" # rotate ahead of the JWT-SVID lifetime
 concurrencyPolicy: Forbid
 jobTemplate:
 spec:
 template:
 spec:
 serviceAccountName: flux-mirror
 restartPolicy: OnFailure
 containers:
 - name: flux-mirror
 image: ghcr.io/fluxcd/flux-mirror:latest
 args: ["secret", "regcreds", "-f", "/config/flux/mirror.yaml"]
 env:
 # go-spiffe reads the Workload API socket from this variable.
 - name: SPIFFE_ENDPOINT_SOCKET
 value: unix:///spiffe-workload-api/spire-agent.sock
 volumeMounts:
 - name: config
 mountPath: /config/flux
 readOnly: true
 - name: spiffe-workload-api
 mountPath: /spiffe-workload-api
 readOnly: true
 volumes:
 - name: config
 configMap:
 name: flux-mirror-config  # holds mirror.yaml
 # The SPIFFE CSI driver exposes the SPIRE Agent Workload API socket.
 - name: spiffe-workload-api
 csi:
 driver: csi.spiffe.io
 readOnly: true

The resulting Secret holds username/password/auth, so it works as a pod imagePullSecret as well as a Flux OCIRepository/HelmRepository .spec.secretRef.

Common invocations

# Upsert a Secret for all hosts in the default config, in the current namespace.
flux mirror secret regcreds

# Fail if the Secret already exists, like 'kubectl create secret docker-registry'.
flux mirror secret regcreds --create

# Specific hosts, a specific namespace and kubeconfig context.
flux mirror secret regcreds -n flux-system --context prod \
 --host registry.example.com --host other.example.com -f ./flux-mirror.yaml

Flux: Flux Mirror Keygen Command

Mon, 01 Jan 0001 00:00:00 +0000

The flux mirror keygen command generates an EdDSA (Ed25519) JSON Web Key pair for JWK-based registry auth. The output files plug directly into the hosts[].credential.jwkPath config field, which sync and login use to sign JWTs.

Synopsis

flux mirror keygen [flags]

It writes the key pair into a directory as two JWK sets:

File	Contents	Mode
`pubkey.json`	Public JWK set — share with the registry or publish it as JWKS.	`0644`
`privkey.json`	Private JWK set — keep it secret.	`0600`

Both files use the standard JWK set shape {"keys":[...]}. The two keys share a UUIDv6 kid so a signature made with the private key can be matched against the public set.

Flags

Flag	Default	Description
`-o, --output-dir`	`.`	Directory to write `pubkey.json` and `privkey.json` into. Created if missing.

Behavior

The output directory is created (mkdir -p) if it does not exist.
The command refuses to overwrite either file if it already exists. Delete them or point at a fresh directory to rotate.
The private file is written with mode 0600. If the public write fails, the private file is rolled back, so a partial run never leaves a stray key behind.

# Write a key pair into the current directory.
flux mirror keygen

# Write a key pair into ./keys/registry (created if missing).
flux mirror keygen -o ./keys/registry

Output:

✔ private key set written to: ./keys/registry/privkey.json
✔ public key set written to: ./keys/registry/pubkey.json

Unlike provider/value credentials — whose lifetime is fixed by an external issuer — a jwkPath credential is signed locally, so you control its lifetime through expiration. This makes a key pair plus login a convenient way to mint a single, long-lived bearer token (for example, a year-long token for a CI system or an air-gapped agent).

1. Generate the key pair.

flux mirror keygen -o ./keys/registry

2. Reference the private key from a host credential, with a long expiration. Set issuer/subject to the identity the registry expects, and expiration to the desired lifetime (here ~1 year). With no credential.username, the signed JWT is stored as a bearer registrytoken:

# config.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
hosts:
 - host: registry.example.com
 credential:
 jwkPath: ./keys/registry/privkey.json
 issuer: https://my-issuer.example
 subject: ci-pusher
 # audiences: # optional, defaults to the host
 # - registry.example.com
 expiration: 8760h  # ~1 year

3. Log in once to mint and store the token.

flux mirror login -f ./config.yaml

login signs one JWT valid for the configured expiration and writes it to the Docker config, so tools like flux push artifact authenticate as that identity until it expires.

4. Grant access on the registry side. Share pubkey.json with the registry operator, or publish it at an HTTPS URL the registry can fetch as JWKS, so the registry can verify tokens signed by the matching private key (matched by kid).

Re-run login to mint a fresh token before the current one expires. Treat privkey.json as a secret: anyone holding it can mint tokens for the configured subject until the public key is rotated out.

Flux: Flux Mirror Report

Mon, 01 Jan 0001 00:00:00 +0000

The flux mirror sync command can emit a structured report of the mirror results by setting --output to json or yaml. The envelope shape is versioned and documented by the JSON Schema in report-v1beta2.json; the deprecated report-v1beta1.json remains published for existing reports.

Usage

flux mirror sync config.yaml -o json

Structured output always emits every entry regardless of --verbose. Filtering belongs downstream (jq, yq). The process exit code still reflects whether any tag failed or drifted (see exit codes).

Envelope

Every report is wrapped in a top-level envelope:

Key	Description
`apiVersion`	Report API version. Currently `mirror.plugin.fluxcd.io/v1beta2`.
`kind`	Report API kind. Currently `Report`.
`$schema`	URL of the JSON Schema describing the envelope. JSON only.
`report.reporter`	Identity of the producer, e.g. `flux-mirror/v0.1.0`.
`report.timestamp`	RFC 3339 UTC timestamp of the run.
`report.durationMs`	Total wall time of the run, in milliseconds.
`report.summary`	Aggregate counts across all entries (see below).
`report.results[]`	One entry per config entry, in config order.

The $schema key is JSON-only — it points at a JSON Schema document and carries no meaning for YAML consumers, so it is dropped in YAML mode.

Summary fields

Every field is always present (zero when unused) so consumers can rely on a stable key set.

Key	Description
`entries`	Number of config entries processed.
`copied`	Total tags copied across all entries.
`overwritten`	Total tags overwritten (drift with `overwrite: true`).
`skipped`	Total tags skipped (already up to date, or deferred by `verify.minAge`).
`drifted`	Total tags drifted (different digest, `overwrite: false`), including entries with `ignoreDriftForExitCode: true`.
`wouldCopy`	Dry-run forecast: tags that would have been copied.
`wouldOverwrite`	Dry-run forecast: tags that would have been overwritten.
`failed`	Total failures: tag-level failures plus plan-failed entries.
`exitCode`	Semantic exit code: `0` clean, `1` failures, `2` drift. Drift on entries with `ignoreDriftForExitCode: true` is excluded. Not affected by `--drift-exit-code`.

Result fields

Each results[] entry describes one config entry (an artifact or chart source).

Key	Description
`source`	Source repository/reference being mirrored.
`destination`	Destination repository the entry mirrors into.
`status`	Entry-level outcome: `completed` or `failed`.
`error`	Plan-time error message. Present only when `status` is `failed`.
`ignoreDriftForExitCode`	`true` when the entry’s drifted tags were excluded from the exit code.
`tags[]`	Per-tag results, in plan order (deterministic). May be empty.

The entry status disambiguates an empty tags array:

completed + [] → the entry was planned and run, but nothing matched the selector.
failed + [] (+ error) → the entry could not be planned (e.g. tag listing failed).

A completed entry can still contain tag-level failed rows — those are per-tag problems, not an entry-level failure.

Tag fields

Key	Description
`tag`	Tag name (artifacts) or chart version (charts).
`status`	Per-tag outcome — see Status.
`digest`	Source artifact digest, when resolved. Absent on a verify-failed row.
`reason`	Why a `skipped` tag was skipped — see Reason. Present only on `skipped`.
`error`	Error message. Present only when `status` is `failed`.
`referrers[]`	Mirrored sub-artifacts (signatures, SBOMs, attestations). Present only with `includeReferrers`.
`verification`	Signature verification metadata. Present only when a signature was confirmed (under `verify:`).

Status values

Status	Meaning
`copied`	Destination did not have it; mirrored from source.
`overwritten`	Destination had a different digest; replaced (`overwrite: true`).
`skipped`	Nothing copied; see `reason`.
`drifted`	Destination has a different digest, `overwrite: false` — left alone.
`would-copy`	Dry-run: would have been copied.
`would-overwrite`	Dry-run: would have been overwritten.
`failed`	The operation errored; see `error`.

Reason values

reason is always present on a skipped status (tag or referrer) and absent otherwise.

Reason	Meaning
`up-to-date`	Destination already has the same digest.
`signature-too-new`	A valid signature was deferred because it is younger than `verify.minAge`.

Referrer fields

Each referrers[] entry describes one referrer (e.g. a cosign signature bundle, an SBOM, or an attestation) mirrored alongside its parent tag.

Key	Description
`digest`	Referrer manifest digest.
`artifactType`	The referrer manifest’s `artifactType`, when set.
`status`	Same Status enum as a tag.
`reason`	Present only on `skipped` (same Reason).

Referrers are reported for any tag whose mirror flow reached the referrer step — every status except failed (the tag copy errored first) and the signature-too-new skip (deferred without mirroring). In --dry-run, referrers are still evaluated and reported with would-copy / would-overwrite / skipped statuses.

Verification fields

Present only when a signature was confirmed (the entry has a verify: block). Only provider is guaranteed; the rest is best-effort.

Key	Description
`provider`	Verification provider, e.g. `cosign`.
`issuer`	Matched OIDC issuer from the signing certificate.
`identity`	Matched certificate identity (subject alternative name).
`integratedTime`	Transparency-log integration time (RFC 3339). Present only when the bundle carries a Tlog timestamp.
`age`	Signature age, as a Go duration string. Present only on a `signature-too-new` skip.
`minAge`	Configured `verify.minAge`, as a Go duration string. Present only on a `signature-too-new` skip.

A verify failure (bad/missing signature, OIDC mismatch) is not a verification block: it surfaces as a status: "failed" tag row carrying the verify error, with no verification and no digest. Verification runs at plan time, so the first verify failure stops the entry (tags verified before it still run); the entry itself stays status: "completed". A real verify-failed row (the configured OIDC subject regex did not match the signed identity):

{
 "tag": "6.13.0",
 "status": "failed",
 "error": "verify docker.io/stefanprodan/podinfo:6.13.0: signature verification failed: failed to verify certificate identity: no matching CertificateIdentity found, last error: expected SAN value to match regex \"^https://github\\.com/example/.*$\", got \"https://github.com/stefanprodan/podinfo/.github/workflows/release.yml@refs/tags/6.13.0\""
}

Example

A report from flux mirror sync … -o json against a config with cosign verification (minAge: 48h) and includeReferrers: true. The first entry completed: tag 6.13.0 was deferred because its signature is younger than minAge, while 6.12.0 was copied along with its cosign signature bundle. The second entry failed at plan time because the source repository does not exist.

{
 "apiVersion": "mirror.plugin.fluxcd.io/v1beta2",
 "kind": "Report",
 "$schema": "https://raw.githubusercontent.com/fluxcd/flux-mirror/main/docs/report-v1beta2.json",
 "report": {
 "reporter": "flux-mirror/v0.1.0",
 "timestamp": "2026-06-06T20:12:25Z",
 "durationMs": 16724,
 "summary": {
 "entries": 2,
 "copied": 1,
 "overwritten": 0,
 "skipped": 1,
 "drifted": 0,
 "wouldCopy": 0,
 "wouldOverwrite": 0,
 "failed": 1,
 "exitCode": 1
 },
 "results": [
 {
 "source": "docker.io/stefanprodan/podinfo",
 "destination": "localhost:5050/podinfo",
 "status": "completed",
 "tags": [
 {
 "tag": "6.13.0",
 "status": "skipped",
 "digest": "sha256:7bdd8cc80b64377b05f5c0a51604c028ed6adea4beaca2e766b9325efa52916c",
 "reason": "signature-too-new",
 "verification": {
 "provider": "cosign",
 "issuer": "https://token.actions.githubusercontent.com",
 "identity": "https://github.com/stefanprodan/podinfo/.github/workflows/release.yml@refs/tags/6.13.0",
 "integratedTime": "2026-06-04T20:59:02Z",
 "age": "47h13m11s",
 "minAge": "48h0m0s"
 }
 },
 {
 "tag": "6.12.0",
 "status": "copied",
 "digest": "sha256:453e2238f70c00dfba6803ddb99a4bb86982ee549f7273f43f90ac58f0714a81",
 "referrers": [
 {
 "digest": "sha256:5892f840c5013230cd0b63fdd5076dd9fe3224a31bd3ebae5c723e3632100b0f",
 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
 "status": "copied"
 }
 ],
 "verification": {
 "provider": "cosign",
 "issuer": "https://token.actions.githubusercontent.com",
 "identity": "https://github.com/stefanprodan/podinfo/.github/workflows/release.yml@refs/tags/6.12.0",
 "integratedTime": "2026-05-20T10:16:39Z"
 }
 }
 ]
 },
 {
 "source": "docker.io/library/flux-mirror-nonexistent-zzz",
 "destination": "localhost:5050/nonexistent",
 "status": "failed",
 "error": "list tags docker.io/library/flux-mirror-nonexistent-zzz: GET https://index.docker.io/v2/library/flux-mirror-nonexistent-zzz/tags/list?n=1000: UNAUTHORIZED: authentication required; [map[Action:pull Class: Name:library/flux-mirror-nonexistent-zzz Type:repository]]",
 "tags": []
 }
 ]
 }
}

Flux – Flux Mirror

Flux: Flux Mirror Config

Example

Writing a Config spec

API version

Artifacts

Tag selection

Referrers

Signature verification

Charts

Hosts

Host direction

Per-host credential

Token providers

Resolving file paths

Bearer token vs. username/password

Cloud registry providers

Transport TLS

Blob upload chunking

Working with Config

Overwrite and drift behavior

Defaults

Flux: Flux Mirror Sync Command

Synopsis

Configuration source

Authentication

Flags

Output

Text mode (default)

Verbose mode

Structured output

Status

Referrers

Exit codes

Examples

Mirror HTTP/S Helm charts into OCI Helm charts

Mirror OCI Helm charts into OCI Helm charts

Mirror images from GHCR into a private registry

Mirror into ECR, ACR, or GAR from GitHub Actions

Mirror into ECR, ACR, or GAR from a CronJob with workload identity

Mirror with the AWS credential provider into a SPIFFE mTLS registry

Preview, resync, and CI invocations

Flux: Flux Mirror Login Command

Synopsis

Configuration source

Flags

Where the credential goes

Examples

Log in to ECR, ACR, or GAR from GitHub Actions

Log in to GHCR from GitHub Actions

Log in to Docker Hub from GitHub Actions

Common invocations

Notes

Flux: Flux Mirror Secret Command

Synopsis

Configuration source

Flags

Behavior

Examples

Rotate ECR, ACR, or GAR pull credentials from a CronJob

Rotate credentials for a registry that accepts ServiceAccount OIDC tokens

Rotate credentials using a SPIFFE JWT-SVID

Common invocations

Flux: Flux Mirror Keygen Command

Synopsis

Flags

Behavior

Example: mint a long-lived login token

Flux: Flux Mirror Report

Usage

Envelope

Summary fields

Result fields

Tag fields

Status values

Reason values

Referrer fields

Verification fields

Example