# Fluxcd

> Operational skill for agents to run GitOps with Flux CD - GitRepository, Kustomization, HelmRelease, image automation, and reconciliation debugging.

- Skill: `alivirgo/fluxcd` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alivirgo/fluxcd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alivirgo/fluxcd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alivirgo (https://skillmd.com/u/alivirgo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alivirgo/fluxcd

---


# Flux CD GitOps AI Skill Guide

## Overview

Flux reconciles Kubernetes clusters from Git using composable controllers: **source-controller** (GitRepository, OCIRepository, HelmRepository), **kustomize-controller**, **helm-controller**, and optional **image-automation**. Unlike a single Application CR, Flux models sources and apply pipelines as separate objects. Agents should debug by reading Ready conditions on each object in the dependency chain.

```
GitRepository / OCIRepository
        |
        v
Kustomization / HelmRelease  -->  cluster apply
        ^
ImageRepository + ImagePolicy + ImageUpdateAutomation (optional)
```

## When to use

- Bootstrapping Flux on a cluster (`flux bootstrap`)
- Authoring GitRepository + Kustomization or HelmRelease pipelines
- Debugging stalled reconciliations and chart render errors
- Image tag automation updating Git automatically

## Operational directives

1. Trace Ready conditions from source -> Kustomization/HelmRelease -> workload health.
2. Prefer immutable digests in production overlays; use image automation deliberately.
3. Keep bootstrap and tenant paths separated; restrict Impersonation / SA privileges.
4. Use `flux reconcile` after Git pushes when waiting on long intervals is costly.
5. Do not manually patch Flux-managed resources without suspending first.

## Concrete examples

### Bootstrap (GitHub)

```bash
flux bootstrap github \
  --owner=example \
  --repository=fleet-gitops \
  --branch=main \
  --path=clusters/prod \
  --personal
```

### GitRepository + Kustomization

```yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: platform
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/example/fleet-gitops
  ref: { branch: main }
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: api
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/api/prod
  prune: true
  sourceRef:
    kind: GitRepository
    name: platform
  targetNamespace: api
```

### HelmRelease sketch

```yaml
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: redis
  namespace: data
spec:
  interval: 10m
  chart:
    spec:
      chart: redis
      version: "19.x"
      sourceRef:
        kind: HelmRepository
        name: bitnami
        namespace: flux-system
  values:
    auth:
      enabled: true
```

### CLI debug chain

```bash
flux get sources git
flux get kustomizations
flux get helmreleases -A
flux logs --kind=Kustomization --name=api
flux reconcile source git platform
flux reconcile kustomization api --with-source
flux suspend kustomization api
flux resume kustomization api
```

## Condition cheat sheet

| Object | Not Ready clue | Action |
| :--- | :--- | :--- |
| GitRepository | auth / clone fail | Fix secret, URL, ref |
| Kustomization | build/apply error | `flux logs`; fix YAML |
| HelmRelease | values/schema | `helm template` locally; pin chart |
| ImagePolicy | no tag match | Fix semver policy filter |

## Best practices

1. Directory-per-cluster under `clusters/` with clear promotion paths.
2. Enable prune carefully; review inventory before first automated prune.
3. Use OCI artifacts for air-gapped or signed delivery when required.
4. Document suspend/resume runbook for incident freezes.

## Limitations

- Flux does not replace CI builds; it consumes artifacts and manifests.
- Multi-tenancy needs careful RBAC and namespace isolation.
- HelmRelease debugging can be opaque without local helm rendering.

## Related skills

- `argocd` - alternative GitOps UX and Application model
- `kubernetes` - workload-level failure diagnosis
- `trivy` - scan images before automation bumps tags
- `makefile-automation` - local render/validate targets for GitOps repos