fix(remote): resolve a git ref to the exact branch or tag

AI_AGENT_DISCLOSURE.md

@@ -0,0 +1,4 @@
+*"This contribution was prepared by an AI agent acting on a human's behalf.
+The human submitter may not have independently reviewed or tested the change."*
+
+2026-09-25

pkg/remote/git.go

@@ -180,10 +180,10 @@ func (g gitRemoteLoader) resolveGitRef(ctx context.Context, path string, ref *gi
 			}
 			return fmt.Errorf("failed to access repository at %s:\n %s", ref.Remote, out)
 		}
-		if len(out) < 40 {
-			return fmt.Errorf("unexpected git command output: %q", string(out))
+		sha, err := matchLsRemoteRef(string(out), ref.Ref)
+		if err != nil {
+			return err
 		}
-		sha := string(out[:40])
 		if !commitSHA.MatchString(sha) {
 			return fmt.Errorf("invalid commit sha %q", sha)
 		}
@@ -192,6 +192,26 @@ func (g gitRemoteLoader) resolveGitRef(ctx context.Context, path string, ref *gi
 	return nil
 }
 
+// matchLsRemoteRef picks the sha of the ref named `name` in `git ls-remote` output.
+// ls-remote matches its pattern against the tail of every ref name, so asking
+// for "main" also lists refs like "refs/heads/feature/main", sorted before
+// "refs/heads/main". Pick the exact match, using git's own lookup order.
+func matchLsRemoteRef(out, name string) (string, error) {
+	shas := map[string]string{}
+	for line := range strings.Lines(out) {
+		sha, refName, ok := strings.Cut(strings.TrimSpace(line), "\t")
+		if ok {
+			shas[refName] = sha
+		}
+	}
+	for _, candidate := range []string{name, "refs/" + name, "refs/tags/" + name, "refs/heads/" + name} {
+		if sha, ok := shas[candidate]; ok {
+			return sha, nil
+		}
+	}
+	return "", fmt.Errorf("unexpected git command output: %q", out)
+}
+
 func (g gitRemoteLoader) checkout(ctx context.Context, path string, ref *gitutil.GitRef) error {
 	err := os.MkdirAll(path, 0o700)
 	if err != nil {

pkg/remote/git_test.go

@@ -17,8 +17,11 @@
 package remote
 
 import (
+	"os/exec"
+	"strings"
 	"testing"
 
+	gitutil "github.com/moby/buildkit/frontend/dockerfile/dfgitutil"
 	"gotest.tools/v3/assert"
 )
 
@@ -173,3 +176,63 @@ func TestValidateGitSubDirSecurityScenarios(t *testing.T) {
 		assert.NilError(t, err)
 	})
 }
+
+func TestResolveGitRefPicksExactRef(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+	repo := t.TempDir()
+	git := func(args ...string) string {
+		t.Helper()
+		cmd := exec.Command("git", append([]string{"-c", "user.name=test", "-c", "user.email=test@example.com"}, args...)...)
+		cmd.Dir = repo
+		out, err := cmd.CombinedOutput()
+		assert.NilError(t, err, string(out))
+		return strings.TrimSpace(string(out))
+	}
+	git("init", "-q", "-b", "main")
+	git("commit", "-q", "--allow-empty", "-m", "on main")
+	// ls-remote matches "main" against the tail of every ref, and
+	// refs/heads/feature/main sorts before refs/heads/main.
+	git("checkout", "-q", "-b", "feature/main")
+	git("commit", "-q", "--allow-empty", "-m", "on feature/main")
+	git("tag", "v1")
+	git("checkout", "-q", "main")
+	git("commit", "-q", "--allow-empty", "-m", "on release/v1")
+	git("branch", "release/v1")
+	mainSHA := git("rev-parse", "main")
+	tagSHA := git("rev-parse", "v1")
+
+	tests := []struct {
+		ref  string
+		want string
+	}{
+		{ref: "main", want: mainSHA},
+		{ref: "refs/heads/main", want: mainSHA},
+		{ref: "v1", want: tagSHA},
+	}
+	for _, tt := range tests {
+		t.Run(tt.ref, func(t *testing.T) {
+			ref := &gitutil.GitRef{Remote: repo, Ref: tt.ref}
+			err := gitRemoteLoader{}.resolveGitRef(t.Context(), repo+"#"+tt.ref, ref)
+			assert.NilError(t, err)
+			assert.Equal(t, ref.Ref, tt.want)
+		})
+	}
+}
+
+func TestMatchLsRemoteRef(t *testing.T) {
+	out := "1111111111111111111111111111111111111111\trefs/heads/feature/main\n" +
+		"2222222222222222222222222222222222222222\trefs/heads/main\n" +
+		"3333333333333333333333333333333333333333\trefs/tags/main\n"
+	sha, err := matchLsRemoteRef(out, "main")
+	assert.NilError(t, err)
+	assert.Equal(t, sha, "3333333333333333333333333333333333333333", "git prefers a tag over a branch with the same name")
+
+	sha, err = matchLsRemoteRef(out, "refs/heads/main")
+	assert.NilError(t, err)
+	assert.Equal(t, sha, "2222222222222222222222222222222222222222")
+
+	_, err = matchLsRemoteRef(out, "feature")
+	assert.ErrorContains(t, err, "unexpected git command output")
+}