feat(git-clone): add support for submodules

[kyounghunJang]

Summary

Add submodule support to git-clone step

Related Issue

fixes #4755

Description

Currently, the git-clone step does not support submodules.
Users must manually checkout submodules in separate steps and parse .gitmodules,
which introduces unnecessary complexity.

This PR adds support for initializing submodules directly within git-clone.

Proposed Changes

• Added a new boolean config option recurseSubmodules (default: false)

[netlify]

✅ Deploy Preview for docs-kargo-io canceled.

Name	Link
🔨 Latest commit	e2a4cbe
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/68f71faa60a0a00008582572

[codecov]

Codecov Report

❌ Patch coverage is 15.38462% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.43%. Comparing base (d6b2774) to head (e2a4cbe).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/controller/git/work_tree.go	0.00%	5 Missing ⚠️
pkg/promotion/runner/builtin/git_cloner.go	33.33%	3 Missing and 1 partial ⚠️
pkg/controller/git/mock_repo.go	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4974      +/-   ##
==========================================
- Coverage   55.44%   55.43%   -0.02%     
==========================================
  Files         404      404              
  Lines       36426    36450      +24     
==========================================
+ Hits        20198    20206       +8     
- Misses      15265    15279      +14     
- Partials      963      965       +2     

☔ 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.

[hiddeco]

I think additional changes would be required to ensure credentials are properly passed, especially when each Git repository requires a different set of credentials. Which is a hypothetical possibility.

[kyounghunJang]

@hiddeco
Hello, thank you for the feedback.

Currently, this PR is designed to only allow cloning submodules that share the same credentials as the main repository. I fully recognize and agree with the need to support multiple sets of credentials.
If we were to support multiple authentications, I think the following changes would be required.

1. Currently, buildGitCommand handles HTTP using GIT_ASKPASS and GIT_PASSWORD. This is expected to only work for a single set of credentials. Therefore, I think this should be changed to use the .git-credentials mechanism instead.

2. To obtain the submodule RepoUrl, we need to perform a bare clone, then parse the .modules file, and store that information into the ClientOptions struct under a Credentials field (or SubCredentials). After that, we should fetch the correct credentials from the secret database.

3. I believe we also need a module that writes the retrieved secret information into .git-credentials.

Please let me know if my thoughts and design approach are correct. Thanks!

[krancour]

fwiw, I think doing this with the limitation of only using the same credentials as the main repository seems like it might be a reasonable first step. I say might because the devil's always in the details and I have not looked at this very closely.

Currently, buildGitCommand handles HTTP using GIT_ASKPASS and GIT_PASSWORD. This is expected to only work for a single set of credentials. Therefore, I think this should be changed to use the .git-credentials mechanism instead.

Only a word of caution that messing with any of that shouldn't be undertaken lightly and I would prefer something like that be done by a maintainer. There are a lot of esoteric reasons that git auth in Kargo is implemented as it is. There are certain approaches that don't work within a container based on a distroless image, and admittedly, I have a pipe dream of one day not even including a shell in that image, and that further restricts which approaches are viable. I definitely do not want us to fall down this particular rabbit hole at this time.

[kyounghunJang]

@krancour
Hello, thank you for your feedback.
If modifying the logic is too complex, I also believe that, as reflected in the current PR, it would be preferable to allow submodules to be fetched when they share the same authentication as the main repository. I have completed testing to confirm that submodules can be fetched successfully in cases where the authentication matches the main repository.

[etetar]

@krancour @kyounghunJang Hi! Thank you for working on this. Any chance this will make it into 1.7.6 or 1.8.0?