fix: fix helm-docs and do various helm improvements

- Add valuesFiles option to HelmTemplate config for passing additional values files to helm template command
- Remove redundant -f values.yaml flag from helm template (chart's default values.yaml is used automatically)
- Remove --template-files flag with typo from helm-docs (default README.md.gotmpl is correct)
- Add buildx setup step to helm workflow to fix CI hang (was missing remote buildkit driver)
- Extract SetupBuildxStep() to avoid code duplication
- Add test helm chart to validate helm CI flow
- Fix the workdir of helm-docs

Signed-off-by: Utku Ozdemir <utku.ozdemir@siderolabs.com>

.dockerignore

@@ -1,6 +1,6 @@
 # THIS FILE WAS AUTOMATICALLY GENERATED, PLEASE DO NOT EDIT.
 #
-# Generated on 2025-08-14T09:17:18Z by kres 9f63e23-dirty.
+# Generated on 2026-01-30T10:07:13Z by kres d81080ef-dirty.
 
 *
 !cmd
@@ -11,3 +11,4 @@
 !README.md
 !.markdownlint.json
 !hack/govulncheck.sh
+!test/test-helm-chart

.github/workflows/helm.yaml

@@ -0,0 +1,119 @@
+# THIS FILE WAS AUTOMATICALLY GENERATED, PLEASE DO NOT EDIT.
+#
+# Generated on 2026-01-30T10:33:51Z by kres ae0b9fab-dirty.
+
+concurrency:
+  group: helm-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+"on":
+  push:
+    tags:
+      - v*
+  pull_request:
+    branches:
+      - main
+      - release-*
+    paths:
+      - test/**
+name: helm
+jobs:
+  default:
+    permissions:
+      actions: read
+      contents: write
+      id-token: write
+      issues: read
+      packages: write
+      pull-requests: read
+    runs-on:
+      group: generic
+    steps:
+      - name: gather-system-info
+        id: system-info
+        uses: kenchan0130/actions-system-info@59699597e84e80085a750998045983daa49274c4 # version: v1.4.0
+        continue-on-error: true
+      - name: print-system-info
+        run: |
+          MEMORY_GB=$((${{ steps.system-info.outputs.totalmem }}/1024/1024/1024))
+
+          OUTPUTS=(
+            "CPU Core: ${{ steps.system-info.outputs.cpu-core }}"
+            "CPU Model: ${{ steps.system-info.outputs.cpu-model }}"
+            "Hostname: ${{ steps.system-info.outputs.hostname }}"
+            "NodeName: ${NODE_NAME}"
+            "Kernel release: ${{ steps.system-info.outputs.kernel-release }}"
+            "Kernel version: ${{ steps.system-info.outputs.kernel-version }}"
+            "Name: ${{ steps.system-info.outputs.name }}"
+            "Platform: ${{ steps.system-info.outputs.platform }}"
+            "Release: ${{ steps.system-info.outputs.release }}"
+            "Total memory: ${MEMORY_GB} GB"
+          )
+
+          for OUTPUT in "${OUTPUTS[@]}";do
+            echo "${OUTPUT}"
+          done
+        continue-on-error: true
+      - name: checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # version: v6.0.1
+      - name: Unshallow
+        run: |
+          git fetch --prune --unshallow
+      - name: Set up Docker Buildx
+        id: setup-buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # version: v3.12.0
+        with:
+          driver: remote
+          endpoint: tcp://buildkit-amd64.ci.svc.cluster.local:1234
+        timeout-minutes: 10
+      - name: Install Helm
+        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # version: v4.3.1
+      - name: Install cosign
+        if: github.event_name != 'pull_request'
+        uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # version: v4.0.0
+      - name: Login to registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # version: v3.6.0
+        with:
+          password: ${{ secrets.GITHUB_TOKEN }}
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+      - name: Lint chart
+        if: github.event_name == 'pull_request'
+        run: |
+          helm lint test/test-helm-chart
+      - name: Template chart
+        if: github.event_name == 'pull_request'
+        run: |
+          helm template -f test/test-helm-chart/ci-values.yaml test-helm-chart test/test-helm-chart
+      - name: Install unit test plugin
+        if: github.event_name == 'pull_request'
+        run: |
+          make helm-plugin-install
+      - name: Unit test chart
+        if: github.event_name == 'pull_request'
+        run: |
+          make chart-unittest
+      - name: Generate schema
+        if: github.event_name == 'pull_request'
+        run: |
+          make chart-gen-schema
+      - name: Generate docs
+        if: github.event_name == 'pull_request'
+        run: |
+          make helm-docs
+      - name: Check dirty
+        if: github.event_name == 'pull_request'
+        run: |
+          make check-dirty
+      - name: helm login
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          HELM_CONFIG_HOME: /var/tmp/.config/helm
+        run: |
+          helm registry login -u ${{ github.repository_owner }} -p ${{ secrets.GITHUB_TOKEN }} ghcr.io
+      - name: Release chart
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          HELM_CONFIG_HOME: /var/tmp/.config/helm
+        run: |
+          make helm-release

.kres.yaml

@@ -91,3 +91,11 @@ spec:
       matchDatasources:
         - docker
       allowedVersions: /^24\.\d+\.\d+-alpine$/
+---
+kind: auto.Helm
+spec:
+  enabled: true
+  chartDir: test/test-helm-chart
+  template:
+    valuesFiles:
+      - test/test-helm-chart/ci-values.yaml

Dockerfile

@@ -2,10 +2,16 @@
 
 # THIS FILE WAS AUTOMATICALLY GENERATED, PLEASE DO NOT EDIT.
 #
-# Generated on 2026-01-16T08:46:36Z by kres 6f7b97a-dirty.
+# Generated on 2026-01-30T10:46:03Z by kres 7e95617c-dirty.
 
 ARG TOOLCHAIN=scratch
 
+# helm toolchain
+FROM --platform=${BUILDPLATFORM} ${TOOLCHAIN} AS helm-toolchain
+ARG HELMDOCS_VERSION
+RUN --mount=type=cache,target=/root/.cache/go-build,id=kres/root/.cache/go-build --mount=type=cache,target=/go/pkg,id=kres/go/pkg go install github.com/norwoodj/helm-docs/cmd/helm-docs@${HELMDOCS_VERSION} \
+	&& mv /go/bin/helm-docs /bin/helm-docs
+
 FROM ghcr.io/siderolabs/ca-certificates:v1.12.0 AS image-ca-certificates
 
 FROM ghcr.io/siderolabs/fhs:v1.12.0 AS image-fhs
@@ -22,6 +28,12 @@ RUN bunx markdownlint --ignore "CHANGELOG.md" --ignore "**/node_modules/**" --ig
 FROM --platform=${BUILDPLATFORM} ${TOOLCHAIN} AS toolchain
 RUN apk --update --no-cache add bash build-base curl jq protoc protobuf-dev
 
+# runs helm-docs
+FROM helm-toolchain AS helm-docs-run
+WORKDIR /src
+COPY test/test-helm-chart /src/test/test-helm-chart
+RUN --mount=type=cache,target=/root/.cache/go-build,id=kres/root/.cache/go-build --mount=type=cache,target=/root/.cache/helm-docs,id=kres/root/.cache/helm-docs,sharing=locked helm-docs --badge-style=flat
+
 # build tools
 FROM --platform=${BUILDPLATFORM} toolchain AS tools
 ENV GO111MODULE=on
@@ -44,6 +56,10 @@ ARG GOFUMPT_VERSION
 RUN go install mvdan.cc/gofumpt@${GOFUMPT_VERSION} \
 	&& mv /go/bin/gofumpt /bin/gofumpt
 
+# clean helm-docs output
+FROM scratch AS helm-docs
+COPY --from=helm-docs-run /src/test/test-helm-chart test/test-helm-chart
+
 # tools and sources
 FROM tools AS base
 WORKDIR /src

Makefile

@@ -1,6 +1,6 @@
 # THIS FILE WAS AUTOMATICALLY GENERATED, PLEASE DO NOT EDIT.
 #
-# Generated on 2026-01-28T15:12:29Z by kres edff623.
+# Generated on 2026-01-30T11:12:05Z by kres e27c601c-dirty.
 
 # common variables
 
@@ -36,6 +36,9 @@ GOTOOLCHAIN ?= local
 GOEXPERIMENT ?=
 GO_BUILDFLAGS += -tags $(GO_BUILDTAGS)
 TESTPKGS ?= ./...
+HELMREPO ?= $(REGISTRY)/$(USERNAME)/charts
+COSIGN_ARGS ?=
+HELMDOCS_VERSION ?= v1.14.2
 KRES_IMAGE ?= ghcr.io/siderolabs/kres:latest
 CONFORMANCE_IMAGE ?= ghcr.io/siderolabs/conform:latest
 
@@ -76,6 +79,7 @@ COMMON_ARGS += --build-arg=DEEPCOPY_VERSION="$(DEEPCOPY_VERSION)"
 COMMON_ARGS += --build-arg=GOLANGCILINT_VERSION="$(GOLANGCILINT_VERSION)"
 COMMON_ARGS += --build-arg=GOFUMPT_VERSION="$(GOFUMPT_VERSION)"
 COMMON_ARGS += --build-arg=TESTPKGS="$(TESTPKGS)"
+COMMON_ARGS += --build-arg=HELMDOCS_VERSION="$(HELMDOCS_VERSION)"
 TOOLCHAIN ?= docker.io/golang:1.25-alpine
 
 # help menu
@@ -144,7 +148,7 @@ else
 GO_LDFLAGS += -s
 endif
 
-all: unit-tests kres image-kres lint
+all: unit-tests kres image-kres helm lint
 
 $(ARTIFACTS):  ## Creates artifacts directory.
 	@mkdir -p $(ARTIFACTS)
@@ -177,6 +181,7 @@ check-dirty:
 
 generate:  ## Generate .proto definitions.
 	@$(MAKE) local-$@ DEST=./
+	@sed -i "s/appVersion: .*/appVersion: \"$$(cat internal/version/data/tag)\"/" test/test-helm-chart/Chart.yaml
 
 lint-golangci-lint:  ## Runs golangci-lint linter.
 	@$(MAKE) target-$@
@@ -255,6 +260,44 @@ lint-fmt: lint-golangci-lint-fmt  ## Run all linter formatters and fix up the so
 image-kres:  ## Builds image for kres.
 	@$(MAKE) registry-$@ IMAGE_NAME="kres"
 
+.PHONY: helm
+helm: $(ARTIFACTS)  ## Package helm chart
+	@helm package test/test-helm-chart -d $(ARTIFACTS)
+
+.PHONY: helm-release
+helm-release: helm  ## Release helm chart
+	@helm push $(ARTIFACTS)/test-helm-chart-*.tgz oci://$(HELMREPO) 2>&1 | tee $(ARTIFACTS)/.digest
+	@cosign sign --yes $(COSIGN_ARGS) $(HELMREPO)/test-helm-chart@$$(cat $(ARTIFACTS)/.digest | awk -F "[, ]+" '/Digest/{print $$NF}')
+
+.PHONY: chart-lint
+chart-lint:  ## Lint helm chart
+	@helm lint test/test-helm-chart
+
+.PHONY: helm-plugin-install
+helm-plugin-install:  ## Install helm plugins
+	-helm plugin install https://github.com/helm-unittest/helm-unittest.git --verify=false --version=v1.0.3
+	-helm plugin install https://github.com/losisin/helm-values-schema-json.git --verify=false --version=v2.3.1
+
+.PHONY: kuttl-plugin-install
+kuttl-plugin-install:  ## Install kubectl kuttl plugin
+	kubectl krew install kuttl
+
+.PHONY: chart-e2e
+chart-e2e:  ## Run helm chart e2e tests
+	export KUBECONFIG=$(shell pwd)/$(ARTIFACTS)/kubeconfig && cd test/e2e && kubectl kuttl test
+
+.PHONY: chart-unittest
+chart-unittest: $(ARTIFACTS)  ## Run helm chart unit tests
+	@helm unittest test/test-helm-chart --output-type junit --output-file $(ARTIFACTS)/helm-unittest-report.xml
+
+.PHONY: chart-gen-schema
+chart-gen-schema:  ## Generate helm chart schema
+	@helm schema --use-helm-docs --draft=7 --indent=2 --values=test/test-helm-chart/values.yaml --output=test/test-helm-chart/values.schema.json
+
+.PHONY: helm-docs
+helm-docs:  ## Runs helm-docs and generates chart documentation
+	@$(MAKE) local-$@ DEST=.
+
 .PHONY: rekres
 rekres:
 	@docker pull $(KRES_IMAGE)

internal/output/ghworkflow/gh_workflow.go

@@ -481,23 +481,28 @@ func DefaultJobPermissions() map[string]string {
 	}
 }
 
+// SetupBuildxStep returns the buildx setup step.
+func SetupBuildxStep() *JobStep {
+	return &JobStep{
+		Name: "Set up Docker Buildx",
+		ID:   "setup-buildx",
+		Uses: ActionRef{
+			Image:   "docker/setup-buildx-action@" + config.SetupBuildxActionRef,
+			Comment: "version: " + config.SetupBuildxActionVersion,
+		},
+		With: map[string]string{
+			"driver":   "remote",
+			"endpoint": "tcp://buildkit-amd64.ci.svc.cluster.local:1234",
+		},
+		TimeoutMinutes: 10,
+	}
+}
+
 // DefaultSteps returns default steps for the workflow.
 func DefaultSteps() []*JobStep {
 	return append(
 		CommonSteps(),
-		&JobStep{
+		SetupBuildxStep(),
-			Name: "Set up Docker Buildx",
-			ID:   "setup-buildx",
-			Uses: ActionRef{
-				Image:   "docker/setup-buildx-action@" + config.SetupBuildxActionRef,
-				Comment: "version: " + config.SetupBuildxActionVersion,
-			},
-			With: map[string]string{
-				"driver":   "remote",
-				"endpoint": "tcp://buildkit-amd64.ci.svc.cluster.local:1234",
-			},
-			TimeoutMinutes: 10,
-		},
 	)
 }
 

internal/project/auto/config.go

@@ -52,11 +52,12 @@ type Helm struct {
 
 // HelmTemplate defines helm template settings.
 type HelmTemplate struct {
-	Set        []string `yaml:"set"`
+	ValuesFiles []string `yaml:"valuesFiles"`
-	SetFile    []string `yaml:"setFile"`
+	Set         []string `yaml:"set"`
-	SetJSON    []string `yaml:"setJSON"`
+	SetFile     []string `yaml:"setFile"`
-	SetLiteral []string `yaml:"setLiteral"`
+	SetJSON     []string `yaml:"setJSON"`
-	SetString  []string `yaml:"setString"`
+	SetLiteral  []string `yaml:"setLiteral"`
+	SetString   []string `yaml:"setString"`
 }
 
 // IntegrationTests defines integration tests builder to be generated.

internal/project/auto/helm.go

@@ -43,6 +43,10 @@ func (builder *builder) DetectHelm() (bool, error) {
 
 	var flags []string
 
+	for _, valuesFile := range helm.Template.ValuesFiles {
+		flags = append(flags, "-f", valuesFile)
+	}
+
 	for _, flag := range helm.Template.Set {
 		flags = append(flags, "--set", flag)
 	}

internal/project/helm/build.go

@@ -44,7 +44,7 @@ func NewBuild(meta *meta.Options) *Build {
 func (helm *Build) CompileDockerfile(output *dockerfile.Output) error {
 	output.Stage("helm-toolchain").
 		Description("helm toolchain").
-		From("base").
+		From("--platform=${BUILDPLATFORM} ${TOOLCHAIN}").
 		Step(step.Arg("HELMDOCS_VERSION")).
 		Step(step.Script(
 			fmt.Sprintf(
@@ -58,8 +58,9 @@ func (helm *Build) CompileDockerfile(output *dockerfile.Output) error {
 	output.Stage("helm-docs-run").
 		Description("runs helm-docs").
 		From("helm-toolchain").
+		Step(step.WorkDir("/src")).
 		Step(step.Copy(helm.meta.HelmChartDir, filepath.Join("/src", helm.meta.HelmChartDir))).
-		Step(step.Run("helm-docs", "--badge-style=flat", "--template-files=README.md.gotpl").
+		Step(step.Run("helm-docs", "--badge-style=flat").
 			MountCache(filepath.Join(helm.meta.CachePath, "go-build"), helm.meta.GitHubRepository).
 			MountCache(filepath.Join(helm.meta.CachePath, "helm-docs"), helm.meta.GitHubRepository, step.CacheLocked))
 
@@ -98,6 +99,7 @@ func (helm *Build) CompileMakefile(output *makefile.Output) error {
 	output.Target("helm").
 		Description("Package helm chart").
 		Phony().
+		Depends("$(ARTIFACTS)").
 		Script(fmt.Sprintf("@helm package %s -d $(ARTIFACTS)", helm.meta.HelmChartDir))
 
 	output.Target("helm-release").
@@ -180,8 +182,7 @@ func (helm *Build) CompileGitHubWorkflow(output *ghworkflow.Output) error {
 	}
 
 	templateStep := ghworkflow.Step("Template chart").
-		SetCommand(fmt.Sprintf("helm template -f %s %s %s %s",
+		SetCommand(fmt.Sprintf("helm template %s %s %s",
-			filepath.Join(helm.meta.HelmChartDir, "values.yaml"),
 			strings.Join(helm.meta.HelmTemplateFlags, " "),
 			filepath.Base(helm.meta.HelmChartDir),
 			helm.meta.HelmChartDir,
@@ -246,6 +247,7 @@ func (helm *Build) CompileGitHubWorkflow(output *ghworkflow.Output) error {
 	jobPermissions["id-token"] = "write"
 
 	jobSteps := []*ghworkflow.JobStep{
+		ghworkflow.SetupBuildxStep(),
 		{
 			Name: "Install Helm",
 			Uses: ghworkflow.ActionRef{

test/test-helm-chart/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

test/test-helm-chart/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: test-helm-chart
+description: A minimal test Helm chart for kres
+type: application
+version: 0.1.0
+appVersion: "1.0.0"

test/test-helm-chart/README.md

@@ -0,0 +1,15 @@
+# test-helm-chart
+
+A minimal test Helm chart for kres
+
+![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat) ![AppVersion: 1.0.0](https://img.shields.io/badge/AppVersion-1.0.0-informational?style=flat)
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| apiKey | string | (required) | Required API key (must be provided) |
+| fullnameOverride | string | `""` | Fullname override |
+| nameOverride | string | `""` | Name override |
+
+this is the test chart!

test/test-helm-chart/README.md.gotmpl

@@ -0,0 +1,8 @@
+{{ template "chart.header" . }}
+{{ template "chart.description" . }}
+
+{{ template "chart.versionBadge" . }}{{ template "chart.typeBadge" . }}{{ template "chart.appVersionBadge" . }}
+
+{{ template "chart.valuesSection" . }}
+
+this is the test chart!

test/test-helm-chart/ci-values.yaml

@@ -0,0 +1,2 @@
+# Values for CI - provides required values for helm template to succeed
+apiKey: "test-api-key"

test/test-helm-chart/templates/_helpers.tpl

@@ -0,0 +1,32 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "test-helm-chart.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "test-helm-chart.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "test-helm-chart.labels" -}}
+helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+app.kubernetes.io/name: {{ include "test-helm-chart.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}

test/test-helm-chart/templates/configmap.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "test-helm-chart.fullname" . }}
+  labels:
+    {{- include "test-helm-chart.labels" . | nindent 4 }}
+data:
+  api-key: {{ required "apiKey is required" .Values.apiKey | quote }}

test/test-helm-chart/values.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "apiKey": {
+      "description": "Required API key (must be provided)",
+      "type": "string"
+    },
+    "fullnameOverride": {
+      "description": "Fullname override",
+      "type": "string"
+    },
+    "nameOverride": {
+      "description": "Name override",
+      "type": "string"
+    }
+  }
+}

test/test-helm-chart/values.yaml

@@ -0,0 +1,7 @@
+# -- Name override
+nameOverride: ""
+# -- Fullname override
+fullnameOverride: ""
+# -- Required API key (must be provided)
+# @default -- (required)
+apiKey: ""