[Feature request] Push branch/refspec templating to enable PR-driven update flow in monorepos

[crabique]

Hello!

I want to propose a change that would be super useful for people using a single ImageUpdateAutomation for updating image references in monorepos.

At the moment, the ImageUpdateAutomation resource supports pushing image updates to a branch that is different to the checkout one, this could be used to implement a flow where a pull request is automatically opened for such updates.

Unfortunately, since the push .branch/.refspec is hardcoded in the resource itself, all updates done by a single ImageUpdateAutomation will all be pushed to the same branch. This makes it awkward to use with monorepos: first PR is opened as intended, but if it's not merged before a new image update happens, the new update will be pushed to the same branch, thus adding it to the first PR (loss of granularity), while no PR will be created for the newer change.

I am proposing an addition of a bool key like .spec.git.push.useTemplates that would enable go-template rendering in .spec.git.push.branch or .spec.git.push.refspec: this keeps the backwards compatibility and would be false by default.

Enabling this feature would allow users to implement at least a per-ImagePolicy updates that can be atomically turned into PRs.

Example:

spec:
  git:
    push:
      # all updates done by a single ImagePolicy will be pushed to this branch
      # automatic PR creation on Git server's end can be setup based on the 'image-bump/' prefix
      branch: 'image-bump/{{ .PolicyObject }}'
      useTemplates: true

This .PolicyObject variable is essentially already available in commit message templating as .Changed.Changes[].Setter.

Alternatively, the template could support other useful variables to allow for a smarter management/grouping of such changes:

• an imageGroup: label value of ImagePolicies—would allow to open a PR for a group of related images all in one place
• SemVer mask (e.g. compare current version to the new, and reduce it to v1.2.X)—similar to how Renovate does it—makes it clear just from the branch name whether it's a patch, minor or a major update; based on this, automatic merge rules can be applied conditionally
• raw old and new version values (.Changed.Changes[].{Old,New}Value)—similar to how it's implemented in tools like ArgoCD image updater
• I could think of more (digests and so on), but even what's already listed above would cover vast majority of use-cases

Hopefully, this proposal makes sense to you, but I will be glad to answer any questions. Thanks!

[matheuscscp]

One alternative is using .spec.policySelector for restricting which ImagePolicies your ImageUpdateAutomation should use:

https://fluxcd.io/flux/components/image/imageupdateautomations/#policyselector

[crabique]

One alternative is using .spec.policySelector for restricting which ImagePolicies your ImageUpdateAutomation should use:

https://fluxcd.io/flux/components/image/imageupdateautomations/#policyselector

While it is certainly a solution, to achieve a fully independent per-policy update flow it would require creating a separate ImageUpdateAutomation for each ImagePolicy, and hardcoding a corresponding .spec.update.path for each of them to prevent it from needlessly re-scanning the same files multiple times.

Unfortunately, this is a lot more boilerplate overhead in terms of the number of resources and duplications of .spec.git.commit alone. Not sure about possible performance implications if the number of such resources gets very high, but could also be a concern.

My proposal is aimed to make the management of this easier, so that a single automation resource (that already has the filesystem context of all defined setters in a repository path) could be seamlessly changed to group/split those changes based on the ref template render output.

P.S.I forgot to mention that I saw informal requests for this feature in both CNCF Slack and https://github.com/fluxcd/image-automation-controller/issues/524#issuecomment-2692263012, so this issue is more of a consolidated/formal place to have a discussion.