Skip to content

docs: Document helm push --oci-strict-version flag #2177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
promptless-for-oss wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Document helm push --oci-strict-version flag #2177

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/topics/registries.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,20 @@ Users of the [helm-push plugin](https://github.com/chartmuseum/helm-push) (for u
may experience issues, since the plugin conflicts with the new, built-in `push`.
As of version v0.10.0, the plugin has been renamed to `cm-push`.

#### Publishing non-strict-semver versions

@promptless-for-oss promptless-for-oss Jul 13, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documented the new --oci-strict-version flag from PR #32349. The flag name, default (false), and help text ("derive the OCI tag from the parsed/sanitized semver representation of the chart version") come from f.BoolVar in pkg/cmd/push.go; the tag-derivation via semver.NewVersion(...).String() (e.g. v1.2.3 → 1.2.3) is in resolveOCITagVersion in pkg/pusher/ocipusher.go. The pull-side asymmetry the flag addresses — helm pull discards non-strict-semver tags via semver.StrictNewVersion() in pkg/registry/client.go — informed the "silently skipped" explanation.

Source: helm/helm#32349

Helm accepts lenient semantic versions in a chart's `version` field, such as `v1.2.3`. By default, `helm push` uses that raw string as the OCI tag. When Helm resolves versions from a registry, however, such as during `helm pull`, it ignores any tag that is not a strict semantic version. A chart pushed with the tag `v1.2.3` is uploaded successfully, but it is silently skipped when Helm later lists the available versions.

To avoid this mismatch, pass the `--oci-strict-version` flag to `helm push`. When it is set, Helm derives the OCI tag from the parsed, canonical semver representation of the chart version instead of the raw string. For example, a chart whose `version` is `v1.2.3` is pushed with the tag `1.2.3`:

```console
$ helm push mychart-v1.2.3.tgz oci://localhost:5000/helm-charts --oci-strict-version
Pushed: localhost:5000/helm-charts/mychart:1.2.3
Digest: sha256:ec5f08ee7be8b557cd1fc5ae1a0ac985e8538da7c93f51a51eff4b277509a723
```

The flag is opt-in and disabled by default, so existing workflows are unaffected. It applies only to OCI (`oci://`) pushes, and the push fails if the chart version cannot be parsed as a semantic version.

### Other subcommands

Support for the `oci://` protocol is also available in various other subcommands.
Expand Down
Loading