CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a community Helm chart repository hosting production-grade Kubernetes charts for: actualbudget, cloudflared, drone, kserve, mlflow, n8n, outline, and pypiserver. Charts are published to GitHub Pages via the chart-releaser action.

Chart-specific guidance (architecture, external docs, non-obvious patterns) lives in charts/<name>/CLAUDE.md. Read that file when working on a specific chart. Charts that currently have one: actualbudget (charts/actualbudget/CLAUDE.md), mlflow (charts/mlflow/CLAUDE.md), n8n (charts/n8n/CLAUDE.md), outline (charts/outline/CLAUDE.md).

Common Commands

Linting

# Lint all charts (requires chart-testing CLI)
ct lint --debug --config ./.github/configs/ct-lint.yaml --lint-conf ./.github/configs/lintconf.yaml

# Lint with Artifact Hub validator (requires `ah` CLI)
ah lint -p charts/<chart-name>

# Run KubeLinter against a single chart (requires kube-linter CLI)
kube-linter lint charts/<chart-name> --config .kube-linter.yaml

Unit Tests

# Run unit tests for a single chart — last argument is the target chart folder
helm unittest --strict --file 'unittests/**/*.yaml' charts/mlflow
helm unittest --strict --file 'unittests/**/*.yaml' charts/outline

# Run unit tests for all charts
for chart in charts/*/; do helm unittest --strict --file 'unittests/**/*.yaml' "${chart%/}"; done

Generating README

# Regenerate README.md from README.md.gotmpl for a chart (requires helm-docs)
helm-docs --chart-search-root=charts --template-files=README.md.gotmpl

Dependency Updates

# Update chart dependencies
helm dependency update charts/<chart-name>

Kind Install Testing

# Install a chart into a local kind cluster (used in CI)
ct install --config ./.github/configs/ct-lint.yaml --charts charts/<chart-name> \
  --helm-extra-set-args "--values charts/<chart-name>/values-kind.yaml" \
  --helm-extra-args "--timeout 600s"

Architecture

Chart Structure

Every chart follows this layout:

charts/<name>/
├── Chart.yaml          # Chart metadata, version, appVersion, ArtifactHub annotations
├── Chart.lock          # Locked dependency versions
├── .helmignore         # Excludes dev/test files from the packaged chart tarball
├── values.yaml         # Default values
├── values.schema.json  # JSON Schema validation for values (additionalProperties: false)
├── values-kind.yaml    # Minimal values for kind cluster CI testing
├── README.md           # Auto-generated by helm-docs from README.md.gotmpl
├── README.md.gotmpl    # Template source for README generation
├── LICENSE
├── files/              # Static files mounted into containers (e.g., scripts)
├── templates/
│   ├── _helpers.tpl    # Template helpers (name, fullname, labels, selectorLabels)
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   ├── hpa.yaml
│   ├── servicemonitor.yaml
│   ├── NOTES.txt
│   └── *_test.yaml     # Helm template test files (separate from unittests/)
└── unittests/
    └── *_test.yaml     # helm-unittest test suites (run via `helm unittest`)

Every non-deprecated chart's .helmignore must exclude files that are not needed in the packaged tarball. At minimum it must contain:

README.md.gotmpl
values-kind.yaml
CLAUDE.md
unittests/

Do not apply .helmignore changes to deprecated charts (currently: kserve).

Versioning Rules

• Any change to a chart (including docs) requires a version bump in Chart.yaml following semver.
• appVersion tracks the upstream application version.
• Breaking changes bump MAJOR version and must document manual upgrade steps in README.md.gotmpl under an "Upgrading" section.
• The artifacthub.io/changes annotation in Chart.yaml is used to auto-generate release notes — always populate it for every change. When linking to a GitHub issue or pull request, use the exact name variants below (not Issue, PR, or any other variant):

  links:
    - name: GitHub Issue
      url: https://github.com/community-charts/helm-charts/issues/<number>
    - name: GitHub PR
      url: https://github.com/community-charts/helm-charts/pull/<number>

• Bump version only once per branch/PR. After the first bump, do not bump again for subsequent commits on the same branch — all changes in the PR are released together under the single bumped version.

CI Pipeline

.github/workflows/release.yml (runs on all PRs/pushes):

1. lint-ah: Runs ah lint on all charts for ArtifactHub compliance.
2. check-helm-docs: Runs helm-docs and fails if any README.md differs from what is committed — catches PRs where README.md.gotmpl or values.yaml doc comments were updated without regenerating the README.
3. lint-test: Runs ct lint (which also calls helm unittest) and ct install on changed charts only. Requires both lint-ah and check-helm-docs to pass. Charts with a .skip-kind-test file skip the ct install step.
4. release: On merge to main, runs chart-releaser to package, GPG-sign, and publish changed charts to GitHub Pages.

.github/workflows/security-scan.yml (runs on changes to charts/**):

4. security-scan: Runs KubeLinter (all built-in checks, kserve excluded via .kube-linter.yaml) and Trivy misconfiguration/vulnerability scan (HIGH + CRITICAL severity) against chart templates. Both results are uploaded as SARIF to GitHub Security.

For conditionally-rendered fields (e.g. gated on semverCompare), suppress KubeLinter checks with a per-object annotation rather than a global .kube-linter.yaml exclusion:

metadata:
  annotations:
    ignore-check.kube-linter.io/<check-name>: "reason"

Unit Test Convention

Tests live in unittests/ as YAML files using helm-unittest syntax. Tests assert on rendered template output using set: to override values. Snapshot tests use __snapshot__/ subdirectories.

When asserting a specific value within a larger rendered string (e.g. one line in a multi-line script), use matchRegex with a targeted pattern rather than equal on the full string — keeps tests focused and resilient to unrelated boilerplate changes. matchRegex does substring matching (no anchoring needed); escape regex metacharacters in patterns (e.g. \. for literal dots in version strings).

Always validate field types against the official schema before writing tests: https://raw.githubusercontent.com/helm-unittest/helm-unittest/refs/heads/main/schema/helm-testsuite.json Suite-level capabilities can be overridden per-test using the same fields.

Values Schema

values.schema.json uses JSON Schema draft-07 with "additionalProperties": false at the root — every new value added to values.yaml must have a corresponding schema entry or chart linting will fail.

Deprecating Fields

Use @deprecated (not DEPRECATED:) in values.yaml doc comments when deprecating a field:

# -- @deprecated Use newField instead. This field will be removed in a future release.
oldField: ~

This is consistent with all existing deprecated fields in the repo and renders as plain text in the helm-docs–generated README. The values.schema.json description strings may use DEPRECATED: since they are not rendered by helm-docs.

Pre-commit Hooks

The repo uses three pre-commit hooks (.pre-commit-config.yaml). Run pre-commit install to activate locally.

helm-docs re-stage workflow: When README.md is modified by the hook, stage it and re-run:

git add charts/<chart-name>/README.md
git commit -s  # retried after hook updates

Contributing Requirements

• Each PR must only change one chart at a time.
• Commits require a Signed-off-by trailer (git commit -s).
• Never add a Co-Authored-By trailer to commits.
• YAML files must follow the rules in .github/configs/lintconf.yaml (2-space indent, no trailing spaces, LF line endings, newline at EOF).
• PR descriptions must follow the template in .github/PULL_REQUEST_TEMPLATE.md: fill in "What this PR does / why we need it", "Which issue this PR fixes" (using fixes #<number> format), "Special notes for your reviewer", and check all applicable checklist items.
• Always use fixes #<number> (not refs, closes, or plain #<number>) for every issue the PR addresses. GitHub only creates a bidirectional PR↔issue link and auto-closes issues on merge when the fixes keyword is present. Using refs or a bare #<number> produces no link in GitHub's UI.