FluxCD Sources Reference

All source CRDs use apiVersion: source.toolkit.fluxcd.io/v1, except ArtifactGenerator which uses source.extensions.fluxcd.io/v1beta1. The source-controller polls at the configured interval and produces versioned, immutable artifacts consumed by kustomize-controller and helm-controller.

GitRepository

Retrieves manifests from a Git repository and produces a tarball artifact.

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: fleet-manifests
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/my-org/fleet-manifests
  ref:
    branch: main
  secretRef:
    name: git-credentials

Key fields:

Auth options:

SSH scp-style syntax (git@host:repo) is not supported — use ssh://git@host/repo.

OCIRepository

Pulls OCI artifacts from container registries. The foundation of gitless GitOps.

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: fleet-manifests
  namespace: flux-system
spec:
  interval: 5m
  url: oci://ghcr.io/my-org/fleet-manifests
  ref:
    tag: latest
  verify:
    provider: cosign
    matchOIDCIdentity:
      - issuer: "https://token.actions.githubusercontent.com"
        subject: "repo:my-org/fleet-manifests:ref:refs/heads/main"

Key fields:

Cloud auth (keyless OIDC): Set provider: aws, azure, or gcp in spec.provider — no static credentials needed.

For Helm charts, prefer OCIRepository + spec.chartRef over HelmRepository — it supports Cosign verification and is more flexible.

HelmRepository

Manages an HTTPS Helm chart index.

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: cert-manager
  namespace: flux-system
spec:
  interval: 1h
  url: https://charts.jetstack.io

For OCI registries, use OCIRepository instead — it supports Cosign verification and doesn't require a separate index fetch.

HelmChart

Packages a chart from a source. Typically auto-generated by HelmRelease — you do not normally create these directly.

References HelmRepository, GitRepository, or Bucket as source. Supports semver constraints and values file merging.

Bucket

Fetches manifests from S3-compatible object storage.

apiVersion: source.toolkit.fluxcd.io/v1
kind: Bucket
metadata:
  name: manifests
  namespace: flux-system
spec:
  interval: 5m
  provider: aws          # aws | azure | gcp | generic
  bucketName: my-manifests
  endpoint: s3.amazonaws.com
  region: eu-west-1

Supports prefix filtering and .gitignore-style exclusion patterns.

ExternalArtifact

A generic artifact API populated by external controllers. Has no spec fields — used as a handoff point between custom controllers and Flux reconcilers.

ArtifactGenerator

Composes or decomposes artifacts from multiple sources. Requires source-watcher optional component in FluxInstance.

Two primary use cases:

1. Monorepo decomposition

Splits a single repository into multiple ExternalArtifact objects per component. Only the affected component's artifact gets a new revision when its path changes — avoids full-repo reconciliation for every commit.

apiVersion: source.extensions.fluxcd.io/v1beta1
kind: ArtifactGenerator
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 5m
  sourceRef:
    kind: OCIRepository
    name: fleet-manifests
  generators:
    - path: apps/team-a
      name: team-a
    - path: apps/team-b
      name: team-b

2. Helm chart composition

Merges environment-specific values from Git into an OCI-hosted chart. Keeps chart and values in separate sources, composed at deploy time.

Copy strategies:

Source selection decision matrix

Validation

# Check source status
flux get sources all -A

# Force immediate source fetch
flux reconcile source git <name> -n flux-system
flux reconcile source oci <name> -n flux-system

# Inspect artifact
kubectl describe gitrepository <name> -n flux-system
kubectl describe ocirepository <name> -n flux-system