fix(controller)!: check create setting when attempting to clone non-existent remote branch

internal/directives/git_cloner.go

@@ -140,7 +140,7 @@
 		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)
 			}
@@ -222,9 +222,12 @@
 	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(
@@ -235,6 +238,15 @@
 	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

@@ -346,6 +346,7 @@ func Test_gitCloner_runPromotionStep(t *testing.T) {
 				{
 					Branch: "stage/dev",
 					Path:   "out",
+					Create: true,
 				},
 			},
 		},