Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 38 ยท Helm in CI/CD

Helm in CI: Lint, Test, Package and Publish

Build a CI pipeline for Helm charts with GitHub Actions: lint, unit tests, kind install tests, version checks, OCI publishing, deploys and a release-gate stand-in.

A chart repository without CI drifts: someone forgets to bump a version, a template typo reaches production, a package is overwritten. Automation fixes all three, and Helm's tooling makes a good pipeline short. This lesson builds one with GitHub Actions; the ideas transfer to GitLab CI, Jenkins or any runner.

Two pipelines, two goals

Keep two goals apart:

  1. Chart CI: validate and publish the chart (the package) on pull requests and merges.
  2. Deploy CD: install or upgrade a release of a published chart in an environment.

They can live in the same repository or separate ones. Application teams often keep the chart next to the code and publish both from one workflow; platform teams publish shared charts from a charts repository.

Pull-request validation

YAML
# .github/workflows/chart-ci.yml
name: chart-ci
on:
  pull_request:
    paths: ["charts/**"]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }

      - uses: azure/setup-helm@v4
        with: { version: v3.16.4 }

      - uses: helm/[email protected]

      - name: Unit tests
        run: |
          helm plugin install https://github.com/helm-unittest/helm-unittest --version v0.7.2
          for c in charts/*/; do helm unittest "$c"; done

      - name: Lint
        run: ct lint --target-branch ${{ github.event.repository.default_branch }} --check-version-increment

      - name: Render and validate manifests
        run: |
          for c in charts/*/; do
            helm template test "$c" | kubeconform -strict -summary -
          done

      - uses: helm/[email protected]

      - name: Install changed charts
        run: ct install --target-branch ${{ github.event.repository.default_branch }}

Pin versions of every action and tool. A pipeline that silently upgrades Helm will one day fail for reasons unrelated to your change. The order is cheap to expensive: unit tests and lint in seconds, a kind cluster in minutes.

Publishing to an OCI registry on merge

YAML
# .github/workflows/chart-release.yml
name: chart-release
on:
  push:
    branches: [main]
    paths: ["charts/**"]

permissions:
  contents: read
  packages: write
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: azure/setup-helm@v4
        with: { version: v3.16.4 }

      - name: Log in
        run: echo "${{ secrets.GITHUB_TOKEN }}" | helm registry login ghcr.io -u "${{ github.actor }}" --password-stdin

      - name: Package and push changed charts
        run: |
          for c in charts/*/; do
            name=$(basename "$c")
            version=$(grep '^version:' "$c/Chart.yaml" | awk '{print $2}')
            if helm pull "oci://ghcr.io/${{ github.repository_owner }}/charts/$name" --version "$version" >/dev/null 2>&1; then
              echo "$name $version already published, skipping"
              continue
            fi
            helm dependency build "$c"
            helm package "$c" --destination dist
            helm push "dist/$name-$version.tgz" "oci://ghcr.io/${{ github.repository_owner }}/charts"
          done

The check helm pull ... --version makes publishing idempotent: a version that exists is never pushed again, honoring the immutability rule from packaging. For classic repositories, the helm/chart-releaser-action does the same with GitHub Releases and Pages.

Deploying from CI

For a direct push-based deploy, install with safe flags:

Terminal
helm upgrade --install shop oci://ghcr.io/my-org/charts/webapp \
  --version "$CHART_VERSION" \
  --namespace prod --create-namespace \
  -f values/base.yaml -f values/prod.yaml \
  --set image.tag="$GITHUB_SHA" \
  --atomic --timeout 10m --wait \
  --history-max 10

The important flags:

Flag Why
upgrade --install One command for first install and later upgrades (idempotent)
--atomic Roll back automatically if the upgrade fails; implies --wait
--wait Block until Pods and Deployments are ready
--timeout Maximum time to wait; default 5 minutes is short for databases
--history-max Limit stored revisions so release Secrets do not pile up
--version Always pin the chart version in CD

Use environment: protection rules for production, so a human approves the job, and give the job cloud credentials through OIDC (short-lived tokens) instead of stored kubeconfigs.

A release gate stand-in

CI should refuse bad releases mechanically. The stand-in below applies the gates that matter: version bump, passing tests, immutability and a signed-off production approval.

Python Stand-in: release gates for a chart

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stamping builds

For application charts you often want to publish a chart per commit and promote it through environments. Use pre-release versions and --app-version:

Terminal
version="0.4.0-build.${GITHUB_RUN_NUMBER}"
helm package charts/webapp --version "$version" --app-version "$GITHUB_SHA"

Environments then pin the version they promote: dev follows the newest pre-release, staging an rc, prod a signed release.

Python Stand-in: compute a build version and tag

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Pitfalls

  • Overwriting versions. Make the publish step skip existing versions.
  • Secrets in logs. --debug prints values; keep it out of shared pipelines or mask output.
  • No timeout tuning. --atomic with the default 5 minutes rolls back healthy-but-slow rollouts.
  • Long-lived kubeconfigs in secrets. Prefer OIDC and per-namespace service accounts.
  • Deploying latest. Pass an immutable image tag (the commit SHA) every time.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does helm upgrade --install do?

    It makes deploy commands idempotent for both first and later runs.
  2. 2. Which flag rolls back automatically on a failed upgrade?

    --atomic waits and rolls back if the upgrade fails.
  3. 3. Why check whether a chart version exists before pushing it?

    Overwriting a version breaks consumers who pinned it.
  4. 4. What is the best way to authenticate CI to a cloud cluster?

    Short-lived federated credentials limit the damage if a job is compromised.

Summary

  • Chart CI runs unit tests, ct lint with version-increment checks, schema validation and a kind install; publish only new versions.
  • Deploy with helm upgrade --install --atomic --wait --version ... -f ... and an immutable image tag.
  • Pin tool versions, authenticate with OIDC, require approval for production.

Next: GitOps with Argo CD and Flux