Support Helm semver encoding in OCI repositories by evankanderson · Pull Request #1834 · fluxcd/source-controller

evankanderson · 2025-06-16T21:59:47Z

(See also the related fluxcd/flux2#4674, which gave me the hint I needed.)

I'm attempting to use a Helm chart with versions like 0.20250616.4188+ref.2dec694 (which gets encoded as the tag :0.20250616.4188_ref.2dec694) with the instructions here: https://fluxcd.io/flux/cheatsheets/oci-artifacts/#helm-oci

Unfortunately, because 0.20250616.4188_ref.2dec694 is not a valid semver, I get the error message:

failed to determine the artifact tag for 'oci://ghcr.io/mindersec/minder/helm/minder': no match found for semver: >0.0.1

Based on the documentation at https://helm.sh/docs/topics/registries/#oci-feature-deprecation-and-behavior-changes-with-v380 and the discussion at opencontainers/distribution-spec#154, it seems plausible to assume that replacing _ with + (one time) when parsing semantic versions from tags is a reasonable thing to do. I'd be willing to discuss fetching the annotations for all the OCI manifests, but I suspect that's undesirable from an efficiency point of view. I'd also be willing to add a verification of the org.opencontainers.image.version annotation on the actually selected tag, but I was trying to minimize the amount of load Flux induces while supporting build metadata in semver.

TLDMain · 2026-04-29T08:38:49Z

Must-have change — could someone review it? @stealthybox @matheuscscp @stefanprodan

stefanprodan · 2026-04-29T08:58:08Z

+		// Helm translates `+` to `_` in OCI tags, because `+` is not a valid tag character.
+		versionStr := strings.Replace(t, "_", "+", 1)
+		// It would be even better to use `org.opencontainers.image.version` annotation
+		// if present, but that adds a fetch for each tag.
+		v, err := version.ParseVersion(versionStr)


OCIRepository is not specific to Helm in any way, we are going to break versions that contain _ as suffix. For this replacement to be safe, we should only do it if the layer selector is set to the Helm OCI type https://fluxcd.io/flux/components/helm/helmreleases/#ocirepository-reference-example

I'm willing to do that; another option is to do this only if ParseVersion produces an error. It looks to me like both semver.StrictNewVersion and semver.NewVersion both reject (return err for) version numbers that contain _ at all, so our risk would be that we would accept versions that we currently reject.

Interestingly, in the tests I didn't need to actually set the media type on the podinfo images for the test to pass.

TLDMain · 2026-04-30T08:28:00Z

OCIRepository is not specific to Helm in any way, we are going to break versions that contain _ as suffix. For this replacement to be safe, we should only do it if the layer selector is set to the Helm OCI type https://fluxcd.io/flux/components/helm/helmreleases/#ocirepository-reference-example

@stefanprodan Would it make sense to introduce either a controller-level flag or an OCIRepository spec flag to always replace _ with +?

For example, we could build an artifact tag based on the application image version and the CI pipeline ID — e.g., v1.0.0+pid123. This would allow us to update manifests while keeping the underlying image version unchanged.

stefanprodan · 2026-04-30T08:30:04Z

Would it make sense to introduce a controller flag that always replaces _ with +?

It doesn't make sense, since Helm v4 charts require the layer selector, not having this in your OCIRepo will result in a pull error.

TLDMain · 2026-04-30T08:32:01Z

Would it make sense to introduce a controller flag that always replaces _ with +?

It doesn't make sense, since Helm v4 charts require the layer selector, not having this in your OCIRepo will result in a pull error.

I see your point regarding Helm v4 and the required layer selector.

What I had in mind is a slightly broader use case — not limited to Helm artifacts. This would also apply to artifacts built and pushed via flux push artifact, where the OCIRepository is used more generically.

stefanprodan · 2026-04-30T08:37:27Z

I don't see any value in encoding build metadata in tags for flux push since we store the Git revision in the artifact metadata that gets propagated between Flux controllers. Instead of this encoding hack, you should rely on OCI annotations that Flux handles for you.

TLDMain · 2026-04-30T08:46:33Z

I don't see any value in encoding build metadata in tags for flux push since we store the Git revision in the artifact metadata that gets propagated between Flux controllers. Instead of this encoding hack, you should rely on OCI annotations that Flux handles for you.

My use case is a bit different — it’s more about how semver sorting behaves across environments.

For example, I have two environments:

prod → >= 1.0.0 (no prereleases)
test → >= 1.0.0-0 (includes prereleases)

This works fine when only the app version changes. But in reality, we also change configs/secrets/deployments without bumping the app version itself. Especially when manifests are stored in a separate repository from the application.

So from semver perspective I’d want something like:

v1.0.0+123
v1.0.0-1+123

so that ordering still makes sense and Flux picks the “latest” correctly, even if the app version didn’t change.

Annotations help with traceability, but they don’t affect how versions are selected/sorted — that’s the gap I’m trying to solve.

stefanprodan · 2026-04-30T09:06:59Z

Build metadata is intended to store the Git SHA, commit SHAs are not numerical and can not be sorted.

evankanderson · 2026-05-14T17:27:54Z

(Sorry, I'll get back to this shortly; I had a few other things come up.)

My use case is that https://github.com/mindersec/minder produces helm charts with versions like 0.20260514.5003+ref.39b999d (Date + GitHub build invocation, with the short SHA checksum available for ease of linking a version back to the corresponding commit). Currently, Flux can't resolve these Helm charts via SemVer due to the encoding that Helm performs when storing the tag in an OCI registry.

matheuscscp

@evankanderson Please address all the three comments (one from Stefan, two from me), rebase, squash, force-push and then we can merge 👍

matheuscscp · 2026-05-15T01:41:31Z

Please address the comments as soon as you can, I'd like to ship a patch release for this next week.

Signed-off-by: Evan Anderson <evan.k.anderson@gmail.com>

evankanderson

Okay, I figured out how to run the tests for just this (make test-ctrl GO_TEST_PREFIX=TestOCIRepository_getArtifactRef) and they seem to pass. Let me know if you need other changes, though I have family visiting this weekend and I'll be on a trip next week.

evankanderson · 2026-05-15T07:19:19Z

(I also squashed all the commits and rebased)

matheuscscp

@evankanderson You missed one thing, pls fix, amend, force-push 🙏

matheuscscp · 2026-05-15T12:23:19Z


 	var matchingVersions []*semver.Version
 	for _, t := range validTags {
+		// Helm translates `+` to `_` in OCI tags, because `+` is not permitted in OCI tags.


Reopening this as a separate comment.

Please note, I'm suggesting a few more comment lines here for a full explanation, this is quite a quirky behavior that is only for Helm, so it deserves full details in the comment.

Suggested change

// Helm translates `+` to `_` in OCI tags, because `+` is not permitted in OCI tags.

// Helm translates `+` to `_` in OCI tags, because `+` is not permitted in OCI tags.

// On the other hand, `_` is not permitted in SemVer.

// Each character not being permitted in one of the two sides establishes

// a perfect bijection between them, which makes the mapping implemented

// by Helm and honored here completely safe.

evankanderson force-pushed the oci-build-semver-sort branch from 76b4044 to 314c103 Compare June 17, 2025 00:35

stefanprodan reviewed Apr 29, 2026

View reviewed changes

evankanderson force-pushed the oci-build-semver-sort branch from 6e3eb7c to f772b6e Compare April 29, 2026 20:47

stefanprodan reviewed Apr 30, 2026

View reviewed changes

Comment thread internal/controller/ocirepository_controller_test.go

stefanprodan reviewed Apr 30, 2026

View reviewed changes

Comment thread internal/controller/ocirepository_controller.go Outdated

matheuscscp reviewed May 15, 2026

View reviewed changes

Comment thread internal/controller/ocirepository_controller.go Outdated

matheuscscp reviewed May 15, 2026

View reviewed changes

Comment thread internal/controller/ocirepository_controller.go Outdated

Comment thread internal/controller/ocirepository_controller.go Outdated

matheuscscp added bug Something isn't working backport:release/v1.8.x To be backported to release/v1.8.x labels May 15, 2026

Support Helm semver encoding in OCI repositories

abe9571

Signed-off-by: Evan Anderson <evan.k.anderson@gmail.com>

evankanderson force-pushed the oci-build-semver-sort branch from f772b6e to abe9571 Compare May 15, 2026 07:14

evankanderson commented May 15, 2026

View reviewed changes

Comment thread internal/controller/ocirepository_controller.go Outdated

Comment thread internal/controller/ocirepository_controller.go Outdated

Comment thread internal/controller/ocirepository_controller.go Outdated

Comment thread internal/controller/ocirepository_controller_test.go

matheuscscp reviewed May 15, 2026

View reviewed changes

-		// Helm translates `+` to `_` in OCI tags, because `+` is not permitted in OCI tags.
+		// Helm translates `+` to `_` in OCI tags, because `+` is not permitted in OCI tags.
+		// On the other hand, `_` is not permitted in SemVer.
+		// Each character not being permitted in one of the two sides establishes
+		// a perfect bijection between them, which makes the mapping implemented
+		// by Helm and honored here completely safe.

Conversation

evankanderson commented Jun 16, 2025

Uh oh!

TLDMain commented Apr 29, 2026

Uh oh!

stefanprodan Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

evankanderson Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

evankanderson Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

TLDMain commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanprodan commented Apr 30, 2026

Uh oh!

TLDMain commented Apr 30, 2026

Uh oh!

stefanprodan commented Apr 30, 2026

Uh oh!

TLDMain commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanprodan commented Apr 30, 2026

Uh oh!

evankanderson commented May 14, 2026

Uh oh!

Uh oh!

matheuscscp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

matheuscscp commented May 15, 2026

Uh oh!

evankanderson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

evankanderson commented May 15, 2026

Uh oh!

matheuscscp left a comment

Choose a reason for hiding this comment

Uh oh!

matheuscscp May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

TLDMain commented Apr 30, 2026 •

edited

Loading

TLDMain commented Apr 30, 2026 •

edited

Loading