helm upgrade: Usage, Options & Common CI Errors
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
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 --debugCommon 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 |