fix(controller): manual backport of git-clone fix from #3012 (#3019)

internal/directives/git_cloner.go

@@ -140,7 +140,7 @@ func (g *gitCloner) runPromotionStep(
 		switch {
 		case checkout.Branch != "":
 			ref = checkout.Branch
-			if err = ensureRemoteBranch(repo, ref); err != nil {
+			if err = ensureRemoteBranch(repo, ref, checkout.Create); err != nil {
 				return PromotionStepResult{Status: kargoapi.PromotionPhaseErrored},
 					fmt.Errorf("error ensuring existence of remote branch %s: %w", ref, err)
 			}
@@ -219,9 +219,12 @@ func mustCloneRepo(stepCtx *PromotionStepContext, cfg GitCloneConfig) (bool, err
 	return false, nil
 }
 
-// ensureRemoteBranch ensures the existence of a remote branch. If the branch
-// does not exist, an empty orphaned branch is created and pushed to the remote.
-func ensureRemoteBranch(repo git.BareRepo, branch string) error {
+// ensureRemoteBranch checks for the existence of a remote branch. If the remote
+// branch exists, no action is taken and nil is returned. If the branch does not
+// exist and create == true, an empty orphaned branch is created and pushed to
+// the remote. If the branch does not exist and create == false, an error is
+// returned.
+func ensureRemoteBranch(repo git.BareRepo, branch string, create bool) error {
 	exists, err := repo.RemoteBranchExists(branch)
 	if err != nil {
 		return fmt.Errorf(
@@ -232,6 +235,15 @@ func ensureRemoteBranch(repo git.BareRepo, branch string) error {
 	if exists {
 		return nil
 	}
+	if !create {
+		return fmt.Errorf(
+			"remote branch %q of repo %s does not exist; set create=true if you'd "+
+				"like a non-existent remote branch to be automatically created at "+
+				"checkout",
+			branch,
+			repo.URL(),
+		)
+	}
 	tmpDir, err := os.MkdirTemp("", "repo-")
 	if err != nil {
 		return fmt.Errorf("error creating temporary directory: %w", err)

internal/directives/git_cloner_test.go

@@ -320,7 +320,8 @@ func Test_gitCloner_runPromotionStep(t *testing.T) {
 				},
 				{
 					Branch: "stage/dev",
-					Path:   "dev",
+					Path:   "out",
+					Create: true,
 				},
 			},
 		},
@@ -331,11 +332,11 @@ func Test_gitCloner_runPromotionStep(t *testing.T) {
 	// The checked out master branch should have the content we know is in the
 	// test remote's master branch.
 	require.FileExists(t, filepath.Join(stepCtx.WorkDir, "master", "test.txt"))
-	require.DirExists(t, filepath.Join(stepCtx.WorkDir, "dev"))
+	require.DirExists(t, filepath.Join(stepCtx.WorkDir, "out"))
 	// The stage/dev branch is a new orphan branch with a single empty commit.
 	// It should lack any content.
-	dirEntries, err := os.ReadDir(filepath.Join(stepCtx.WorkDir, "dev"))
+	dirEntries, err := os.ReadDir(filepath.Join(stepCtx.WorkDir, "out"))
 	require.NoError(t, err)
 	require.Len(t, dirEntries, 1) // Just the .git file
-	require.FileExists(t, filepath.Join(stepCtx.WorkDir, "dev", ".git"))
+	require.FileExists(t, filepath.Join(stepCtx.WorkDir, "out", ".git"))
 }