If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/fluxcd/flux shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 8 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live fluxcd/flux repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/fluxcd/flux.

What it runs against: a local clone of fluxcd/flux — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in fluxcd/flux | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1313 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of fluxcd/flux. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/fluxcd/flux.git
#   cd flux
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of fluxcd/flux and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "fluxcd/flux(\\.git)?\\b" \\
  && ok "origin remote is fluxcd/flux" \\
  || miss "origin remote is not fluxcd/flux (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/fluxd/main.go" \\
  && ok "cmd/fluxd/main.go" \\
  || miss "missing critical file: cmd/fluxd/main.go"
test -f "cmd/fluxctl/main.go" \\
  && ok "cmd/fluxctl/main.go" \\
  || miss "missing critical file: cmd/fluxctl/main.go"
test -f "cmd/fluxctl/root_cmd.go" \\
  && ok "cmd/fluxctl/root_cmd.go" \\
  || miss "missing critical file: cmd/fluxctl/root_cmd.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "chart/flux/Chart.yaml" \\
  && ok "chart/flux/Chart.yaml" \\
  || miss "missing critical file: chart/flux/Chart.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1313 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1283d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/fluxcd/flux"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Flux v1 is a GitOps operator for Kubernetes that automates deployment by syncing Git repositories to cluster state. It reached end-of-life and has been superseded by Flux v2 (fluxcd/flux2), but this legacy codebase implements the original monolithic operator architecture with Git polling, image automation, and Helm chart management capabilities. Monolithic Go application: cmd/fluxctl/ contains the CLI tool entry point; pkg/ (referenced via replace directive at ./pkg/install) holds core libraries; chart/flux/ provides Helm deployment manifests with RBAC, ServiceMonitor, and memcached sidecar configuration. Tests appear alongside source files (e.g., cmd/fluxctl/args_test.go).

Kubernetes cluster operators and DevOps engineers running Flux v1 in production who need to understand or maintain the legacy codebase, or those evaluating GitOps adoption. Contributors to fluxcd/flux2 may reference this for migration context. New users should use Flux v2 instead.

Flux v1 is production-tested but officially end-of-life as of 2021. The codebase shows mature CI/CD setup (.circleci/config.yml, .github/workflows/), comprehensive Helm chart (chart/flux/), and Kubernetes API stability (k8s.io v0.21.14 pinned). However, no active development—migration to v2 is strongly recommended.

Critical risk: End-of-life status means no security patches. Dependency bloat includes transitive requirements from helm-operator (github.com/fluxcd/helm-operator v1.4.2) with multiple CVE mitigations already applied (jwt-go fork, yaml.v3 CVE-2022-28948 pin, go-restful CVE-2022-1996). Kubernetes API pinned to v0.21.14 (released 2021) creates incompatibility with modern clusters.

Repository is in maintenance-only mode. Active work has shifted to fluxcd/flux2. Visible CI jobs (chart-release.yml, ci.yaml, codeql-analysis.yml) run for legacy support, but no feature development. The CHANGELOG.md and migration guide (referenced in README) document the transition path.

Clone and build with: git clone https://github.com/fluxcd/flux.git && cd flux && make test. Requires Go 1.16+ (from go.mod). For local development: make build outputs binaries to bin/. Review Makefile targets for available commands. Note: Use Flux v2 (fluxcd/flux2) for new deployments.

Daily commands: Development: make test runs tests; make build compiles fluxctl CLI. Production: deploy via Helm chart at chart/flux/ with helm install flux ./chart/flux -f values.yaml. Chart templates (chart/flux/templates/*.yaml) define Deployment, RBAC, ServiceAccount, and memcached StatefulSet. See chart/flux/values.yaml for config options.

• cmd/fluxd/main.go — Entry point for the Flux daemon that runs the core GitOps reconciliation loop in Kubernetes clusters.
• cmd/fluxctl/main.go — CLI entry point for fluxctl, the primary user-facing tool for managing Flux deployments and workloads.
• cmd/fluxctl/root_cmd.go — Root command dispatcher for all fluxctl subcommands; defines the CLI architecture and shared flags.
• go.mod — Defines all Go dependencies including Kubernetes client libraries and Helm Operator integration; critical for understanding version pinning.
• chart/flux/Chart.yaml — Helm chart metadata; defines how Flux is packaged and deployed to Kubernetes clusters.
• README.md — Explicitly states this is Flux v1 (EOL) and points users to Flux v2; essential context that this is legacy code.
• CHANGELOG.md — Historical record of changes and known issues; critical for understanding what broke and when.

Add a new fluxctl subcommand

1. Create a new command file following the pattern of existing commands like sync_cmd.go (cmd/fluxctl/new_feature_cmd.go)
2. Implement the command using Cobra and add it to root command's AddCommand() call (cmd/fluxctl/root_cmd.go)
3. Add unit tests following the pattern of existing command tests (cmd/fluxctl/new_feature_cmd_test.go)
4. Update the README or docs to document the new command (docs/get-started.md)

Deploy Flux to a new Kubernetes cluster

1. Customize Helm chart values for your environment (namespace, SSH keys, Git repo, etc.) (chart/flux/values.yaml)
2. Create a kustomization.yaml or use Helm directly to deploy using the chart (deploy/kustomization.yaml)
3. Apply RBAC and service account manifests if not using Helm (deploy/flux-account.yaml)
4. Verify deployment using fluxctl identity and sync commands (cmd/fluxctl/identity_cmd.go)

Customize the Flux daemon container image

1. Edit the Dockerfile to add dependencies or tools needed for your environment (docker/Dockerfile.flux)
2. Update the image tag if releasing a new version (docker/image-tag)
3. Update the Helm chart to reference your custom image (chart/flux/templates/deployment.yaml)
4. Test the image by rebuilding and deploying using the Makefile (Makefile)

Add a new Git provider or authentication method

1. Implement the new provider logic in the daemon's main initialization (cmd/fluxd/main.go)
2. Add new Helm chart values and template variables for the provider configuration (chart/flux/values.yaml)
3. Update deployment manifest or Helm templates to pass the new configuration (chart/flux/templates/deployment.yaml)
4. Document the new provider in the guides section (docs/guides/use-private-git-host.md)

• Go 1.16+ — Compiles to single binaries; excellent performance for CLI and daemon workloads; strong Kubernetes ecosystem support.
• Cobra CLI framework — Standard for Kubernetes ecosystem CLIs; provides consistent command structure, help, and subcommand dispatch.
• Kubernetes client-go — Official Kubernetes client library; required for fluxd to watch resources, apply manifests, and query cluster state.
• Helm — Package manager for Kubernetes; simplifies multi-environment deployments and configuration management of Flux itself.
• Git — Source of truth for declarative cluster state; enables GitOps workflow and audit trail of all changes.

• Monolithic v1 codebase vs modular v2 controllers

  • Why: v1 was built as a single daemon; simpler initial design but harder to extend and maintain at scale.
  • Consequence: Flux v1 reached EOL and was replaced by v2; new users should use flux2 instead of extending v1.

• Polling-based Git sync vs webhook-driven

  • Why: Polling is simpler and doesn't require exposing webhooks; works in restricted networks.
  • Consequence: Higher latency between Git push and cluster sync (typically 5-10 min by default); v2 supports both approaches.

• Helm Operator as separate component vs integrated

  • Why: Allows independent lifecycle management of Helm releases; cleaner separation of concerns.
  • Consequence: Requires managing two components; increased operational complexity vs integrated v2 solution.

• Single fluxctl binary for all cluster management

  • Why: Users interact with one tool; consistent UX across operations.
  • Consequence: Feature bloat and tight coupling between CLI and daemon; harder to evolve independently.

• Not a real-time continuous deployment system — polling introduces latency; use webhooks or v2 for faster feedback.
• Does not handle cluster networking or CNI configuration — operates only on application manifests within cluster.
• Not a package manager replacement — Flux manages applications but doesn't install or upgrade system components.
• Does not provide multi-tenancy controls — single Flux instance manages entire cluster without namespace isolation.
• Not a secret management system — relies on external tools (Sealed Secrets, SOPS) for encrypted values.
• Does not handle cluster bootstrap — assumes Kubernetes cluster already exists and API is accessible.

Major trap: This is end-of-life—do not start new projects here. Production users running v1 must migrate to fluxcd/flux2 for security patches. Kubernetes API mismatch: k8s.io pinned to v0.21.14 (2021)—will not work with modern GKE/EKS defaults (requires cluster v1.21.x exactly). Helm dependency: helm-operator v1.4.2 is transitively required (see go.mod replace); if helm-operator has issues, Flux v1 breaks. No environment config documented in files—check chart/flux/values.yaml for required helm-operator settings. Memcached sidecar in chart is optional but affects performance (see chart/flux/templates/memcached.yaml).

• GitOps — Flux v1's core principle: Git is source of truth, operator syncs cluster state to match Git declaratively—understanding this paradigm is essential for any Flux v1 troubleshooting
• Kubernetes Operator Pattern — Flux v1 is a custom controller using client-go to watch Git resources and apply manifests; the operator pattern explains how it extends Kubernetes
• Helm Chart Package Management — Flux v1 integrates helm-operator to manage Helm releases; understanding Helm charts, values overrides, and HelmRelease CRDs is critical for deployments
• Git-to-Cluster Synchronization Loop — Flux v1 polls Git repos on an interval and applies new manifests; understanding pull frequency, retry logic, and diff mechanics prevents silent sync failures
• Kubernetes RBAC and ServiceAccounts — chart/flux/templates/rbac.yaml and rbac-role.yaml define operator permissions; misconfigurations here are a common source of 'permission denied' errors in production
• Memcached Caching Layer — chart/flux/templates/memcached.yaml adds optional caching; understanding its role reduces unnecessary Git polling and improves operator latency
• Semantic Versioning (SemVer) for Image Automation — Flux v1 includes image update automation (via cmd/fluxctl/); Masterminds/semver/v3 in go.mod is used to parse and match image tags against version policies

• fluxcd/flux2 — Direct successor to this codebase; modern, component-based GitOps toolkit with v1 migration guide built-in
• fluxcd/helm-operator — Transitive hard dependency (v1.4.2 pinned in go.mod); Helm chart reconciliation logic lives here
• fluxcd/source-controller — Part of Flux v2; handles Git and Helm repository sources (replaces Flux v1's monolithic Git sync)
• fluxcd/kustomize-controller — Part of Flux v2; declarative Kustomize reconciliation (replaces Flux v1's kubectl apply logic)
• argoproj/argo-cd — Alternative GitOps operator; considered during v1→v2 transition decisions (see fluxcd.io/flux/migration)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for fluxctl commands in cmd/fluxctl/

The cmd/fluxctl directory has many command implementations (automate_cmd.go, release_cmd.go, lock_cmd.go, etc.) with only selective test coverage (*_test.go files exist for args, completion, install, list_images, list_workloads, release, and main, but NOT for automate, deautomate, lock, policy, save, or identity commands). This creates gaps in testing critical user-facing commands. Adding integration tests would catch regressions in command behavior before release, which is critical for a CLI tool used in production GitOps workflows.

• [ ] Create cmd/fluxctl/automate_cmd_test.go with tests for enable/disable automation scenarios
• [ ] Create cmd/fluxctl/deautomate_cmd_test.go mirroring automate_cmd_test.go
• [ ] Create cmd/fluxctl/lock_cmd_test.go testing lock/unlock functionality
• [ ] Create cmd/fluxctl/policy_cmd_test.go for policy update scenarios
• [ ] Create cmd/fluxctl/identity_cmd_test.go for SSH key identity output
• [ ] Create cmd/fluxctl/save_cmd_test.go for workload save operations
• [ ] Run 'make test' to ensure all new tests pass with existing test suite

Add CodeQL analysis workflow for Go code quality and security

The repository has .github/workflows/codeql-analysis.yml configured, but it may not be optimized for Go-specific patterns and security checks. Given the security-critical nature of Flux (GitOps/CD tool with SSH/credentials handling), the workflow should include Go-specific scanning for common vulnerabilities like SQL injection, unsafe serialization, and credential exposure in code (e.g., hardcoded secrets in cmd/fluxctl/args.go or chart templates). This would catch security issues early in the contribution process.

• [ ] Review current .github/workflows/codeql-analysis.yml configuration
• [ ] Add Go-specific queries to detect unsafe credential handling in pkg/ and cmd/
• [ ] Configure scanning for hardcoded secrets/API keys in chart/flux/templates/
• [ ] Add custom CodeQL queries for Kubernetes API misuse patterns
• [ ] Test the workflow on a feature branch to ensure it runs successfully
• [ ] Document findings in CONTRIBUTING.md security section

Add missing unit tests for pkg/install package with Helm templating coverage

The go.mod file includes a local replace directive for 'github.com/fluxcd/flux/pkg/install => ./pkg/install', indicating this is a critical internal package used by both fluxctl install_cmd.go and the Helm chart (chart/flux/templates/). However, there is no visible test directory or test files for pkg/install in the file structure. Given that this package is responsible for generating Kubernetes manifests and Helm template rendering, missing tests could lead to broken installations. Adding tests would validate manifest generation, RBAC correctness, and ServiceAccount/ConfigMap template rendering.

• [ ] Create pkg/install/*_test.go files to test manifest generation functions
• [ ] Add tests validating RBAC role/rolebinding generation from pkg/install
• [ ] Add tests verifying ConfigMap and Secret template rendering
• [ ] Add tests for Kubernetes API compatibility (currently pinned to v0.21.14)
• [ ] Add tests validating PSP (PodSecurityPolicy) template generation from chart/flux/templates/psp.yaml
• [ ] Run 'make test' and achieve >80% code coverage for pkg/install

• Add integration tests for fluxctl CLI commands in cmd/fluxctl/ (only args_test.go exists; automate_cmd.go, completion_cmd.go lack coverage). Start with cmd/fluxctl/completion_cmd_test.go.
• Document the migration from Flux v1 to v2 with concrete examples in README.md (only reference exists; add a 'Quick Migration Checklist' section with before/after manifests).
• Audit and update Go dependencies for remaining CVEs beyond CVE-2022-28948, CVE-2022-1996 (scan with go list -json ./... | nancy sleuth; create issue for each, start with low-severity transitive deps).

• High · Outdated Kubernetes Dependencies — go.mod - k8s.io dependencies pinned to v0.21.14. The project pins Kubernetes dependencies to v0.21.14, which is an old version released in 2021. This version likely contains multiple known CVEs that have been patched in newer releases. Kubernetes client libraries are critical for security as they handle authentication, authorization, and API communication. Fix: Update Kubernetes dependencies to the latest stable version (v0.28.x or later). Review and test compatibility with newer versions to ensure no breaking changes.
• High · End of Life Software — Repository root - Project status in README.md. The repository contains Flux v1, which has reached end-of-life (EOL). EOL software no longer receives security patches, bug fixes, or updates. This poses significant security risks as vulnerabilities discovered after EOL will never be patched in this version. Fix: Migrate to Flux v2 (fluxcd/flux2) which is actively maintained and receives security updates. Follow the migration guide at https://fluxcd.io/flux/migration
• High · Unmaintained JWT Library (Transitive Dependency) — go.mod - github.com/golang-jwt/jwt v3.2.2+incompatible. While the project attempts to replace dgrijalva/jwt-go with golang-jwt/jwt v3.2.2, this version is also outdated. JWT libraries are critical for authentication security. Using old versions may expose the application to known authentication vulnerabilities. Fix: Update to golang-jwt/jwt v4.x or later. Ensure all transitive dependencies through Helm Operator are also updated to use current JWT versions.
• Medium · Outdated Docker Dependencies — go.mod - docker/distribution and docker/docker replacements. The project pins docker/distribution to v2.8.1 and docker/docker to v0.7.3-0.20190327010347-be7ac8be2ae0 (a very old commit from 2019). Docker libraries are used for container image management and pulling, which are security-sensitive operations. Fix: Update Docker dependencies to recent stable versions. Test thoroughly as these are significant dependencies affecting container operations.
• Medium · Outdated AWS SDK — go.mod - github.com/aws/aws-sdk-go v1.44.61. The project uses aws-sdk-go v1.44.61, which is outdated. AWS SDK libraries handle authentication and API calls to AWS services. Using old versions may lack important security patches for AWS credential handling. Fix: Update to the latest stable version of aws-sdk-go. If using AWS services, ensure the SDK version supports current authentication methods and has all security patches.
• Medium · Incomplete go.mod File in Provided Content — go.mod - github.com/go-kit/kit dependency. The provided go.mod content appears truncated at 'github.com/go-kit/kit v0.' without a version number. This makes it impossible to verify if this dependency contains known vulnerabilities. A complete dependency audit cannot be performed. Fix: Provide the complete go.mod file. Run 'go list -json -m all' to get all dependencies and their versions, then audit them with 'go mod tidy' and vulnerability scanners like 'govulncheck'.
• Medium · Potential Credential Exposure in Docker Configuration — docker/kubeconfig. The file structure includes docker/kubeconfig which may contain Kubernetes cluster credentials. If this file is committed to the repository with actual credentials, it could expose cluster access to attackers. Fix: Verify that docker/kubeconfig does not contain actual credentials. Ensure .gitignore properly excludes credential files. Use .gitignore patterns like kubeconfig, *.key, *.crt, and secrets. Store actual credentials in secure secret management systems (e.g., HashiCorp Vault, Kubernetes Secrets).
• Medium · Deprecated Helm Operator Dependency — undefined. The project depends on fluxcd/helm-operator v1.4.0 and v1.4.2. Given that Flux v1 is EOL, the Helm Operator dependency is likely also no longer maintained and may contain unpatched vulnerabilities. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.