Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
fluxcd avatar

Gitops Knowledge

fluxcd/agent-skills

  • 549 installs
  • 202 repo stars
  • Updated August 4, 2026
  • fluxcd/agent-skills

gitops-knowledge is a Flux CD agent skill that answers GitOps questions and generates schema-validated YAML for 19 Flux CRDs for developers implementing Kubernetes delivery with Flux Operator and Git or OCI sources.

About

A Flux CD and Flux Operator knowledge base that answers GitOps concepts and produces correct, schema-validated manifests for all Flux CRDs. A developer uses it for Flux repo structure, bootstrap, multi-tenancy, OCI delivery, image automation, or drift detection guidance.

  • Generates schema-validated YAML for HelmRelease, Kustomization, GitRepository, and more
  • Prefers Flux Operator FluxInstance over legacy flux bootstrap

Gitops Knowledge by the numbers

  • 549 all-time installs (skills.sh)
  • Ranked #257 of 1,435 DevOps & CI/CD skills by installs in the Skillselion catalog
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/fluxcd/agent-skills --skill gitops-knowledge

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs549
repo stars★ 202
Last updatedAugust 4, 2026
Repositoryfluxcd/agent-skills ↗

How do you generate valid Flux CD HelmRelease YAML manifests?

Answers Flux CD questions and generates schema-validated YAML for Flux CRDs like HelmRelease, Kustomization, GitRepository, and FluxInstance.

Who is it for?

Platform engineers implementing Flux CD GitOps who need correct HelmRelease, Kustomization, or FluxInstance YAML without reading full Flux documentation.

Skip if: Live Kubernetes cluster debugging or repository security audits, which require the sibling gitops-cluster-debug or gitops-repo-audit skills instead.

When should I use this skill?

User asks about Flux CD concepts, requests HelmRelease or Kustomization manifests, multi-tenancy setup, OCI delivery, or GitOps repository structure.

What you get

Schema-validated Flux CRD YAML manifests, GitOps architecture guidance, and ResourceSet or FluxInstance configuration for Kubernetes clusters.

  • Flux CRD YAML manifests
  • GitOps architecture guidance
  • ResourceSet templates

By the numbers

  • Documents 19 Flux custom resource kinds with bundled OpenAPI validation schemas
  • Part of a 3-skill fluxcd/agent-skills collection alongside repo-audit and cluster-debug
  • Includes 9 topic reference guides from repo-patterns through gitless image automation

Files

SKILL.mdMarkdownGitHub ↗

Flux CD Knowledge Base

You are an expert on Flux CD, the GitOps toolkit for Kubernetes. Use this knowledge base to answer questions accurately, generate correct YAML manifests, and explain Flux concepts.

Rules:

  • Always use the exact apiVersion/kind combinations from the CRD table below. Never invent API versions.
  • Before generating YAML for any CRD, read its OpenAPI schema from assets/schemas/ to verify field names, types, and enum values.
  • When a question requires detail beyond this file, load the relevant reference file from references/.
  • Prefer Flux Operator (FluxInstance) for cluster setup. Do not reference flux bootstrap or legacy gotk-* files.

What is Flux

Flux is a set of Kubernetes controllers that implement GitOps — the practice of using Git (or OCI registries) as the source of truth for declarative infrastructure and applications. Flux continuously reconciles the desired state stored in sources with the actual state of the cluster.

Flux Operator manages the Flux installation declaratively through a FluxInstance custom resource. It handles installation, configuration, upgrades, and lifecycle of all Flux controllers. Only one FluxInstance named flux can exist per cluster.

How resources relate:

Sources (Git, OCI, Helm, Bucket)
  │
  ▼ produce artifacts
Artifacts (tarballs, Helm charts, OCI layers)
  │
  ▼ consumed by
Appliers (Kustomization, HelmRelease)
  │
  ▼ create/update
Managed Resources (Deployments, Services, ConfigMaps, ...)
  │
  ▼ status reported to
Notifications (Provider + Alert → Slack, Teams, GitHub, ...)

ResourceSet orchestration flow:

ResourceSetInputProvider (GitHub PRs, OCI tags, ...)
  │
  ▼ exports inputs
ResourceSet (template + input matrix)
  │
  ▼ generates per-input
Namespaces, Sources, Kustomizations, HelmReleases, RBAC, ...

Two delivery models:

  • Git-based: Flux watches Git repositories and applies changes on commit.
  • Gitless (OCI-based): Git → CI pushes OCI artifacts → Flux pulls from registry. OCI artifacts

are immutable, signed, and don't require Git credentials on clusters.

Controllers and CRDs

KindapiVersionControllerPurpose
FluxInstancefluxcd.controlplane.io/v1flux-operatorManages Flux installation lifecycle
FluxReportfluxcd.controlplane.io/v1flux-operatorRead-only observed state of Flux
ResourceSetfluxcd.controlplane.io/v1flux-operatorTemplate resources from input matrix
ResourceSetInputProviderfluxcd.controlplane.io/v1flux-operatorFetch inputs from external services
GitRepositorysource.toolkit.fluxcd.io/v1source-controllerFetch from Git repositories
OCIRepositorysource.toolkit.fluxcd.io/v1source-controllerFetch OCI artifacts from registries
HelmRepositorysource.toolkit.fluxcd.io/v1source-controllerIndex Helm chart repositories
HelmChartsource.toolkit.fluxcd.io/v1source-controllerFetch and package Helm charts
Bucketsource.toolkit.fluxcd.io/v1source-controllerFetch from S3-compatible storage
ExternalArtifactsource.toolkit.fluxcd.io/v1(external)Generic artifact storage for 3rd-party controllers
ArtifactGeneratorsource.extensions.fluxcd.io/v1beta1source-controllerCompose/decompose artifacts from multiple sources
Kustomizationkustomize.toolkit.fluxcd.io/v1kustomize-controllerBuild and apply Kustomize overlays or plain YAML
HelmReleasehelm.toolkit.fluxcd.io/v2helm-controllerInstall and manage Helm releases
Providernotification.toolkit.fluxcd.io/v1beta3notification-controllerExternal notification provider config
Alertnotification.toolkit.fluxcd.io/v1beta3notification-controllerRoute events to notification providers
Receivernotification.toolkit.fluxcd.io/v1notification-controllerWebhook receiver for incoming events
ImageRepositoryimage.toolkit.fluxcd.io/v1image-reflector-controllerScan container image registries
ImagePolicyimage.toolkit.fluxcd.io/v1image-reflector-controllerSelect image by version policy
ImageUpdateAutomationimage.toolkit.fluxcd.io/v1image-automation-controllerUpdate YAML in Git with new image tags

How Flux Works

Reconciliation Loop

Flux controllers run a continuous reconciliation loop:

1. Sources poll for changes — source-controller checks Git repos, OCI registries, Helm repos, or S3 buckets at configured intervals and produces versioned artifacts. 2. Appliers consume artifacts — kustomize-controller and helm-controller detect new artifact revisions, build manifests (Kustomize overlays or Helm templates), and apply them to the cluster using server-side apply. 3. Drift detection and self-healing — Flux compares the desired state from the source with the live state in the cluster. When drift is detected, Flux corrects it automatically (if enabled). 4. Notifications report status — notification-controller sends events to external systems (Slack, Teams, GitHub commit status, etc.) based on Alert rules.

Dependency Ordering

Use dependsOn to control reconciliation order. For example, install CRDs before CRs, or infrastructure before applications:

spec:
  dependsOn:
    - name: infra-controllers  # wait for this Kustomization to be Ready

ResourceSets support richer dependencies with readyExpr (CEL expressions) and can depend on any type of resource:

spec:
  dependsOn:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSet
      name: policies
      ready: true
      readyExpr: "status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'True')"

Reactivity with Watch Labels

By default, Flux controllers poll sources at the configured interval. To react immediately when a dependency changes, add the watch label to the upstream resource:

metadata:
  labels:
    reconcile.fluxcd.io/watch: Enabled

When a ConfigMap or Secret with this label changes, any Kustomization or HelmRelease that references it via postBuild.substituteFrom or valuesFrom will reconcile immediately.

Decision Trees

Which Source Type?

  • Git repo with Kustomize overlays or plain YAML → GitRepository
  • OCI artifact (container image with manifests) → OCIRepository
  • Helm chart from OCI registry → OCIRepository with layerSelector for Helm media type
  • Helm chart from HTTPS Helm repo → HelmRepository (default type)
  • S3/GCS/MinIO bucket → Bucket
  • Monorepo that needs splitting → ArtifactGenerator (creates ExternalArtifact per path)
  • Helm chart + env-specific values from Git → ArtifactGenerator (composes chart with values overlay)

Kustomization vs HelmRelease?

  • Plain YAML or Kustomize overlays → Kustomization
  • Helm chart → HelmRelease
  • Both can deploy to remote clusters via kubeConfig and support dependsOn.

ResourceSet vs Kustomization?

  • One set of manifests, one deployment → Kustomization
  • Same template deployed for N inputs (tenants, components, environments) → ResourceSet
  • ResourceSets generate resources from an input matrix; Kustomizations apply a fixed set of manifests.

How to Set Up GitOps from Scratch

1. Install Flux Operator (Helm chart or Terraform) 2. Create a FluxInstance named flux in the flux-system namespace 3. Configure .spec.sync to point to your Git repo or OCI registry 4. Organize manifests in the source repo using Kustomize base+overlay pattern 5. Create Kustomization resources to apply manifests from the source 6. Add Provider + Alert for notifications

Canonical YAML Patterns

1. GitOps Pipeline (GitRepository + Kustomization)

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/org/my-app.git
  ref:
    branch: main
  secretRef:
    name: git-credentials  # optional, for private repos
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: my-app
  path: ./deploy/production
  prune: true
  wait: true
  timeout: 5m

2. Helm from HTTPS Repository

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: metrics-server
  namespace: kube-system
spec:
  interval: 1h
  url: https://kubernetes-sigs.github.io/metrics-server/
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: metrics-server
  namespace: kube-system
spec:
  interval: 30m
  chart:
    spec:
      chart: metrics-server
      version: "3.x"
      sourceRef:
        kind: HelmRepository
        name: metrics-server
  values:
    args:
      - --kubelet-insecure-tls

3. Helm from OCI Registry (Recommended)

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: cert-manager-chart
  namespace: cert-manager
spec:
  interval: 1h
  url: oci://quay.io/jetstack/charts/cert-manager
  layerSelector:
    mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
    operation: copy
  ref:
    semver: "1.x"
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: cert-manager
  namespace: cert-manager
spec:
  interval: 1h
  chartRef:
    kind: OCIRepository
    name: cert-manager-chart
  install:
    strategy:
      name: RetryOnFailure
      retryInterval: 5m
  upgrade:
    strategy:
      name: RetryOnFailure
      retryInterval: 5m
  values:
    crds:
      enabled: true

4. FluxInstance with OCI Sync (Gitless GitOps)

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.x"
    registry: "ghcr.io/fluxcd"
  components:
    - source-controller
    - source-watcher
    - kustomize-controller
    - helm-controller
    - notification-controller
  cluster:
    type: kubernetes
    size: medium
    multitenant: true
    tenantDefaultServiceAccount: flux
    networkPolicy: true
  sync:
    kind: OCIRepository
    url: "oci://ghcr.io/my-org/fleet-manifests"
    ref: "latest"
    path: "clusters/production"
    pullSecret: "registry-auth"

5. ResourceSet for Multi-Component Orchestration

apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
metadata:
  name: apps
  namespace: flux-system
spec:
  inputs:
    - tenant: "frontend"
      environment: "production"
    - tenant: "backend"
      environment: "production"
  resources:
    - apiVersion: v1
      kind: Namespace
      metadata:
        name: << inputs.tenant >>
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: OCIRepository
      metadata:
        name: apps
        namespace: << inputs.tenant >>
      spec:
        interval: 5m
        url: "oci://ghcr.io/my-org/apps/<< inputs.tenant >>"
        ref:
          tag: latest
    - apiVersion: kustomize.toolkit.fluxcd.io/v1
      kind: Kustomization
      metadata:
        name: apps
        namespace: << inputs.tenant >>
      spec:
        interval: 30m
        wait: true
        prune: true
        sourceRef:
          kind: OCIRepository
          name: apps
        path: "./<< inputs.environment >>"

For the full multi-tenant pattern — per-tenant ServiceAccount + RoleBinding, serviceAccountName impersonation, dependsOn, and the reconcileEvery annotation — load references/resourcesets.md.

6. Image Automation

Flux supports two delivery models for updating container images and Helm chart versions. Pick based on whether the team wants Git commits as the audit log for version changes:

  • Git-based — ImageRepository + ImagePolicy + ImageUpdateAutomation scan the

registry and commit tag bumps back to Git via $imagepolicy YAML markers. Requires image-reflector-controller and image-automation-controller on the cluster. Load references/image-automation.md.

  • Gitless — ResourceSet + ResourceSetInputProvider (type: OCIArtifactTag)

scans the registry and re-renders the ResourceSet directly, upgrading the downstream HelmRelease or Kustomization without touching Git. No bot credentials, no Git poll lag, no extra controllers. Recommended default for Flux Operator deployments. Load references/gitless-image-automation.md.

Gitless is the better fit when the tag lives in Helm values, when tags should differ per cluster in a fleet, or when the team doesn't want a bot writing to the repo. Git-based is the better fit when PR-based approval of version bumps is required or when Git must remain the canonical record of every deployed version.

7. Notifications (Slack, GitHub, Webhooks)

Provider + Alert for outgoing notifications, Receiver for incoming webhooks. Alert and Provider use v1beta3, Receiver uses v1.

For Slack, GitHub commit status, webhook receivers, and all provider types, load references/notifications.md.

Common Mistakes

Wrong template delimiters:

  • ResourceSet uses << inputs.field >> — NOT {{ .inputs.field }} or {{ inputs.field }}
  • Go templates {{ }} are only used in ImageUpdateAutomation .spec.git.commit.messageTemplate

Mutual exclusivity:

  • HelmRelease: spec.chart.spec and spec.chartRef are mutually exclusive
  • FluxInstance: only one per cluster, must be named flux

HelmRelease strategy fields:

  • Install/upgrade strategy is at spec.install.strategy.name and spec.upgrade.strategy.name
  • Always use RetryOnFailure — it retries without rollback or uninstall, avoiding downtime
  • Do not use RemediateOnFailure or spec.install.remediation / spec.upgrade.remediation

OCIRepository for Helm charts:

  • When using OCIRepository to fetch Helm charts from OCI registries, set layerSelector to extract the chart:
  layerSelector:
    mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
    operation: copy

Reference Index

Load reference files and OpenAPI schemas based on the question topic. Load at most 1-2 reference files per question. Read schemas for field-level validation when generating YAML.

CRDReferenceSchema
FluxInstancereferences/flux-operator.mdassets/schemas/fluxinstance-fluxcd-v1.json
FluxReportreferences/flux-operator.mdassets/schemas/fluxreport-fluxcd-v1.json
ResourceSetreferences/resourcesets.mdassets/schemas/resourceset-fluxcd-v1.json
ResourceSetInputProviderreferences/resourcesets.mdassets/schemas/resourcesetinputprovider-fluxcd-v1.json
GitRepositoryreferences/sources.mdassets/schemas/gitrepository-source-v1.json
OCIRepositoryreferences/sources.mdassets/schemas/ocirepository-source-v1.json
HelmRepositoryreferences/sources.mdassets/schemas/helmrepository-source-v1.json
HelmChartreferences/sources.mdassets/schemas/helmchart-source-v1.json
Bucketreferences/sources.mdassets/schemas/bucket-source-v1.json
ExternalArtifactreferences/sources.mdassets/schemas/externalartifact-source-v1.json
ArtifactGeneratorreferences/sources.mdassets/schemas/artifactgenerator-source-v1beta1.json
Kustomizationreferences/kustomization.mdassets/schemas/kustomization-kustomize-v1.json
HelmReleasereferences/helmrelease.mdassets/schemas/helmrelease-helm-v2.json
Providerreferences/notifications.mdassets/schemas/provider-notification-v1beta3.json
Alertreferences/notifications.mdassets/schemas/alert-notification-v1beta3.json
Receiverreferences/notifications.mdassets/schemas/receiver-notification-v1.json
ImageRepositoryreferences/image-automation.mdassets/schemas/imagerepository-image-v1.json
ImagePolicyreferences/image-automation.mdassets/schemas/imagepolicy-image-v1.json
ImageUpdateAutomationreferences/image-automation.mdassets/schemas/imageupdateautomation-image-v1.json
TopicReference
Repository structure, monorepo vs multi-repo, OCI-based fleet managementreferences/repo-patterns.md
Best practices, dependency management, remediation, versioningreferences/best-practices.md
Web UI, dashboard, SSO, OIDC, Dex, Keycloak, Entra ID, RBACreferences/web-ui.md
MCP Server, AI assistant integration, in-cluster deploymentreferences/mcp-server.md
Terraform bootstrap of Flux Operatorreferences/terraform-bootstrap.md
Gitless GitOps, Flux OCI artifacts, flux push artifact, registry-based deliveryreferences/gitless-gitops.md
Gitless image automation (ResourceSet + OCIArtifactTag)references/gitless-image-automation.md

Related skills

microsoftAzure DeploySafely execute production deployments of already-prepared applications to Microsoft Azure.485k1.3kmicrosoftAzure ValidateRun deep pre-deployment checks on Azure configuration, infrastructure definitions, RBAC roles, and managed identities before pushing to production.485k1.3kxixu-meGithub Actions DocsGet precise, docs-grounded answers about GitHub Actions workflows, syntax, security, and migration instead of relying on stale knowledge.275k72mattpocockSetup Pre CommitAutomatically run Prettier, type checking, and tests on every commit via Husky and lint-staged.170k199kvercel-labsDeploy To VercelSafely turn any local project into a live Vercel preview with one instruction.99.3k29.7kvercel-labsVercel Cli With TokensDeploy projects to Vercel from agents and scripts using token authentication instead of interactive browser login.74.6k29.7k

How it compares

Pick gitops-knowledge over generic Kubernetes skills when you need Flux-specific CRD YAML with OpenAPI validation rather than kubectl troubleshooting commands.

FAQ

What Flux resources does gitops-knowledge generate?

gitops-knowledge generates schema-validated YAML for 19 Flux CRDs including GitRepository, OCIRepository, HelmRelease, Kustomization, ResourceSet, FluxInstance, and image automation resources. OpenAPI schemas in assets/schemas validate field names before output.

Does gitops-knowledge debug live Kubernetes clusters?

gitops-knowledge answers Flux concepts and generates manifests but does not debug live clusters or audit repositories. Use the sibling gitops-cluster-debug or gitops-repo-audit skills from fluxcd/agent-skills for those tasks.

What GitOps delivery models does gitops-knowledge cover?

gitops-knowledge covers Git-based delivery where Flux polls repositories and gitless OCI-based delivery where CI pushes artifacts to registries. Decision trees help pick GitRepository, OCIRepository, or HelmRepository source types.

DevOps & CI/CDdeployinfra
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.