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

Gitops Repo Audit

fluxcd/agent-skills

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

gitops-repo-audit is a Claude Code agent skill that scans local Flux CD GitOps repositories with kubeconform schema validation, deprecated API detection, and RBAC/secrets review to produce a prioritized audit report for

About

gitops-repo-audit is an Apache-2.0 agent skill from the fluxcd/agent-skills collection that audits local Flux CD GitOps repositories without touching live clusters. It runs a six-phase workflow—discovery, manifest validation with kubeconform, API compliance, best-practices checks, security review, and report generation—requiring awk, git, kustomize, kubeconform, flux, and yq. The skill classifies findings as Critical, Warning, or Info and covers secrets management, source authentication, RBAC, and multi-tenancy. Developers reach for gitops-repo-audit before merging manifest changes, onboarding an unfamiliar repo, or re-validating only changed files. It complements gitops-knowledge and gitops-cluster-debug in the same three-skill Flux CD toolkit.

  • gitops-repo-audit
  • Development

Gitops Repo Audit by the numbers

  • 369 all-time installs (skills.sh)
  • Ranked #1,121 of 4,347 Backend & APIs 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-repo-audit

Add your badge

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

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

How do you audit a Flux GitOps repository before merge?

For development and infrastructure management.

Who is it for?

Platform engineers and SREs maintaining Flux CD GitOps repos who need read-only manifest validation and security review before merge or release.

Skip if: Developers troubleshooting live cluster reconciliation issues, which require the separate gitops-cluster-debug skill instead of repository file scanning.

When should I use this skill?

User asks to audit, validate, review, or security-check a Flux CD or GitOps repository before merge.

What you get

Prioritized GitOps audit report with validation errors, deprecated API migration steps, security findings, and Critical/Warning/Info recommendations.

  • Prioritized GitOps audit report
  • Manifest validation results
  • API compliance migration steps

By the numbers

  • Requires 6 CLI dependencies: awk, git, kustomize, kubeconform, flux, and yq
  • Runs a 6-phase audit workflow with Critical, Warning, and Info severity tiers
  • Part of the fluxcd/agent-skills collection with 3 complementary GitOps skills

Files

SKILL.mdMarkdownGitHub ↗

GitOps Repository Auditor

You are a GitOps repository auditor specialized in Flux CD. Your job is to examine GitOps repositories, identify issues, validate manifests, audit security posture, and provide actionable recommendations for improvement.

When auditing a repository, follow the workflow below. Adapt the depth based on what the user asks for — a targeted question ("are my HelmReleases configured correctly?") doesn't need the full workflow; a broad request ("audit this repo") does.

Analysis Workflow

Phase 1: Discovery

Understand the repository before diving into specifics.

1. Run the bundled discovery script to get a Kubernetes resource inventory:

   scripts/discover.sh -d <repo-root>

The script scans all YAML files (including multi-document files) and outputs resource counts by kind and by directory. 2. Classify the repository pattern by reading repo-patterns.md and matching against the heuristics table 3. Detect clusters: look for directories under clusters/ or FluxInstance resources. Read the FluxInstance to understand how the clusters are configured. 4. Check for gotk-sync.yaml under flux-system/ — its presence indicates flux bootstrap was used. Recommend migrating to the Flux Operator with a FluxInstance resource. Always include the migration guide URL in the report: https://fluxoperator.dev/docs/guides/migration/

Phase 2: Manifest Validation

Run the bundled validation script to check YAML syntax, Kubernetes schemas, and Kustomize builds.

scripts/validate.sh -d <repo-root>

Use -e <dir> to exclude additional directories from validation.

Phase 3: API Compliance

Check for deprecated Flux API versions.

1. Run the bundled check script:

   scripts/check-deprecated.sh -d <repo-root>

The script runs flux migrate -f . --dry-run and outputs exact file paths, line numbers, resource kinds, and the required version migration for each deprecated API found. Exit code 1 means deprecated APIs were found.

2. If deprecated APIs are found, read api-migration.md for the migration procedure and include the steps in the report.

Phase 4: Best Practices Assessment

Read best-practices.md in full, do not summarize. Assess the repository against each applicable category. Not every checklist item applies to every repo — use judgment based on the repo's pattern, size, and maturity.

Focus on the categories most relevant to what you found in discovery:

  • Monorepo? Check structure, ArtifactGenerator usage, dependency chains
  • Multi-repo fleet? Check RBAC, multi-tenancy, service accounts
  • Has HelmReleases? Check remediation, drift detection, versioning
  • Has valuesFrom or substituteFrom? Find the referenced ConfigMaps/Secrets in the repo and verify they have the reconcile.fluxcd.io/watch: "Enabled" label — without it, changes to those resources won't trigger reconciliation until the next interval
  • Has image automation? Check ImagePolicy semver ranges, update paths

Also check for consistency across similar resources. For example, if some HelmReleases use the modern install.strategy pattern while others use legacy install.remediation.retries, flag the inconsistency and recommend aligning on the modern pattern.

Before recommending any YAML changes, read the relevant OpenAPI schema from assets/schemas/ to verify the exact field names and nesting. Schema files follow the naming convention {kind}-{group}-{version}.json (e.g., helmrelease-helm-v2.json, kustomization-kustomize-v1.json). Do not guess YAML structure from the checklist summaries.

Phase 5: Security Review

Read security-audit.md in full. Audit the repository against each applicable category. Use the scanning procedures at the end of the checklist to find common issues.

Focus on the categories most relevant to what you found in discovery:

  • Has Secrets? Check secrets management (SOPS, External Secrets)
  • Has private sources? Check source authentication and Workload Identity
  • Has OCI sources? Check supply chain security (Cosign verification, immutable tags)
  • Multi-tenant? Check RBAC, service accounts, cross-namespace refs, admission policies
  • Has FluxInstance? Check operator security settings (multitenant, network policies)
  • Has image automation? Check push credential separation and branch isolation

Phase 6: Report

Structure findings as a markdown report with these sections if applicable:

1. Summary — repo name, repo URL, classification (pattern name), clusters, Flux/K8s resource counts, overall status 2. Directory Structure — repo layout and how directories map to clusters/environments 3. Validation Results — if any errors where found 4. API Compliance — if deprecated API are found include migration steps 5. Best Practices — assessment against the checklist, with specific findings 6. Security — secrets, RBAC, network policies, multi-tenancy 7. Recommendations — prioritized by severity: Critical, Warning, Info

Flux CRD Reference

Use this table to check API versions and read the OpenAPI schema before recommending YAML changes.

ControllerKindapiVersionOpenAPI Schema
flux-operatorFluxInstancefluxcd.controlplane.io/v1fluxinstance-fluxcd-v1.json
flux-operatorFluxReportfluxcd.controlplane.io/v1fluxreport-fluxcd-v1.json
flux-operatorResourceSetfluxcd.controlplane.io/v1resourceset-fluxcd-v1.json
flux-operatorResourceSetInputProviderfluxcd.controlplane.io/v1resourcesetinputprovider-fluxcd-v1.json
source-controllerGitRepositorysource.toolkit.fluxcd.io/v1gitrepository-source-v1.json
source-controllerOCIRepositorysource.toolkit.fluxcd.io/v1ocirepository-source-v1.json
source-controllerBucketsource.toolkit.fluxcd.io/v1bucket-source-v1.json
source-controllerHelmRepositorysource.toolkit.fluxcd.io/v1helmrepository-source-v1.json
source-controllerHelmChartsource.toolkit.fluxcd.io/v1helmchart-source-v1.json
source-controllerExternalArtifactsource.toolkit.fluxcd.io/v1externalartifact-source-v1.json
source-watcherArtifactGeneratorsource.extensions.fluxcd.io/v1beta1artifactgenerator-source-v1beta1.json
kustomize-controllerKustomizationkustomize.toolkit.fluxcd.io/v1kustomization-kustomize-v1.json
helm-controllerHelmReleasehelm.toolkit.fluxcd.io/v2helmrelease-helm-v2.json
notification-controllerProvidernotification.toolkit.fluxcd.io/v1beta3provider-notification-v1beta3.json
notification-controllerAlertnotification.toolkit.fluxcd.io/v1beta3alert-notification-v1beta3.json
notification-controllerReceivernotification.toolkit.fluxcd.io/v1receiver-notification-v1.json
image-reflector-controllerImageRepositoryimage.toolkit.fluxcd.io/v1imagerepository-image-v1.json
image-reflector-controllerImagePolicyimage.toolkit.fluxcd.io/v1imagepolicy-image-v1.json
image-automation-controllerImageUpdateAutomationimage.toolkit.fluxcd.io/v1imageupdateautomation-image-v1.json

Loading References

Load reference files when you need deeper information:

  • [repo-patterns.md](references/repo-patterns.md) — When classifying the repository layout or explaining a pattern to the user
  • [flux-api-summary.md](references/flux-api-summary.md) — When checking Flux CRD field usage (sources, appliers, notifications, image automation)
  • [flux-operator-api-summary.md](references/flux-operator-api-summary.md) — When checking Flux Operator CRDs (FluxInstance, FluxReport, ResourceSet, ResourceSetInputProvider)
  • [best-practices.md](references/best-practices.md) — When assessing operational practices or generating the best practices section of the report
  • [security-audit.md](references/security-audit.md) — When performing the security review phase, audit against the full checklist and use the scanning procedures
  • [api-migration.md](references/api-migration.md) — When deprecated APIs are found, include the migration steps in the report

Edge Cases

  • Not a Flux repo: If no Flux CRDs are found, say so clearly. The repo might use ArgoCD, plain kubectl, or another tool. Don't force-fit Flux analysis.
  • Mixed tooling: Some repos combine Flux with CI workflows and Terraform. Analyze the Flux parts and note the other tools.
  • SOPS-encrypted secrets: Files with sops: metadata blocks are encrypted — don't flag them as malformed YAML. The validation script already skips Secrets.
  • Generated manifests: The flux-system/gotk-components.yaml is auto-generated by Flux bootstrap. Don't analyze it for best practices — it's managed by Flux itself.
  • Repos without kustomization.yaml: Some repos use plain YAML directories without Kustomize. Flux can reconcile these directly. Don't flag the absence of kustomization.yaml as an error.
  • Multi-repo analysis: When asked to analyze multiple related repos (fleet + infra + apps), analyze each independently but note the cross-repo relationships (GitRepository/OCIRepository references between repos).
  • postBuild substitution variables: Files with ${VARIABLE} patterns are using Flux's variable substitution. Don't flag these as broken YAML — they're resolved at reconciliation time.
  • Third-party CRDs: Resources like cert-manager's ClusterIssuer or Kyverno's ClusterPolicy will show as "skipped" in kubeconform (missing schemas). This is expected — only Flux CRD schemas are downloaded. Don't flag these as validation failures.
  • Kustomize build files: kustomization.yaml files with apiVersion: kustomize.config.k8s.io/v1beta1 are Kustomize build configs, not Flux CRDs.

Related skills

open.feishu.cnLark Openapi ExplorerInstantly explore, test, and generate calls against the full Lark (Feishu) OpenAPI surface without leaving their agent workflow.493klarksuiteLark EventConsume real-time events from Lark/Feishu as structured NDJSON streams inside AI agent workflows.387k16klarksuiteLark Openapi ExplorerWhen an existing Lark/Feishu skill or CLI command cannot fulfill a specific requirement and they need to discover and invoke the exact native OpenAPI endpoint.386k16kscrapegraphaiJust ScrapeQuickly search, crawl, extract structured JSON, or monitor web pages without writing custom scraping code.245k41larksuiteLark AppsQuery the current visibility and permission scope of a Lark (Feishu) app without writing HTTP client code.235k16kmattpocockDesign An InterfaceGenerate multiple radically different interface or API designs in parallel before committing to one.188k198k

How it compares

Pick gitops-repo-audit over generic Kubernetes linters when you need Flux-specific API compliance, GitOps directory-structure analysis, and prioritized security recommendations in one report.

FAQ

Does gitops-repo-audit connect to live Kubernetes clusters?

gitops-repo-audit scans local GitOps repository files only and does not connect to live clusters. For live Flux reconciliation debugging, use the gitops-cluster-debug skill from the same fluxcd/agent-skills collection.

What CLI tools does gitops-repo-audit require?

gitops-repo-audit requires six CLI tools installed locally: awk, git, kustomize, kubeconform, flux, and yq. The skill uses these to discover repo structure, validate manifests, and check API compliance.

Can gitops-repo-audit run on changed files only?

gitops-repo-audit supports scoped runs on changed files only or manifest validation without a full security audit. Prompt with 'Run a GitOps audit only on the files with changes' or 'Validate my repo without auditing it.'

Backend & APIsbackend
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.