# helm package: Usage, Options & Common CI Errors

> helm package builds a chart into a versioned .tgz archive. Setting the version in CI, dependency bundling, and the lock-mismatch and version errors.

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

Bundle a chart into a versioned archive for publishing.

helm package compresses a chart directory into a chart-version.tgz archive - the artifact you push to a chart repository or OCI registry. It is the build step in a chart-release pipeline.

## What it does

helm package CHART produces NAME-VERSION.tgz using the version from Chart.yaml. --version and --app-version override those at package time (useful for CI-stamped versions); --dependency-update refreshes the charts/ directory first; --sign with a key produces a provenance file. The archive is what helm repo index and helm push consume.

## Common usage

```Terminal
helm package ./charts/web
helm package ./charts/web --version 1.4.${BUILD_NUMBER}
helm package ./charts/web --dependency-update
helm package ./charts/web --destination ./dist
```

## Common errors in CI

"Error: found in Chart.yaml, but missing in charts/ directory" means dependencies are declared but not vendored. Run helm dependency update (or package with --dependency-update) first. "Error: chart Chart.yaml version is required" / an invalid version means the version field is missing or not SemVer-2 compliant; helm requires strict SemVer, so a tag like v1.0 or 1.0 (without patch) can be rejected. Stamp a full x.y.z. If Chart.lock is out of date relative to Chart.yaml dependencies, packaging warns/fails; regenerate the lock with helm dependency update.

## 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 package: Usage, Options & Common CI Errors?

helm package compresses a chart directory into a chart-version.tgz archive - the artifact you push to a chart repository or OCI registry. It is the build step in a chart-release pipeline.

### What it does?

helm package CHART produces NAME-VERSION.tgz using the version from Chart.yaml. --version and --app-version override those at package time (useful for CI-stamped versions); --dependency-update refreshes the charts/ directory first; --sign with a key produces a provenance file. The archive is what helm repo index and helm push consume.

### Common errors in CI?

"Error: found in Chart.yaml, but missing in charts/ directory" means dependencies are declared but not vendored. Run helm dependency update (or package with --dependency-update) first. "Error: chart Chart.yaml version is required" / an invalid version means the version field is missing or not SemVer-2 compliant; helm requires strict

---

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