flux manager: OCI HelmRelease with HelmRepository in a separate file rebases its branch on every run

[aschyolkin]

What is the problem?

When a Flux HelmRelease gets its chart from an OCI HelmRepository that is defined in a separate file, Renovate re-creates and force-pushes the existing update branch on every run.

The new commit has a byte-identical diff to the previous one — only the parent and the SHA change. Because every push starts a new merge request pipeline, this produces an endless stream of pipelines and CI comments. In our repository this rebuilds 23 branches every 15 minutes; the oldest affected MR has accumulated roughly 500 pipelines and 1000 CI comments.

The debug log shows the branch is not conflicted and reuse was intended, yet the branch is rebuilt anyway:

branch.isConflicted(): false
Branch does not need rebasing
Using reuseExistingBranch: true
manager.getUpdatedPackageFiles() reuseExistingBranch=true
Rebasing branch after deps list has changed
manager.getUpdatedPackageFiles() reuseExistingBranch=false

Minimal reproduction

https://github.com/aschyolkin/renovate-flux-oci-repro

1. Run Renovate against it — a PR is opened updating reloader.
2. Push any unrelated commit to the default branch.
3. Run Renovate again — the branch is force-pushed with a new SHA and an identical diff.

Analysis

1. extractAllPackageFiles calls collectHelmRepos(manifests) over all files, so it finds the neighbouring helmrepository.yaml. For type: oci, resolveHelmRepository sets datasource=docker and packageName=ghcr.io/stakater/charts/reloader — flux/extract.ts#L122-L170.

2. checkBranchDepsMatchBaseDeps re-extracts the branch content through the single-file extractPackageFile, where collectHelmRepos([manifest]) only sees helmrelease.yaml. matchingRepositories is empty, so the dependency falls through to skipReason: 'unknown-registry' with no packageName — auto-replace.ts#L173-L186.

3. getDepsSignature compares depName + packageName, so the two extraction paths can never agree, and get-updated.ts unconditionally falls back to reuseExistingBranch: false, rebuilding the branch from the base branch — get-updated.ts#L253-L257.

A plain HTTP HelmRepository is unaffected: packageName is left unset in both extraction paths and registryUrls is not part of the signature, so the signatures match. That is why only OCI repositories loop.

Note that rebaseWhen: "never" does not help — it only affects shouldReuseExistingBranch higher up the stack, while the reset in get-updated.ts is unconditional.

Expected behavior

A branch whose package file has not changed should be reused rather than rebuilt. The branch-reuse check should either extract with cross-file context, the way extractAllPackageFiles does, or compare a dependency identity that is stable across both extraction paths.

Workarounds

Both make the single-file extraction produce the same packageName:

• registryAliases keyed by sourceRef.name. Note that the example in the flux manager readme uses "matchDatasources": ["helm"], which does not apply here: after full extraction the dependency is already datasource=docker, so the filter has to be omitted.

  {
    "packageRules": [
      {
        "matchManagers": ["flux"],
        "registryAliases": { "reloader": "oci://ghcr.io/stakater/charts" }
      }
    ]
  }

• Merging the HelmRepository and the HelmRelease into a single multi-document YAML file.

Version

Reproduced on 44.40.0. The same implementation is present in current main.

Possibly related but with different root causes: #20906, #10358, #19835.

[sambai-dev]

Your analysis checks out against the source at 44.40.0. I re-read the three files you cited and they behave exactly as you describe, and all three are byte-identical on current main (44.44.0 was tagged today), so no released version fixes this yet.

Confirmed from source:

• extract.ts: the multi-file pass calls collectHelmRepos(manifests) over everything scanned, while the branch-side re-extract goes through the single-file extractPackageFile, which calls collectHelmRepos([manifest]) and so cannot see your separate helmrepository.yaml. For type: oci, resolveHelmRepository rewrites the dep to the docker datasource with packageName ghcr.io/stakater/charts/reloader; with no matching repo and no alias it falls through to skipReason: 'unknown-registry'.
• auto-replace.ts: checkBranchDepsMatchBaseDeps compares getDepsSignature(baseDeps) against the branch re-extract, and that signature is built from depName and packageName only (registryUrls is not part of it). The base side carries the OCI packageName, the branch side has none, so the two strings can never match and the existing branch is always judged stale.
• get-updated.ts: once that comparison fails, the worker recurses with reuseExistingBranch forced back to false and rebuilds the branch from the base tip. Your reading of rebaseWhen is correct: it is only consulted inside shouldReuseExistingBranch (and there only on the conflicted/behind paths), while this reset ignores it entirely.

That places the failure between two extraction paths inside the flux manager, which config cannot reconcile properly. With a minimal repro plus the pipeline-volume numbers, this looks worth promoting to an issue. Of the threads you linked, #20906 is the closest relative, but its cause (post-upgrade tasks) is distinct, so it does not cover this behavior.

Until a fix lands, your two workarounds are the practical options. One addition on registryAliases: the example in the flux manager readme pairs it with matchDatasources: ["helm"], which suits the HTTP case. Both alias application paths emit the OCI dep with the docker datasource, so the datasource filter has to go, exactly as your snippet does, otherwise the rule will not attach to the dependency.

I have not executed your repro repo myself; the above comes from reading the linked files at the 44.40.0 tag and diffing them against main.

[aschyolkin]

Thanks for the detailed source review — that matches what we see, and I can add a data point on newer releases.

Our bot is not pinned to a chart version, so it has been picking up releases on its own while this thread was open. It has moved 44.40.0 → 44.45.3 → 44.45.4, and the version actually changed between two consecutive runs this morning (04:30 and 04:45 UTC). That gave us an unplanned test across several releases.

The behavior is unchanged on 44.45.4. The most recent run produced exactly 23 occurrences of Rebasing branch after deps list has changed for our repository — the same count as on 44.40.0, and the same set of branches. All of them are Flux HelmRelease resources backed by an OCI HelmRepository kept in a separate file. No base-helm-* or base-github-tags-* branch is affected, which lines up with registryUrls not being part of the signature.

So the loop reproduces on 44.40.0, 44.45.3 and 44.45.4, consistent with the files being byte-identical on main.

Two more notes that may be useful when this becomes an issue:

• The signature is computed per package file across the whole dep list, so a single unresolvable OCI chart also drags in the image dependencies that the flux manager picks up from the same HelmRelease via findDependencies. In our case 20 package files produce 23 looping branches for that reason — the image branches are collateral, not independently broken.
• The registryAliases workaround needs care at scale. It only applies on the "repository not found" path, so for a HelmRelease whose sourceRef namespace does not match the HelmRepository namespace, both extraction paths currently agree on unknown-registry and there is no loop. Adding a blanket alias for those makes the branch-side extract resolve while the full extract still does not, producing the mismatch in the opposite direction. We found 7 such pairs out of 49 in our repo and had to exclude them until their namespaces are aligned.

Happy to run anything specific against the reproduction repo if it would help.

[sambai-dev]

Hi! Just catching up on this thread.

@aschyolkin, your release sweep turned my source read into something much harder to argue with, thanks for doing it.

One thing your notes clarify for me: if findDependencies is what drags the image deps into the same file signature, then one unresolvable OCI chart quietly breaks unrelated image branches too, which would fit your 23 looping branches across 20 package files. I have not re-verified that hop myself, so treat that as your reading and mine agreeing rather than an independent check.

The namespace finding feels like the strongest argument for fixing this in the manager rather than documenting a registryAliases recipe. Would you mind capturing those 7 excluded pairs somewhere visible in #45441, so a routing gate change cannot silently regress them? They look like exactly the edge a widened gate would break.

[aschyolkin]

Happy to write those up — one small thing first: #45441 is a fix(github-actions) PR about component-prefixed tags, so that number looks like a typo. I could not find an issue tracking this yet, so I am recording the seven pairs here; feel free to point me at the right number once one exists and I will repeat it there.

On findDependencies: agreed that it should be treated as two readings agreeing rather than an independent check. What I can offer beyond the code path is the shape of the data — in our repository the 23 looping branches come from 20 package files, and the extra three are image branches belonging to files that also carry an unresolvable OCI chart. No image branch loops in a file whose chart resolves. That is consistent with a per-file signature, but I have not isolated it in a unit test.

The seven excluded pairs

All seven are Flux HelmRelease + OCI HelmRepository in separate files, exactly like the looping ones. The difference is that the namespace comparison in resolveResourceManifest fails:

rep.metadata.namespace === (sourceRef.namespace ?? helmRelease.metadata.namespace)

Because that comparison already fails during the full extraction, these pairs get unknown-registry on both extraction paths. The signatures therefore match and they do not loop today. They are only dangerous the moment something makes the branch-side path resolve while the full path still does not.

They fall into two shapes:

Shape A — sourceRef.namespace points somewhere else (2 pairs)

# HelmRelease
metadata:
  namespace: flux-system
spec:
  chart:
    spec:
      sourceRef:
        kind: HelmRepository
        name: some-chart
        namespace: team-ns      # <- overrides the comparison
---
# HelmRepository, separate file
metadata:
  name: some-chart
  namespace: flux-system        # <- matches the HelmRelease, but not sourceRef.namespace

Shape B — the HelmRepository has no namespace at all (5 pairs)

# HelmRelease
metadata:
  namespace: team-ns
spec:
  chart:
    spec:
      sourceRef:
        kind: HelmRepository
        name: some-chart        # no namespace -> falls back to team-ns
---
# HelmRepository, separate file
metadata:
  name: some-chart              # no namespace -> undefined

Why this shape exists at all

These manifests are not broken at runtime. The Flux Kustomization that applies them sets spec.targetNamespace, which moves every resource in the tree into the same namespace, so the HelmRelease and the HelmRepository do end up together and Flux reconciles them fine. The namespaces written in git are simply not the namespaces the objects live in.

That is the part I would flag for any routing change: the namespace in the manifest is not authoritative when a parent Kustomization sets targetNamespace, and the manager has no visibility into that parent. A gate that gets widened — for example by relaxing the namespace match, or by applying aliases before the repository lookup — would start resolving these on one path only, and produce the mirrored mismatch in the opposite direction. In our case that would newly break 7 charts plus the image dependencies sharing those files, none of which loop today.

For a fix in the manager, a regression test with both shapes above (asserting that full and single-file extraction agree, whatever the outcome) would cover the edge. The property that matters is not "the chart resolves" but "both paths agree", which also holds for the deliberately unresolvable cases.

We are keeping these seven out of our registryAliases rollout until their namespaces are aligned, and doing that alignment as a separate change with the signatures re-checked afterwards.

[sambai-dev]

@aschyolkin You are right, my mistake on the number: #45441 is the component-prefixed tags fix and unrelated to the flux rebase loop. Thanks for writing the seven pairs up here instead.

I searched the issue tracker just now and found nothing tracking the OCI HelmRepository rebase loop, so there is no number to hand you yet. This thread seems like a candidate for a tracking issue once someone from the team picks it up; it has a confirmed reproduction spanning 44.40 through 44.45.4 plus a dedicated repro repository.

Your image-branch split is a useful constraint either way: three extra loops, all in package files that also carry an unresolvable chart, none where the chart resolves. That fits the per-file signature reading even without a test isolating it.