helm upgrade: Command Reference for CI/CD

By Kaveh Alemi·Latchkey

The idempotent Helm deploy: upgrade, or install if absent.

helm upgrade --install is the standard CI deploy command: it upgrades an existing release or installs it on first run, in one idempotent step. This reference covers the gating flags and a deploy example built around an immutable tag.

Common flags and usage

upgrade --install <release> <chart>: idempotent upgrade-or-install
-f values.yaml / --set k=v: override values
--wait: block until resources are Ready
--atomic: roll back to the prior release on failure
--timeout 5m: bound the wait
--reuse-values / --reset-values: control value carry-over

Example

shell

helm upgrade --install web ./charts/web \
  --namespace prod \
  --set image.tag=${IMAGE_TAG} \
  --wait --atomic --timeout 5m

In CI

upgrade --install removes the "does this release exist yet?" branch from your pipeline. --atomic rolls the release back to the last good revision if the upgrade fails, and --wait gates on readiness. Set image.tag to an immutable value (commit SHA) so each deploy is a real change. Latchkey managed runners give each deploy job a clean, ephemeral environment for this step.

Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

Terminal

# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes

Key takeaways

upgrade --install is the idempotent deploy: one command for both cases.
--atomic + --wait + --timeout make the deploy self-gating and self-healing.
Pin image.tag to an immutable SHA so upgrades are real changes.

Frequently asked questions

helm upgrade: Command Reference for CI/CD?

In CI?