feat: add a YAML Merger PromotionStep

[prune998]

This PR add a new Promotion Step that caan merge multiple YAML files into a single file.

This is useful in the scenario where, for example, multiple promotions (ex: one per cluster) merges content in the same repo/branch.
Then Helm will pick up the values from multiple locations, but updating global values could impact many clusters at the same time.

With this step, we are able to pre-merge global values with more specific values and only commit one single values.yaml file for each specific cluster. No more globals.

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	b537d59
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/68f62a8ccbddae0008b57f3c
😎 Deploy Preview	https://deploy-preview-4634.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[prune998]

Any way to get someone trigger the CI build ?
thx

[codecov]

Codecov Report

❌ Patch coverage is 65.38462% with 36 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.47%. Comparing base (d6b2774) to head (b537d59).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/promotion/runner/builtin/yaml_merger.go	62.02%	25 Missing and 5 partials ⚠️
pkg/yaml/yaml.go	76.00%	4 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4634      +/-   ##
==========================================
+ Coverage   55.44%   55.47%   +0.02%     
==========================================
  Files         404      405       +1     
  Lines       36426    36539     +113     
==========================================
+ Hits        20198    20270      +72     
- Misses      15265    15298      +33     
- Partials      963      971       +8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[fuskovic]

Stopped by for a drive-by review.

Concept looks reasonable to me.

Related to #4766

Linter needs to be satisfied.

I'll defer the rest to @hiddeco and @krancour

[prune998]

thanks for the review @fuskovic. Everything should be resolved + rebased now.
I'll keep watching the workflows when they run, in case any other issue is detected.

[prune998]

Anyone to review this ?

[krancour]

@prune998 I know this isn't what anyone wants to hear, but our priorities are elsewhere right now and there may be a bit of a wait for a thorough review.

Some discussion may also be in order. I see this is meant to address #4766, but no maintainer triaged that feature request or moved it out of proposal status. It's a gamble putting the effort into a feature without those conversations happening first.

In all probability, this is a worthwhile feature and it will be reviewed eventually and probably merged, but some patience may be required.

If it makes you feel any better, I have PRs open to some other projects that are old enough to be starting kindergarten. Our backlog isn't that bad, thankfully.

[krancour]

Small addendum... there are some notoriously well-known gotchas when merging YAML, so this isn't a review I'd rush through and that contributes to the above.

[prune998]

Thanks for the comment @krancour . I understand you're busy with your customers features.
The way Kargo is designed forces us to embed the promotionStep functions inside the code, which creates friction. Got it.

What you could do, would be

• have someone do a quick review, ensuring that it works and it is useful, and more importantly, is not a security or stability risk
• mark that function as alpha, not supported
• add me as support of the feature and assign me comments/issues if any
• release the feature

This way, your team will not be much impacted, the features is released, and you have a "feature maintainer".

This is just a proposition and you can refuse it. I'll wait, or keep using my forked version... but it will be a miss :)
Thanks for your time and effort anyway.

Side note on YAML merging: yeah, there's a ton of gotchas... this is why I used a "well known" library to do it and not try to re-implement it myself. The library I used is also opinionated. But it is intended for K8s yaml style. I also tested others, with varying results... Anyway, they all have the same limitations (biggest one being no merge of lists, latest list takes precedence), like Helm does, so people knowing Helm will not be disturbed.
Once I'm sure you're interrested in this feature and the code, I can add more examples in the docs and test cases in the code to better demonstrate all sort of merges. I just don't want to spend too much time if you are to refuse it. All I can say is that it is working "like Helm" for me at the moment.

[prune998]

All requested modifications applied.
Thanks for the full review @fykaa

[fykaa]

thanks @prune998 I'll do a final cleanup before approving this PR

[fykaa]

I have reviewed this PR and it works correctly for both cases - with and without ignoreMissingFiles. in its current implementation, it will error when all files in inFiles are missing and there's nothing to merge.

Deferring to @krancour for the final merge.

[prune998]

all set !! Many thanks @fykaa. Hope to see that merged soon ! Thanks all for you help

[prune998]

are we good to merge then ?