rules_helm

Chart-as-a-module: build, lint, and publish Helm charts in Bazel (the Helm analog of rules_oci).

bazel_dep(name = "rules_helm", version = "0.2.0")

View source & releases on GitHub ↗

Chart-as-a-module: build, lint, and publish Helm charts in Bazel — the Helm analog of how this org already does container images (rules_oci) and protos.

Helm itself is fetched hermetically (a pinned per-platform binary from get.helm.sh), so bazel build-ing a chart needs nothing installed on the host.

helm_template

Render a chart someone else published into manifests you can read, review, diff and gate:

load("@rules_helm//helm:defs.bzl", "helm_template")

helm_template(
    name = "argocd_manifests",
    chart = "@argo_cd_chart//file",   # http_file, pinned by sha256
    release_name = "argocd",
    namespace = "argocd",
    values = ["values.yaml"],
)

helm install renders and applies in one motion, so what actually reached the cluster is knowable only afterwards, by asking the cluster. Rendering to a file makes it reviewable before anything moves, byte-stable across rebuilds, and diffable against a live cluster.

The action has no network, so chart must be a self-contained .tgz — a chart with unvendored subcharts fails here rather than silently fetching them. Pin it with http_file + sha256 so the render is a pure function of committed inputs.

Rules

Use

MODULE.bazel:

bazel_dep(name = "rules_helm", version = "0.1.0")

BUILD.bazel next to a chart:

load("@rules_helm//helm:defs.bzl", "helm_chart", "helm_lint", "helm_push")

_SRCS = ["values.yaml"] + glob(["templates/**", ".helmignore"])

helm_chart(
    name = "chart",
    chart_yaml = "Chart.yaml",
    srcs = _SRCS,
    version = "1.2.3",        # optional; defaults to Chart.yaml
    app_version = "1.2.3",    # optional; defaults to Chart.yaml
)

helm_lint(name = "lint", chart_yaml = "Chart.yaml", srcs = _SRCS)

helm_push(name = "push", chart = ":chart", repository = "ghcr.io/fastverk/charts")

bazel build //path/to:chart        # -> bazel-bin/path/to/chart.tgz
bazel build //path/to:lint         # fails if the chart doesn't lint
helm registry login ghcr.io ...    # auth once (CI uses GITHUB_TOKEN)
bazel run   //path/to:push         # publishes the .tgz

srcs must list every file helm should package — the action runs in a sandbox containing only the declared inputs. helm_chart is for leaf charts; a chart with subchart dependencies must have its charts/ vendored (helm dependency build) and the vendored archives passed in srcs.

Bumping helm

Two edits in helm/repositories.bzl: HELM_VERSION and the four HELM_SHA256 lines. Refresh a checksum with:

curl -fsSL https://get.helm.sh/helm-v<ver>-<platform>.tar.gz.sha256sum

This v0.1.0 downloads only the host platform’s binary (chart packaging always runs host-native). A future revision can graduate this to a full multi-platform Bazel toolchain for exec-platform selection (RBE).

Publishing this module

Tag a release and run the registry tool (same flow as the other fastverk rules_* modules):

git tag v0.1.0 && git push origin v0.1.0
# in repos/bazel-registry:
bazel run //tools/rels -- release --repo fastverk/rules_helm --version 0.1.0

Usage#

load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("@rules_helm//helm:defs.bzl", "helm_chart", "helm_lint", "helm_push", "helm_template")

# All chart files the action needs (the sandbox sees only declared inputs).
_SRCS = [
    "chart/values.yaml",
    "chart/templates/deployment.yaml",
]

helm_chart(
    name = "smoke",
    chart_yaml = "chart/Chart.yaml",
    srcs = _SRCS,
    version = "0.1.0",
    app_version = "0.0.0",
)

helm_lint(
    name = "lint",
    chart_yaml = "chart/Chart.yaml",
    srcs = _SRCS,
)

helm_push(
    name = "push",
    chart = ":smoke",
    repository = "ghcr.io/fastverk/charts",
)

# ── helm_template ────────────────────────────────────────────────────────────
# Round-trips the chart this package already builds: helm_chart packages it, then
# helm_template renders it back to manifests. Self-contained, so the test proves
# the rule works without depending on any third-party chart staying published.
helm_template(
    name = "smoke_rendered",
    chart = ":smoke",
    namespace = "smoke-ns",
    release_name = "smoke-release",
    values = ["chart/values.yaml"],
)

# The whole point of rendering to a file is that the output is reviewable and
# STABLE. If a helm upgrade or a rule change perturbs it, that must surface as a
# failing test rather than as a silent difference in what reaches a cluster.
diff_test(
    name = "smoke_rendered_stable",
    file1 = "expected_smoke_rendered.yaml",
    file2 = ":smoke_rendered",
)

Conformance#

Dependencies#

Depends on

Used by (1 in the registry)

Versions#

2 published versions, newest first. Each resolves to an immutable, integrity-checked archive.

Changelog#

← All modules