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/flux2 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 the board

• Last commit 1d ago
• 14 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{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/flux2 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/fluxcd/flux2.

What it runs against: a local clone of fluxcd/flux2 — 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/flux2 | 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 main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of fluxcd/flux2. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/fluxcd/flux2.git
#   cd flux2
#
# 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/flux2 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "fluxcd/flux2(\\.git)?\\b" \\
  && ok "origin remote is fluxcd/flux2" \\
  || miss "origin remote is not fluxcd/flux2 (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/flux/bootstrap.go" \\
  && ok "cmd/flux/bootstrap.go" \\
  || miss "missing critical file: cmd/flux/bootstrap.go"
test -f "cmd/flux/create.go" \\
  && ok "cmd/flux/create.go" \\
  || miss "missing critical file: cmd/flux/create.go"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f ".goreleaser.yml" \\
  && ok ".goreleaser.yml" \\
  || miss "missing critical file: .goreleaser.yml"
test -f ".github/workflows/release.yaml" \\
  && ok ".github/workflows/release.yaml" \\
  || miss "missing critical file: .github/workflows/release.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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/flux2"
  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 v2 is a declarative, GitOps-based continuous delivery platform for Kubernetes that automatically syncs cluster state to Git repositories and OCI artifacts. It's built on the GitOps Toolkit—a set of Kubernetes API extensions (custom resources and controllers)—enabling multi-tenant GitOps workflows without polling or webhooks. Core capabilities include automated image updates, Helm release management, SOPS integration for secrets, and support for arbitrary numbers of Git sources. Monorepo: cmd/flux/ contains the CLI entry point; internal/ houses CLI command implementations; .github/workflows/ orchestrates testing, release, and AUR package publishing. Flux bootstraps itself using GitOps Toolkit CRDs (GitRepository, Kustomization, HelmRelease, ImagePolicy, etc.) defined in dependent controller repos. Architecture is plugin-based: controllers handle specific domains (source control, image automation, Helm, notifications).

Platform engineers and DevOps teams who want to implement GitOps on Kubernetes; SREs deploying multi-tenant clusters; developers integrating continuous delivery into CI/CD pipelines. Users consume Flux via the flux CLI (built from cmd/flux) or directly instantiate CRDs in their clusters.

Production-ready and CNCF graduated. The codebase is mature (1.3M+ Go LOC) with comprehensive CI/CD workflows (.github/workflows/), security scanning, conformance testing across cloud providers (e2e-azure.yaml, e2e-gcp.yaml), and active maintenance visible through dependabot.yml and release.yaml. Currently targets Go 1.26.0.

Low production risk but moderate dependency surface: relies on 40+ fluxcd-managed sub-controllers (helm-controller, image-automation-controller, kustomize-controller, source-controller, notification-controller all pinned in go.mod). Breaking changes can ripple across dependent controllers; monitor CONTRIBUTING.md and release notes. Single-org governance (fluxcd) mitigates maintenance risk but vendor lock-in considerations exist for multi-cluster deployments.

Active development on conformance testing (conformance.yaml), cloud-provider e2e tests, and SLSA 3 build provenance. Dependabot tracks 40+ Go dependencies continuously. Release pipeline (release.yaml) publishes binaries and AUR packages. Recent focus on security scanning (scan.yaml) and OpenSSF scorecard integration.

git clone https://github.com/fluxcd/flux2.git
cd flux2
make build  # Compiles flux CLI using Go 1.26.0+
./bin/flux --version

For development: make install may install into $GOPATH/bin. Dependencies installed via go mod download.

Daily commands:

make build                 # Build flux CLI to ./bin/flux
./bin/flux check          # Validates cluster readiness
flux bootstrap git --url=<git-repo> --branch=main --path=clusters/my-cluster  # Bootstrap Flux on cluster

For integration testing: .github/kind/config.yaml defines KinD cluster; workflows use kind create cluster + flux bootstrap.

• cmd/flux/bootstrap.go — Entry point for Flux bootstrap operations; every contributor must understand how clusters are initialized with Flux.
• cmd/flux/create.go — Core command router for resource creation; defines the primary CLI UX pattern that all create subcommands extend.
• Makefile — Build orchestration and dependency management; essential for understanding the development workflow and release process.
• .goreleaser.yml — Release configuration that automates binary distribution across multiple architectures and platforms.
• .github/workflows/release.yaml — CI/CD pipeline for building, testing, and publishing Flux releases; critical for understanding deployment guarantees.
• go.mod — Module dependencies including fluxcd controllers (helm, kustomize, image, notification); defines the GitOps Toolkit integration boundary.
• cmd/flux/check.go — Health check and validation logic; demonstrates how Flux validates cluster readiness and component compatibility.

Add a New Flux Resource Creation Command

1. Create new command file following naming pattern cmd/flux/create_<resource>.go (cmd/flux/create_source_git.go)
2. Define command struct and flags using Cobra; mirror validation patterns from existing create commands (cmd/flux/create_helmrelease.go)
3. Implement resource marshaling to YAML and API validation using fluxcd API types (cmd/flux/create_kustomization.go)
4. Register command in the parent dispatcher (e.g., add subcommand to create.go) (cmd/flux/create.go)
5. Write unit tests following existing pattern with mock Kubernetes clients (cmd/flux/create_kustomization_test.go)

Add a New Bootstrap Provider

1. Create provider-specific bootstrap file (cmd/flux/bootstrap_<provider>.go) implementing git operations (cmd/flux/bootstrap_github.go)
2. Implement provider authentication and repository creation using go-git-providers library (cmd/flux/bootstrap_gitlab.go)
3. Add platform-specific flags and validation in command structure (cmd/flux/bootstrap_bitbucket_server.go)
4. Register provider handler in bootstrap dispatcher; ensure secret management follows existing pattern (cmd/flux/bootstrap.go)
5. Add provider to workflow test matrix for E2E validation (.github/workflows/e2e.yaml)

Add a New Secret Type

1. Create cmd/flux/create_secret_<type>.go following credential generation pattern (cmd/flux/create_secret_git.go)
2. Implement encoding logic for the specific secret format (SSH keys, certificates, tokens) (cmd/flux/create_secret_oci.go)
3. Add unit tests validating secret encoding and Kubernetes compatibility (cmd/flux/create_secret_helm_test.go)
4. Register handler in create_secret.go dispatcher and document in help text (cmd/flux/create_secret.go)

Add a New Alert Provider

1. Create cmd/flux/create_alertprovider_<name>.go with provider-specific URL and auth fields (cmd/flux/create_alertprovider.go)
2. Implement validation for provider-specific requirements (webhook URL format, token structure) (cmd/flux/alert_provider.go)
3. Add integration tests validating webhook payload structure matches provider expectations (cmd/flux/check_test.go)
4. Register provider in alert_provider.go dispatcher and update CLI help documentation (cmd/flux/alert_provider.go)

• Go + Cobra CLI framework — Compiles to single binary for cross-platform distribution; Cobra provides structured command hierarchies matching Flux's resource creation model
• Kubernetes controller-runtime + API types — Fluent integration with fluxcd controller APIs (source, helm, kustomize, image, notification); native YAML marshaling for declarative resource management
• go-git-providers library — Abstracts GitHub, GitLab, Gitea, Bitbucket APIs; enables multi-provider bootstrap without duplicating auth logic
• fluxcd/helm-controller, fluxcd/kustomize-controller APIs — Decoupled controller architecture; flux CLI is just a manifest builder/validator; controllers handle actual deployment reconciliation
• GitHub Actions + KinD clusters — Automates E2E testing on ephemeral clusters; validates bootstrap and reconciliation workflows before release

• CLI generates Kubernetes manifests rather than directly executing deployments
  • Why: Follows GitOps principle: manifests are declarative and version-controlled; enables auditing and
  • Consequence: undefined

Git committer identity required: Flux bootstrap and operations often commit to Git; requires GIT_AUTHOR_EMAIL and GIT_AUTHOR_NAME env vars. API versioning coupling: Flux CLI version must align with controller API versions in the cluster; mismatches cause reconciliation failures (check flux check). Namespace isolation: Flux resources are namespace-scoped; multi-tenant setups require per-namespace RBAC and source definitions. Kind cluster networking: KinD on Docker for Mac/Windows has DNS quirks; tests may fail if bridge networking isn't configured. Build reproducibility: Uses .goreleaser.yml with SLSA provenance; local make build produces different checksums than CI releases.

• GitOps — Flux's entire paradigm: Git as single source of truth, controllers continuously reconcile cluster state to Git state; foundational to understanding why Flux exists
• Kubernetes Custom Resource Definitions (CRDs) and Controllers — Flux extends Kubernetes API via CRDs (GitRepository, HelmRelease, Kustomization); understanding the operator pattern is essential to extending Flux
• Reconciliation Loops — Controllers continuously observe actual cluster state vs. desired state in CRDs and drive convergence; the core mechanism powering Flux's autonomous behavior
• Multi-tenancy in Kubernetes — Flux supports namespace-scoped resources and RBAC to isolate tenants; critical for enterprises deploying shared clusters with Flux
• OCI (Open Container Initiative) Artifacts — Flux sources configurations from OCI registries (not just Git); required knowledge for modern artifact distribution beyond containers
• Server-Sent Events (SSE) and Webhooks — Flux integrates with source-watcher/api v2 for push-based notifications rather than polling; reduces cluster-to-Git latency
• Supply Chain Levels for Software Artifacts (SLSA) — Flux targets SLSA level 3 for build provenance (visible in release.yaml and scorecard.yml); ensures binaries are cryptographically verifiable and tamper-evident

• fluxcd/source-controller — Core Flux controller managing GitRepository and OCIRepository CRDs; Flux CLI orchestrates this controller's reconciliation
• fluxcd/helm-controller — Handles HelmRelease CRDs for Helm integration; imported in go.mod and used by flux create helmrelease commands
• fluxcd/image-automation-controller — Provides ImagePolicy and ImageUpdateAutomation CRDs for automated image updates; essential for the flux bootstrap image-update workflow
• fluxcd/kustomize-controller — Reconciles Kustomization CRDs; core to Flux's multi-source deployment strategy via flux create kustomization
• argoproj/argo-cd — Alternative GitOps CD tool for Kubernetes; architectural competitor with different declarative model and UI-first approach

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 bootstrap commands across all providers

The repo has bootstrap implementations for multiple Git providers (GitHub, GitLab, Gitea, Bitbucket Server) in cmd/flux/bootstrap_*.go files, but the test coverage appears minimal. Add E2E-style integration tests that verify the bootstrap flow for each provider, ensuring authentication, repository setup, and initial flux installation work correctly. This directly improves reliability for users' first experience with Flux.

• [ ] Create cmd/flux/bootstrap_github_test.go with tests for GitHub token validation and repo creation
• [ ] Create cmd/flux/bootstrap_gitlab_test.go with tests for GitLab-specific authentication flows
• [ ] Create cmd/flux/bootstrap_gitea_test.go for self-hosted Gitea scenarios
• [ ] Create cmd/flux/bootstrap_bitbucket_server_test.go for Bitbucket Server-specific logic
• [ ] Reference existing cmd/flux/check_test.go and cmd/flux/cluster_info_test.go patterns for mock setup

Add GitHub Actions workflow for testing Flux CLI on multiple Go versions

The go.mod specifies go 1.26.0, but there's no dedicated workflow in .github/workflows/ that tests against multiple Go versions (1.25.x, 1.26.x) to catch compatibility regressions early. Add a matrix workflow similar to update.yaml but focused on multi-version Go testing for the CLI binary builds.

• [ ] Create .github/workflows/test-go-versions.yaml with matrix strategy for Go 1.25, 1.26
• [ ] Include 'go test ./cmd/flux/...' for all cmd packages
• [ ] Include 'go build ./cmd/flux' to verify binary compilation on each version
• [ ] Configure to run on pull requests to main and release branches
• [ ] Reference .goreleaser.yml build configurations for consistency

Add missing unit tests for build_artifact and build_kustomization commands

The files cmd/flux/build_artifact_test.go and cmd/flux/build_kustomization_test.go already exist but are likely incomplete based on the pattern of similar commands. These build commands are critical for local development workflows. Expand test coverage to include edge cases like malformed kubeconfig, missing artifacts, and kustomization validation errors.

• [ ] Review cmd/flux/build_artifact.go for all error paths and add tests for: missing file, invalid YAML, network failures
• [ ] Review cmd/flux/build_kustomization.go and add tests for: invalid kustomization.yaml, missing bases/patches, variable substitution failures
• [ ] Add integration tests that use .github/kind/config.yaml kind cluster setup
• [ ] Ensure tests validate both stdout output formatting and exit codes
• [ ] Reference cmd/flux/check_test.go patterns for mock client setup

• Add integration tests for image-reflector-controller API changes: image-reflector-controller/api v1.1.1 is imported but no dedicated CLI tests exist for image scanning; contributors could add test cases in a new cmd/flux/list/images_test.go
• Document bootstrap idempotency guarantees: CONTRIBUTING.md lacks explicit guidance on running flux bootstrap multiple times; a pull request clarifying expected behavior and edge cases would help users and reduce support load
• Add Makefile target for local security scanning: scan.yaml exists in CI but developers lack a local equivalent; adding make scan or similar would catch vulnerabilities before push and align with OSSF scorecard focus

Flux2 demonstrates a security-conscious approach with non-root container execution, SLSA 3 compliance claims, CII Best Practices badge, and proper use of HTTPS. However, the incomplete go.mod file prevents full dependency analysis. Key concerns include missing checksum verification for kubectl downloads, incomplete base image patching strategy, and lack of artifact integrity documentation. The codebase follows security best practices for a GitOps tool, but improvements in supply chain security (SBOM, provenance) and dependency verification are recommended.

• High · Incomplete Dependency List in go.mod — go.mod (line ending with 'github.com/spf13/'). The go.mod file appears to be truncated at 'github.com/spf13/' without version specification. This incomplete dependency declaration makes it impossible to verify if all transitive dependencies are properly pinned or if vulnerable versions are being used. The analysis cannot determine the complete dependency tree. Fix: Ensure the go.mod file is complete and all dependencies have explicit version pins. Run 'go mod tidy' and 'go mod verify' to validate the module file integrity.
• Medium · Outdated Alpine Base Image — Dockerfile (lines 1 and 17). The Dockerfile uses Alpine 3.23 which may have unpatched security vulnerabilities depending on the release date. While Alpine is generally secure, using the latest patch version is recommended for production images. Fix: Regularly update Alpine to the latest patch version (e.g., 3.23.X where X is the latest patch). Implement automated dependency scanning in CI/CD pipeline.
• Medium · HTTP Used for kubectl Download — Dockerfile (lines 5-6). The Dockerfile downloads kubectl using HTTPS (correct), but the curl command lacks integrity verification via checksums. If the CDN or connection is compromised, a malicious kubectl binary could be installed. Fix: Add SHA256 checksum verification after downloading kubectl. Example: 'curl -sL ... | sha256sum -c' or download the SHA file and verify independently.
• Medium · Overly Permissive COPY Instruction — Dockerfile (line 22). The COPY instruction in the flux-cli stage uses --chmod=755 which makes the flux binary world-executable. While necessary for execution, this should be the minimal required permission. Fix: Verify that 755 permissions are necessary. Consider using 750 or 700 if the binary doesn't need to be world-executable. Document the rationale for the permission choice.
• Low · Non-Root User Without Explicit UID Documentation — Dockerfile (line 24). The Dockerfile runs as user 65534:65534 (nobody user). While this is good security practice, there's no documentation explaining why this specific UID was chosen or if it's compatible with all deployment scenarios. Fix: Document the choice of UID 65534 in comments. Consider using a named user created in the Dockerfile for better clarity and maintainability.
• Low · Potential TOCTOU in CI/CD Workflows — .github/workflows/ (multiple files). The workflow files reference external actions and use curl commands without explicit version pinning in some cases. This could expose the build pipeline to supply chain attacks if dependencies are unexpectedly updated. Fix: Pin all external GitHub Actions to specific commit SHAs rather than tags. Review .github/workflows/README.md for documented best practices and implement them consistently.
• Low · No SBOM or Provenance Metadata — Repository root. While the project has SLSA 3 badge in README, there's no visible SBOM (Software Bill of Materials) or artifact provenance in the file structure. This makes it harder for users to verify dependencies and security. Fix: Generate and publish SBOM files (SPDX or CycloneDX format) with each release. Consider implementing SLSA provenance generation in CI/CD workflows.

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.