Learning GitOps - FluxCD - Source Management - Git, Helm, OCI, Buckets

#Introduction

In episode 8 you referenced Helm charts as a source. This episode opens up every source type Flux supports and its advanced features. This matters because sources are the heart of GitOps: anything that enters the cluster passes through the Source Controller.

We'll dissect advanced GitRepository, HelmRepository, OCIRepository, Bucket, and then how to verify source authenticity with GPG and Cosign.

#Advanced GitRepository

#Git References

Beyond branch, ref can point to a tag, commit, or semver:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: webapp
  namespace: flux-system
spec:
  interval: 5m
  ref:
    tag: v1.2.0
 
  # or commit:
  # ref:
  #   commit: 3f4a8c9d21e0b4a1
 
  # or semver:
  # ref:
  #   semver: ">=1.0.0 <2.0.0"
 
  url: https://github.com/arman/webapp-manifests.git

• tag — points to a specific release version; stable for production.
• commit — pins to a commit hash; the most deterministic.
• semver — Flux selects the highest tag matching the range, then automatically moves up when a new tag appears.

#Submodules and Filtering

Large repos can be slimmed down in two ways. First, enable submodules:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: fleet
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/arman/fleet.git
  ref:
    branch: main
  gitImplementation: go-git
  recurseSubmodules: true

Second, limit which files get copied via include and exclude (gitignore patterns). This reduces clone load and speeds up reconciliation for very large repos:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: fleet
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/arman/fleet.git
  ref:
    branch: main
  ignore: |
    .github
    docs/
    **/*.md

#GPG Verification

To make sure a commit really comes from a legitimate author, enable GPG verification:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: webapp
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/arman/webapp-manifests.git
  ref:
    branch: main
  verify:
    mode: head
    secretRef:
      name: gpg-public-keys

#HelmRepository

A HelmRepository is essentially one of two things: a directory containing an index.yaml, or an OCI registry. For a regular HTTP repo, Flux downloads index.yaml then fetches the charts it needs.

Authentication is similar to GitRepository — via a basic auth or token Secret:

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: internal
  namespace: flux-system
spec:
  interval: 1h
  url: https://helm.internal.acme.com/charts
  secretRef:
    name: helm-auth
  timeout: 60s
  passCredentials: true

• passCredentials — sends credentials to all requests, not just the main host. Useful when charts are hosted in object storage that requires per-request auth.
• certSecretRef — mounts a custom CA for TLS.
• insecure: true — turns off TLS verification, lab only.

#OCIRepository

OCIRepository is a generic source for OCI artifacts: charts, images, or manifests packaged as OCI layers. It's lighter than a Git clone and great for large repos or distributing charts to many clusters.

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: webapp-chart
  namespace: flux-system
spec:
  interval: 10m
  url: oci://registry.internal.acme.com/charts/webapp
  ref:
    tag: 1.2.0
  secretRef:
    name: registry-auth
  layerSelector:
    mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip

Authentication uses a dockerconfigjson type Secret:

flux create secret oci registry-auth \
  --url=oci://registry.internal.acme.com/charts \
  --username=arman \
  --password=$REGISTRY_PASSWORD

The most common use cases: distributing manifests to many clusters without cloning Git, and distributing internal charts already scanned and approved by the security team.

#Bucket

For static artifacts (S3-compatible, GCS, Azure Blob), Flux has Bucket. This source downloads files from object storage periodically:

apiVersion: source.toolkit.fluxcd.io/v1
kind: Bucket
metadata:
  name: manifests
  namespace: flux-system
spec:
  interval: 10m
  provider: generic
  bucketName: my-app-manifests
  endpoint: https://s3.ap-southeast-1.amazonaws.com
  region: ap-southeast-1
  secretRef:
    name: s3-credentials

For GCS and Azure, just change provider:

Bucket is useful when manifests are produced by a CI pipeline (e.g. build output) and uploaded to storage, so the cluster doesn't need Git access.

#Source Verification

Beyond GPG in Git, Flux verifies OCI artifacts with Cosign. Create an OCIRepository with a verify block:

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: webapp
  namespace: flux-system
spec:
  interval: 10m
  url: oci://registry.internal.acme.com/apps/webapp
  verify:
    provider: cosign
    secretRef:
      name: cosign-public-keys

Public keys for GPG and Cosign are stored in a Secret in flux-system; the Source Controller also uses a Key Management Service (e.g. AWS KMS or Azure Key Vault) for cloud-managed keys. There are two behavioral modes:

• failOnVerificationFailure: true — verification is mandatory; unsigned artifacts are rejected.
• ignoreNotVerified — verifies only, does not reject unsigned artifacts.

#Closing

All configuration entry paths are now open:

• GitRepository supports branch, tag, commit, semver, submodules, filtering, and GPG verification.
• HelmRepository handles chart indexes, authentication, TLS, and passCredentials.
• OCIRepository brings charts and manifests in as lightweight OCI artifacts.
• Bucket serves static artifacts from S3, GCS, or Azure Blob.
• GPG and Cosign ensure a source truly comes from a trusted party.

Your sources are now diverse. In episode 10 we'll manage orchestration: dependsOn, health checks, deploy ordering strategies, and complex scenarios like database before application. See you!