GitRepository and source-controller — the source of desired state

source-controller is the first link in the Flux chain. It owns the four CRDs that describe where desired state lives and produces a tarball artifact that the rest of the controllers consume. Without a ready source artifact, no Kustomization reconciles and no HelmRelease installs.

What source-controller does

The controller watches its CRDs, fetches their referenced content at a declared interval, validates the content, packages it as a tarball, and writes the artifact reference into the CRD’s status section. The four CRDs:

• GitRepository - a Git repository, cloned at a ref (branch, tag, commit SHA, semver range).
• OCIRepository - an OCI image pulled at a tag or digest.
• HelmRepository - a Helm chart repository (HTTP-served index.yaml plus chart tarballs).
• Bucket - an S3-compatible bucket polled for a key prefix.

flowchart LR
    GR["GitRepository"] --> SC["source-controller"]
    HR["HelmRepository"] --> SC
    OR["OCIRepository"] --> SC
    BK["Bucket"] --> SC
    SC --> ART[("in-cluster artifact Secret")]
    ART --> KC["kustomize-controller"]
    ART --> HC["helm-controller"]

Every successful reconcile produces the same shape: a Secret containing the artifact, and a status section pointing at it. Downstream controllers read status.artifact.url, fetch over HTTP using a service-account token, and never touch the original source.

The GitRepository spec

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: apps
  namespace: flux-system
spec:
  url: https://github.com/example/apps
  interval: 1m0s
  ref:
    branch: main
  secretRef:
    name: github-deploy-key
  ignore: |
    /*.md
    /docs/**
  timeout: 60s
  suspend: false

• spec.url - the clone URL. HTTPS is preferred for production; SSH is supported via a kubernetes.io/ssh-auth secretRef.
• spec.interval - how often the controller re-fetches. Production default is 1m0s.
• spec.ref - the reference to clone: branch, tag, semver, or commit. Pinning to a commit SHA is the production rule for branch-tracked repos.
• spec.secretRef - a Secret in the same namespace holding credentials (kubernetes.io/basic-auth, ssh-auth, or tls).
• spec.ignore - paths to exclude from the artifact.
• spec.suspend - pauses reconciliation; the escape hatch for incident containment.

Creating and inspecting

The CLI command that produces the manifest above:

flux create source git apps \
  --url=https://github.com/example/apps \
  --branch=main \
  --interval=1m0s \
  --secret-ref=github-deploy-key \
  --export

--export prints the CRD to stdout instead of applying it. The lifecycle from create to observe:

flux create source git apps --url=... --branch=main
flux get source git apps
flux reconcile source git apps

flux reconcile source git apps writes an annotation that forces the next reconcile out of cycle.

Status and the artifact

The status section is populated by the controller:

• status.artifact.revision - the SHA resolved from spec.ref at fetch time. Pinning spec.ref to a commit SHA returns the same SHA every fetch.
• status.artifact.url - the in-cluster HTTP URL of the tarball. Downstream controllers fetch from here.
• status.conditions[Ready] - the condition other controllers wait on. reason=GitOperationFailed means the clone failed; reason=AuthenticationFailed means the secret was rejected.

Under the hood

source-controller is small on purpose. It does not render manifests, does not apply resources, and does not know what Kustomize or Helm is.

Production discipline

1. spec.ref is pinned to a SHA or semver range, not a branch head. Branch heads move; the audit chain breaks. Use CI to bump the SHA.
2. spec.interval is sized to the change rate. The interval is the upper bound on time-to-reconcile.
3. spec.suspend is used during incident containment. kubectl patch gitrepository apps -p '{"spec":{"suspend":true}' freezes every Kustomization that consumes the source.

Cross-course references

• Kubernetes for Production Sysadmins - Part XI (CRD Status) covers the condition model the source CRDs use.
• Git, CI/CD & GitOps for Infrastructure Engineers - Part LXXV (Pull-based Deployment) is the operational pattern this controller implements; Part LXXVI (GitOps Repo Architecture) is the repository layout the GitRepository points at.

Quiz