helm-kustomize-lint-action

A composite GitHub Action that lints a Helm chart end-to-end in a single step: yamllint over chart metadata, helm lint --strict per values file, helm template --debug render check, and optional kubeconform validation of the rendered manifests.

It replaces the shared lint prelude that most Helm chart repos copy-paste (azure/setup-helm + helm lint + helm template for every environment values file, optionally followed by kubeconform).

Scope:

• v1.0.x — Helm single-chart linting (chart_path + values_files).
• v1.1.0+ — adds mode: changed-charts for Helm monorepos: runs ct list-changed + ct lint on charts changed vs base_ref, then loops helm template and optional kubeconform over the changed chart set.
• v1.2.0+ — Kustomize mode (kustomize build + validation) is still reserved. The existing inputs stay backwards-compatible when it lands.

• Two modes driven by mode input:
  • helm (default): single-chart pipeline — setup-helm → optional yamllint on Chart.yaml + values*.yaml → helm lint per values file → helm template --debug per values file → optional kubeconform on rendered manifests. Zero config for a single-chart layout.
  • changed-charts: monorepo pipeline — installs chart-testing → ct list-changed against base_ref → if any charts changed, ct lint (with --check-version-increment) + helm template + optional kubeconform, all scoped to the changed chart set. skipped on every output when no charts changed.
• Multi-env charts (helm mode): pass values_files as multi-line input — each file is linted and rendered independently (mirrors the helm lint ./chart -f values-<env>.yaml pattern).
• Tunable: chart_path, helm_version (pin or latest), working_directory for mono-repos, lint_strict (default on), run_yamllint / run_template / run_kubeconform toggles, yamllint_config override, kubeconform_version + kubeconform_schema_locations (multi-line) for CRD schema URLs. changed-charts adds base_ref, charts_dir, ct_version, ct_check_version_increment.
• Templates are deliberately not yamllinted (Helm Go-template syntax is not valid YAML) — run_yamllint only touches Chart.yaml + values*.yaml.
• Writes a per-run summary table to $GITHUB_STEP_SUMMARY.
• Exposes lint_result, template_result, kubeconform_result, changed_charts_count outputs — readable even when the action fails with continue-on-error: true.

• Runner OS: ubuntu-latest is the tested target. sudo install is used to place kubeconform / ct under /usr/local/bin, which GitHub-hosted Ubuntu runners allow without extra setup.
• Caller must run actions/checkout before this action so the chart directory is on disk. For mode: changed-charts, also pass fetch-depth: 0 so ct list-changed can diff against base_ref.
• Helm is installed by the action via azure/setup-helm@v5 — no pre-install required.
• chart-testing (ct) is downloaded by the action when mode: changed-charts is set (from github.com/helm/chart-testing/releases, ct_version). Supports linux/amd64 and linux/arm64.
• kubeconform (opt-in) is downloaded from the official GitHub releases when run_kubeconform: true. Supports linux/amd64 and linux/arm64.
• Python (for yamllint) is provided by GitHub-hosted runners. If run_yamllint: true, the action installs yamllint via pip at runtime.

Drop this into .github/workflows/lint.yml of any Helm chart repo:

name: Lint

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  helm-lint:
    name: Helm Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: somaz94/helm-kustomize-lint-action@v1

With all defaults it runs: setup-helm@v5 with latest → yamllint -d relaxed Chart.yaml values.yaml → helm lint . --strict → helm template ci-render . --debug > /dev/null. kubeconform is opt-in and stays skipped unless run_kubeconform: 'true'.

- uses: actions/checkout@v6
- uses: somaz94/helm-kustomize-lint-action@v1
  with:
    chart_path: ./helm
    values_files: |
      values-aws.yaml
      values-gcp.yaml
      values-cloudflare.yaml

Each file is linted and rendered in its own helm invocation, so an error in one env doesn't mask another. The aggregate lint_result / template_result is failure if any file fails.

- uses: actions/checkout@v6
- uses: somaz94/helm-kustomize-lint-action@v1
  with:
    run_kubeconform: 'true'
    kubeconform_schema_locations: |
      default
      https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json

The action pipes helm template output into kubeconform -strict -ignore-missing-schemas -summary with one -schema-location flag per non-empty line. The default location is the bundled Kubernetes schema set; extra lines add CRD schemas (e.g., Gateway API, Prometheus Operator via the datreeio catalog).

- uses: actions/checkout@v6
- uses: somaz94/helm-kustomize-lint-action@v1
  with:
    helm_version: v3.16.4

Default is latest. Pin when you need a specific helm for consistent helm lint warning behavior across PRs.

- uses: actions/checkout@v6
- uses: somaz94/helm-kustomize-lint-action@v1
  with:
    working_directory: charts/my-app
    values_files: |
      values.yaml
      values-staging.yaml

All helm / yamllint / kubeconform commands run from working_directory. Paths in values_files are relative to working_directory.

- uses: actions/checkout@v6
- uses: somaz94/helm-kustomize-lint-action@v1
  with:
    run_template: 'false'

template_result becomes skipped. Useful when you render elsewhere (e.g., Argo CD) and only need helm lint as a guardrail.

- uses: actions/checkout@v6
- uses: somaz94/helm-kustomize-lint-action@v1
  with:
    lint_strict: 'false'

Default is true. Flip off when adopting the action against a legacy chart you can't immediately fix — warnings are still emitted, just not promoted to errors.

- uses: actions/checkout@v6
- uses: somaz94/helm-kustomize-lint-action@v1
  with:
    yamllint_config: .yamllint.yml

When empty (default), the action uses yamllint -d relaxed. When set, it uses yamllint -c <config>. The config path is relative to working_directory.

For a Helm monorepo (e.g., charts/{chart-a,chart-b,chart-c}/) where you only want to lint charts that changed in a PR:

name: Lint

on:
  pull_request:
    paths:
      - 'charts/**'

permissions:
  contents: read

jobs:
  lint-changed:
    name: Lint Changed Charts
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0        # required — ct list-changed needs full git history
      - uses: somaz94/helm-kustomize-lint-action@v1
        with:
          mode: changed-charts
          charts_dir: charts
          base_ref: ${{ github.event.repository.default_branch }}
          run_kubeconform: 'true'
          kubeconform_schema_locations: |
            default
            https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json

What this runs internally:

1. Installs chart-testing (ct_version, default v3.11.0) from its GitHub release.
2. ct list-changed --target-branch <base_ref> --chart-dirs <charts_dir> — returns changed chart paths (one per line).
3. If any charts changed: ct lint --target-branch <base_ref> --chart-dirs <charts_dir> --check-version-increment=true — ct calls helm lint internally and enforces a Chart.yaml version bump per changed chart (disable via ct_check_version_increment: 'false').
4. For each changed chart: helm template ci-render <chart-path> --debug (when run_template: true, default).
5. For each changed chart: helm template | kubeconform -strict -ignore-missing-schemas (when run_kubeconform: true).

When no charts are changed (e.g., the PR only touched docs), all three outputs become skipped and the action exits 0 — no helm/ct invocations.

In changed-charts mode, these inputs are ignored (the action emits ::notice:: for each): chart_path, values_files, run_yamllint, yamllint_config, lint_strict (ct lint has no --strict flag — it is stricter than helm lint by default: validates Chart.yaml schema + maintainers + version increment). Use mode: helm (default) if you need per-values-file linting.

- id: lint
  uses: somaz94/helm-kustomize-lint-action@v1
  continue-on-error: true
  with:
    run_kubeconform: 'true'

- name: Report lint result
  run: |
    echo "lint=${{ steps.lint.outputs.lint_result }}"
    echo "template=${{ steps.lint.outputs.template_result }}"
    echo "kubeconform=${{ steps.lint.outputs.kubeconform_result }}"
    if [[ "${{ steps.lint.outputs.lint_result }}" == "failure" ]]; then
      echo "::warning::helm lint failed — review the rendered output above"
    fi

continue-on-error: true lets the workflow inspect the outputs before deciding whether to fail the job.

This action only reads the checkout and writes to $GITHUB_STEP_SUMMARY. A minimal permissions: contents: read at the job or workflow level is sufficient.

1. Validate inputs — in helm mode: checks chart_path contains Chart.yaml, every values_files entry exists. In changed-charts mode: checks charts_dir is a directory under working_directory, ct_version matches a valid release tag, emits ::notice:: for ignored inputs (chart_path, values_files, run_yamllint, yamllint_config). Both modes: validates kubeconform_version when opt-in.
2. azure/setup-helm@v5 — installs helm at the requested version.
3. Install chart-testing (mode: changed-charts only) — downloads the pinned ct_version tarball from github.com/helm/chart-testing/releases and places ct under /usr/local/bin.
4. List changed charts (mode: changed-charts only, id: discover) — runs ct list-changed --target-branch <base_ref> --chart-dirs <charts_dir> and exports changed, count, charts as step outputs.
5. yamllint (helm mode + run_yamllint: true) — pip-installs yamllint, then lints only Chart.yaml + values*.yaml.
6. Helm lint (id: lint) — helm mode: loops over values_files. changed-charts mode: when any chart changed, runs ct lint --target-branch <base_ref> --chart-dirs <charts_dir> --check-version-increment=<ct_check_version_increment> (ct internally calls helm lint per chart); when no charts changed, writes lint_result=skipped and exits 0.
7. Helm template (id: template) — helm mode: loops over values_files with --debug. changed-charts mode: loops over the discovered chart list with --debug. skipped when run_template: false or no charts changed.
8. Kubeconform (id: kubeconform, run_kubeconform: true) — downloads the pinned kubeconform binary (multi-arch), then pipes helm template output through kubeconform -strict -ignore-missing-schemas -summary. Same mode-aware looping as template. skipped when disabled or no charts changed.
9. Summary — a markdown table is appended to $GITHUB_STEP_SUMMARY on if: always() so failed runs still surface what was attempted.

See CLAUDE.md for the full internal flow and the composite-output wiring rationale.

MIT. See LICENSE.