# helm upgrade: Usage, Options & Common CI Errors

> helm upgrade changes a release to a new chart or values. The --install idempotent pattern, --atomic auto-rollback, and the no-deployed-releases error.

Source: https://latchkey.dev/learn/command-reference/helm-upgrade-command  
Updated: 2026-06-25

The CI deploy command - upgrade or install a release safely.

helm upgrade applies a new chart version or new values to an existing release, creating a new revision. With --install it is the standard idempotent CI deploy step, and with --atomic it self-heals a bad rollout.

## What it does

helm upgrade NAME CHART computes the changes from the current release to the new desired state and applies them as a new revision. --install creates the release if it does not exist (making the command idempotent across re-runs). --atomic rolls back automatically on failure; --reuse-values / --reset-values control how prior values carry forward.

## Common usage

```Terminal
helm upgrade --install web ./charts/web -n prod -f values.prod.yaml
helm upgrade --install web ./charts/web --atomic --wait --timeout 5m
helm upgrade web ./charts/web --set image.tag=${GIT_SHA} --reuse-values
helm upgrade web ./charts/web --dry-run --debug
```

## Common errors in CI

"Error: UPGRADE FAILED: \"web\" has no deployed releases" happens when a prior install failed and left the release in a failed state - upgrade has nothing healthy to upgrade from. Fix with helm upgrade --install (which handles the create path) or uninstall the failed release first. The --reuse-values vs --reset-values distinction bites CI: --reuse-values keeps old overrides (so a removed --set lingers), while a plain upgrade without either resets to chart defaults plus your new --set. Always use --atomic --wait in CI so a failed upgrade rolls back rather than leaving a half-applied release.

## Options

| Flag | Effect |
| --- | --- |
| -i, --install | Install if the release is absent |
| --atomic | Roll back to prior revision on failure |
| --wait | Block until resources are Ready |
| --reuse-values | Carry forward prior overrides |
| --reset-values | Reset to chart defaults + new --set |
| --force | Replace resources via delete/recreate |

## 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
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### helm upgrade: Usage, Options & Common CI Errors?

helm upgrade applies a new chart version or new values to an existing release, creating a new revision. With --install it is the standard idempotent CI deploy step, and with --atomic it self-heals a bad rollout.

### What it does?

helm upgrade NAME CHART computes the changes from the current release to the new desired state and applies them as a new revision. --install creates the release if it does not exist (making the command idempotent across re-runs).

### Common errors in CI?

"Error: UPGRADE FAILED: \"web\" has no deployed releases" happens when a prior install failed and left the release in a failed state - upgrade has nothing healthy to upgrade from. Fix with helm upgrade --install (which handles the create path) or uninstall the failed release first.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt