fix!: use the git CLI for action clones and make builtin:checkout match actions/checkout (#1277)

The runner now uses the `git` command line instead of go-git to download actions and reusable workflows. go-git had recurring bugs and does not support SHA-256 repositories, and full clones of actions are several times faster.

`builtin:checkout` now runs `git` where the job runs and behaves like `actions/checkout`:

1. A branch is checked out as a local branch tracking `origin`, tag and pull request runs keep their ref, and a triggering tag that moved fails the step.
1. Later steps can fetch and push with the persisted token or SSH key.
1. It supports the `ssh-*`, `lfs`, `submodules`, `sparse-checkout`, `filter`, `fetch-tags`, `clean`, `persist-credentials`, `show-progress` and `set-safe-directory` inputs and the `ref` and `commit` outputs.
1. SHA-256 repositories work for actions, reusable workflows and `builtin:checkout`.

Git keeps the token off its command line, ignores `GIT_DIR` and similar variables inherited by the runner, and keeps action files LF regardless of `core.autocrlf`. A cancelled job lets git remove its lock files.

This is a breaking change: the runner needs Git 2.34.1 or newer on its `PATH`, and so do job images that use `builtin:checkout`. The official runner images include it.

Fixes: https://gitea.com/gitea/runner/issues/1077
Fixes: https://gitea.com/gitea/runner/issues/1267
Fixes: https://gitea.com/gitea/runner/issues/1279
Fixes: https://gitea.com/gitea/runner/issues/1284
Fixes: https://gitea.com/gitea/runner/issues/1285
Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/runner/pulls/1277
Reviewed-by: Lunny Xiao <[email protected]>
Reviewed-by: silverwind <[email protected]>
Co-authored-by: bircni <[email protected]>

internal/pkg/action/action.go

@@ -20,4 +20,5 @@ type Context struct {
 	NoSkipCheckout  bool
 	UseGitIgnore    bool
 	InsecureSkipTLS bool
+	Env             map[string]string
 }

internal/pkg/action/checkout/checkout.go

@@ -6,21 +6,36 @@ package checkout
 import (
 	"cmp"
 	"context"
+	"crypto/sha256"
+	"errors"
 	"fmt"
-	"os"
+	"maps"
+	"net/url"
 	"path"
 	"path/filepath"
+	"runtime"
 	"slices"
 	"strconv"
 	"strings"
+	"time"
 
 	"gitea.com/gitea/runner/act/common/git"
+	"gitea.com/gitea/runner/act/container"
 	"gitea.com/gitea/runner/internal/pkg/action"
+
+	"gitea.dev/actionslib/pkg/model"
+	"github.com/kballard/go-shellquote"
 )
 
-var inputNames = []string{"repository", "ref", "token", "path", "fetch-depth"}
+var inputNames = []string{
+	"repository", "ref", "token", "ssh-key", "ssh-known-hosts", "ssh-strict", "ssh-user", "persist-credentials", "path", "clean",
+	"filter", "sparse-checkout", "sparse-checkout-cone-mode", "fetch-depth", "fetch-tags", "show-progress", "lfs", "submodules",
+	"set-safe-directory",
+}
 
-func Main(ctx context.Context, c *action.Context) error {
+const credentialsInclude = "includeIf.gitdir:**.path" // the form actions/checkout removes from a repository it checks out again
+
+func Main(ctx context.Context, c *action.Context) (err error) {
 	for name := range c.Inputs {
 		if !slices.Contains(inputNames, name) {
 			return fmt.Errorf("checkout: unsupported input %q", name)
@@ -37,38 +52,382 @@ func Main(ctx context.Context, c *action.Context) error {
 
 	ghc := c.Github
 	repository := cmp.Or(c.Inputs["repository"], ghc.Repository)
-	ref := shortBranch(c.Inputs["ref"])
-	isWorkflowRepo := repository == ghc.Repository
-	local := isWorkflowRepo && slices.Contains([]string{"", shortBranch(ghc.Ref), ghc.Sha}, ref) && !c.NoSkipCheckout
-	if local && !c.BindWorkdir {
-		return c.Container.CopyDir(dst, c.HostWorkdir+string(filepath.Separator)+".", c.UseGitIgnore, false)(ctx)
-	}
-	if local && dst == c.Workspace {
+	ref := c.Inputs["ref"]
+	sshKey := strings.TrimSpace(c.Inputs["ssh-key"])
+	isWorkflowRepo := strings.EqualFold(repository, ghc.Repository)
+	local := isWorkflowRepo && slices.Contains([]string{"", shortBranch(ghc.Ref), ghc.Sha}, shortBranch(ref)) && !c.NoSkipCheckout && sshKey == ""
+	if local && (!c.BindWorkdir || dst == c.Workspace) {
+		if !c.BindWorkdir {
+			if err := c.Container.CopyDir(dst, c.HostWorkdir+string(filepath.Separator)+".", c.UseGitIgnore, false)(ctx); err != nil {
+				return err
+			}
+		}
+		if output := c.Env["GITHUB_OUTPUT"]; output != "" {
+			return c.Container.Copy(path.Dir(output), &container.FileEntry{Name: path.Base(output), Mode: 0o666, Body: fmt.Sprintf("ref=%s\ncommit=%s\n", ghc.Ref, ghc.Sha)})(ctx)
+		}
 		return nil
 	}
 
-	if ref == "" {
-		ref = "HEAD"
-		if isWorkflowRepo {
-			ref = ghc.Sha
+	co := &checkout{
+		url:       strings.TrimSuffix(ghc.ServerURL, "/") + "/" + repository,
+		dst:       dst,
+		ref:       ref,
+		depth:     depth,
+		fetchTags: boolInput(c.Inputs, "fetch-tags", false),
+		clean:     boolInput(c.Inputs, "clean", true),
+		lfs:       boolInput(c.Inputs, "lfs", false),
+		progress:  boolInput(c.Inputs, "show-progress", true),
+		cone:      boolInput(c.Inputs, "sparse-checkout-cone-mode", true),
+		filter:    strings.TrimSpace(c.Inputs["filter"]),
+		output:    c.Env["GITHUB_OUTPUT"],
+	}
+	for pattern := range strings.Lines(c.Inputs["sparse-checkout"]) {
+		if pattern = strings.TrimSpace(pattern); pattern != "" {
+			co.sparse = append(co.sparse, pattern)
 		}
 	}
-	dir, err := os.MkdirTemp("", "checkout-")
-	if err != nil {
+	if len(co.sparse) > 0 {
+		co.filter = cmp.Or(co.filter, "blob:none")
+	}
+	if submodules := strings.ToLower(strings.TrimSpace(c.Inputs["submodules"])); submodules == "true" || submodules == "recursive" {
+		co.submodules = submodules
+	}
+	if sshKey != "" {
+		if co.url, err = sshURL(ghc, repository, strings.TrimSpace(c.Inputs["ssh-user"])); err != nil {
+			return err
+		}
+	}
+	co.objectFormat = git.ObjectFormat(ref)
+	switch {
+	case co.objectFormat != "":
+		co.sha, co.ref = ref, ""
+	case ref == "" && isWorkflowRepo && strings.HasPrefix(ghc.Ref, "refs/"):
+		co.sha, co.ref = ghc.Sha, ghc.Ref
+	case ref == "" && isWorkflowRepo: // a merged pull request's ref is its merge commit
+		co.sha = ghc.Sha
+	case ref == "HEAD":
+		co.ref = ""
+	}
+	if isWorkflowRepo {
+		co.objectFormat = cmp.Or(co.objectFormat, git.ObjectFormat(ghc.Sha))
+	}
+
+	// named like actions/checkout's, which create-pull-request knows to hide, and gone with the job
+	runnerTemp, _ := c.Container.GetRunnerContext(ctx)["temp"].(string)
+	digest := sha256.Sum256([]byte(dst))
+	credentials := fmt.Sprintf("git-credentials-%x.config", digest[:8])
+	co.credentials = path.Join(runnerTemp, credentials)
+	persist := boolInput(c.Inputs, "persist-credentials", true)
+	config, remoteConfig := serverConfig(ghc.ServerURL, cmp.Or(c.Inputs["token"], ghc.Token), c.InsecureSkipTLS, co.submodules != "" && sshKey == "")
+	if boolInput(c.Inputs, "set-safe-directory", true) {
+		remoteConfig = append(remoteConfig, "safe.directory=*") // a bound workdir belongs to the host user
+	}
+	env := gitEnv(c, remoteConfig)
+	env["GIT_LFS_SKIP_SMUDGE"] = strconv.FormatBool(!co.lfs || len(co.sparse) == 0) // lfs pull fetches the objects of a full checkout in one go
+	if sshKey != "" {
+		key := fmt.Sprintf("git-ssh-key-%x", digest[:8])
+		files := []*container.FileEntry{{Name: key, Mode: 0o600, Body: sshKey + "\n"}}
+		ssh := []string{"ssh", "-i", path.Join(runnerTemp, key)}
+		if boolInput(c.Inputs, "ssh-strict", true) {
+			ssh = append(ssh, "-o", "StrictHostKeyChecking=yes", "-o", "CheckHostIP=no")
+		}
+		if knownHosts := strings.TrimSpace(c.Inputs["ssh-known-hosts"]); knownHosts != "" {
+			name := fmt.Sprintf("git-ssh-known-hosts-%x", digest[:8])
+			files = append(files, &container.FileEntry{Name: name, Mode: 0o600, Body: knownHosts + "\n"})
+			ssh = append(ssh, "-o", "UserKnownHostsFile=~/.ssh/known_hosts "+strconv.Quote(path.Join(runnerTemp, name)))
+		}
+		if !persist {
+			defer func() {
+				cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), time.Minute)
+				defer cancel()
+				err = errors.Join(err, c.Container.Copy(runnerTemp, &container.FileEntry{Name: key, Mode: 0o600})(cleanupCtx))
+			}()
+		}
+		if err := c.Container.Copy(runnerTemp, files...)(ctx); err != nil {
+			return err
+		}
+		env["GIT_SSH_COMMAND"] = shellquote.Join(ssh...)
+		config += "[core]\n\tsshCommand = " + strconv.Quote(env["GIT_SSH_COMMAND"]) + "\n"
+	}
+	if !persist {
+		config = ""
+	}
+
+	if co.objectFormat == "" || co.sha == "" && !strings.HasPrefix(co.ref, "refs/") {
+		advertised, err := lsRemote(ctx, c, env, co.url, co.ref)
+		if err != nil {
+			return fmt.Errorf("checkout: %s@%s: %w", repository, ref, err)
+		}
+		if co.resolve(advertised); co.ref == "" && co.sha == "" {
+			return fmt.Errorf("checkout: %s has no ref %q", repository, ref)
+		}
+	}
+	co.outputRef = co.ref
+	if ref != co.sha {
+		co.outputRef = cmp.Or(ref, co.ref) // as given, like actions/checkout
+	}
+	if err := c.Container.Copy(runnerTemp, &container.FileEntry{Name: credentials, Mode: 0o600, Body: config})(ctx); err != nil {
 		return err
 	}
-	defer os.RemoveAll(dir)
-	if err := git.NewGitCloneExecutor(git.NewGitCloneExecutorInput{
-		URL:             strings.TrimSuffix(ghc.ServerURL, "/") + "/" + repository,
-		Ref:             ref,
-		Dir:             dir,
-		Token:           cmp.Or(c.Inputs["token"], ghc.Token),
-		Depth:           depth,
-		InsecureSkipTLS: c.InsecureSkipTLS,
-	})(ctx); err != nil {
-		return fmt.Errorf("checkout: clone %s@%s: %w", repository, ref, err)
+
+	clone := func(commands [][]string) error {
+		if err := run(ctx, c, env, commands); err != nil {
+			return fmt.Errorf("checkout: clone %s@%s: %w", repository, cmp.Or(co.ref, co.sha), err)
+		}
+		return nil
 	}
-	return c.Container.CopyDir(dst, dir+string(filepath.Separator)+".", false, false)(ctx)
+	commands, fetched := co.commands()
+	if co.sha != "" && strings.HasPrefix(co.ref, "refs/tags/") {
+		if err := clone(commands[:fetched]); err != nil {
+			return err
+		}
+		tagged, err := output(ctx, c, env, "git", "-C", dst, "rev-parse", "--verify", "--quiet", co.ref+"^{commit}")
+		if err != nil {
+			return fmt.Errorf("checkout: %s: %w", co.ref, err)
+		}
+		if !strings.EqualFold(strings.TrimSpace(tagged), co.sha) {
+			return fmt.Errorf("checkout: %s does not point to the expected commit %s, it may have been moved after the workflow was triggered", co.ref, co.sha)
+		}
+		commands = commands[fetched:]
+	}
+	return clone(commands)
+}
+
+func gitEnv(c *action.Context, config []string) map[string]string {
+	env := map[string]string{"GIT_TERMINAL_PROMPT": "0"}
+	maps.Copy(env, c.Env)
+	maps.DeleteFunc(env, func(name, _ string) bool { return slices.Contains(git.LocalEnvVars, name) })
+	maps.Copy(env, git.ConfigEnv(append([]string{"protocol.version=2", "init.defaultBranch=main", "advice.detachedHead=false", "maintenance.auto=false"}, config...)...))
+	return env
+}
+
+func run(ctx context.Context, c *action.Context, env map[string]string, commands [][]string) error {
+	if _, host := c.Container.(*container.HostEnvironment); !host || runtime.GOOS != "windows" {
+		script := []string{"set -e", `command -v git >/dev/null || { echo "builtin:checkout needs git on PATH" >&2; exit 127; }`}
+		for _, command := range commands {
+			script = append(script, shellquote.Join(command...))
+		}
+		return c.Container.Exec([]string{"sh", "-c", strings.Join(script, "\n")}, env, "", "")(ctx)
+	}
+	for _, command := range commands {
+		if err := c.Container.Exec(command, env, "", "")(ctx); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// output runs where the job runs, so the job's network and git config apply as for the fetch.
+func output(ctx context.Context, c *action.Context, env map[string]string, command ...string) (string, error) {
+	var out strings.Builder
+	stdout, stderr := c.Container.ReplaceLogWriter(&out, &out)
+	defer c.Container.ReplaceLogWriter(stdout, stderr)
+	if err := c.Container.Exec(command, env, "", "")(ctx); err != nil {
+		return "", fmt.Errorf("%w: %s", err, strings.TrimSpace(out.String()))
+	}
+	return out.String(), nil
+}
+
+func lsRemote(ctx context.Context, c *action.Context, env map[string]string, url, ref string) (string, error) {
+	patterns := []string{ref}
+	switch {
+	case ref == "":
+		patterns = []string{"HEAD"}
+	case !strings.HasPrefix(ref, "refs/"):
+		patterns = []string{"refs/heads/" + ref, "refs/tags/" + ref}
+	}
+	return output(ctx, c, env, append([]string{"git", "ls-remote", "--symref", url}, patterns...)...)
+}
+
+// serverConfig scopes the token to the server, so no other host like a repository's LFS endpoint gets it.
+func serverConfig(serverURL, token string, insecureSkipTLS, rewriteSSH bool) (file string, env []string) {
+	scope := strings.TrimSuffix(serverURL, "/") + "/"
+	file = fmt.Sprintf("[http %q]\n", scope)
+	for _, entry := range git.RemoteConfig(token, insecureSkipTLS) {
+		setting := strings.TrimPrefix(entry, "http.")
+		key, value, _ := strings.Cut(setting, "=")
+		file += "\t" + key + " = " + value + "\n"
+		env = append(env, "http."+scope+"."+setting)
+	}
+	if server, err := url.Parse(serverURL); rewriteSSH && err == nil && server.Hostname() != "" { // submodules on the server fetch over HTTP with the token
+		file += fmt.Sprintf("[url %q]\n\tinsteadOf = git@%s:\n", scope, server.Hostname())
+		env = append(env, "url."+scope+".insteadOf=git@"+server.Hostname()+":")
+	}
+	return file, env
+}
+
+func sshURL(ghc *model.GithubContext, repository, user string) (string, error) {
+	endpoint := &url.URL{Scheme: "ssh"}
+	if advertised, _ := model.NestedMapLookup(ghc.Event, "repository", "ssh_url").(string); advertised != "" {
+		if colon := strings.LastIndex(advertised, ":"); !strings.HasPrefix(advertised, "ssh://") && colon >= 0 {
+			advertised = "ssh://" + advertised[:colon] + "/" + advertised[colon+1:] // scp-like git@host:owner/repo.git
+		}
+		var err error
+		if endpoint, err = url.Parse(advertised); err != nil {
+			return "", fmt.Errorf("checkout: parse the event's ssh_url: %w", err)
+		}
+	} else if server, err := url.Parse(ghc.ServerURL); err == nil {
+		endpoint.Host = server.Hostname()
+	}
+	endpoint.User = url.User(cmp.Or(user, endpoint.User.Username(), "git"))
+	endpoint.Path = "/" + repository + ".git"
+	return endpoint.String(), nil
+}
+
+type checkout struct {
+	url, dst, objectFormat, credentials, output, outputRef string
+	ref, sha                                               string // ref is fully qualified or empty, sha pins it when known
+	filter, submodules                                     string
+	sparse                                                 []string
+	depth                                                  int
+	fetchTags, clean, lfs, progress, cone                  bool
+}
+
+const fullDepth = "2147483647" // git's INFINITE_DEPTH, also deepens a shallow dst
+
+// commands checks out co.dst, the first `fetched` of them fetch so a fetched tag can be verified before the rest.
+func (co *checkout) commands() (commands [][]string, fetched int) {
+	repo := func(args ...string) []string { return append([]string{"git", "-C", co.dst}, args...) }
+	commands = [][]string{
+		{"git", "init", "--quiet", "--object-format=" + co.objectFormat, co.dst},
+		repo("config", "remote.origin.url", co.url), // `remote add` fails on a repeated checkout
+		repo("config", "remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*"),
+		repo("config", "--replace-all", "--fixed-value", credentialsInclude, co.credentials, co.credentials),
+	}
+	if co.lfs {
+		commands = append(commands, repo("lfs", "install", "--local"))
+	}
+
+	depth := strconv.Itoa(co.depth)
+	var refSpecs []string
+	if co.depth == 0 {
+		depth = fullDepth
+		refSpecs = append(refSpecs, "+refs/heads/*:refs/remotes/origin/*")
+	}
+	fetch := []string{"fetch", "--force", "--no-tags", "--no-recurse-submodules", "--depth", depth}
+	if co.progress {
+		fetch = append(fetch, "--progress")
+	} else {
+		fetch = append(fetch, "--no-progress")
+	}
+	if co.filter != "" {
+		fetch = append(fetch, "--filter="+co.filter)
+	}
+	if co.fetchTags || co.depth == 0 {
+		refSpecs = append(refSpecs, "+refs/tags/*:refs/tags/*")
+	}
+	tag := strings.HasPrefix(co.ref, "refs/tags/") // fetched itself, which keeps an annotated tag's object
+	pinned := co.sha != "" && co.ref != "" && !tag
+	if co.ref != "" && !pinned {
+		refSpecs = append(refSpecs, "+"+co.ref+":"+trackingRef(co.ref))
+	}
+	if co.sha != "" && !tag {
+		refSpecs = append(refSpecs, co.sha)
+	}
+	commands = append(commands, repo(append(append(fetch, "origin"), refSpecs...)...))
+	if pinned {
+		commands = append(commands, repo("update-ref", trackingRef(co.ref), co.sha))
+	}
+	fetched = len(commands)
+
+	if len(co.sparse) > 0 {
+		mode := "--cone"
+		if !co.cone {
+			mode = "--no-cone"
+		}
+		commands = append(commands, repo("sparse-checkout", "init", mode), repo(append([]string{"sparse-checkout", "set", "--"}, co.sparse...)...))
+	}
+	if branch, ok := strings.CutPrefix(co.ref, "refs/heads/"); ok {
+		commands = append(commands, repo("checkout", "--force", "--ignore-other-worktrees", "-B", branch, "--track", trackingRef(co.ref)))
+	} else {
+		commands = append(commands, repo("checkout", "--force", cmp.Or(co.sha, trackingRef(co.ref))))
+	}
+	if len(co.sparse) == 0 { // after the checkout, so a sparse dst of another repository needs nothing of it
+		commands = append(commands, repo("sparse-checkout", "disable"), repo("config", "--local", "--unset-all", "extensions.worktreeConfig"))
+	}
+	if co.lfs && len(co.sparse) == 0 {
+		commands = append(commands, repo("lfs", "pull", "origin"))
+	}
+	if co.clean {
+		commands = append(commands, repo("clean", "-ffdx"))
+	}
+	if co.submodules != "" {
+		commands = append(commands, co.submoduleCommands(repo)...)
+	}
+	if co.output != "" {
+		commands = append(commands, repo("log", "-1", "--format=commit=%H%nref="+strings.ReplaceAll(co.outputRef, "%", "%%"), "--output="+co.output))
+	}
+	return commands, fetched
+}
+
+func (co *checkout) submoduleCommands(repo func(args ...string) []string) [][]string {
+	var recursive []string
+	if co.submodules == "recursive" {
+		recursive = []string{"--recursive"}
+	}
+	foreach := func(commands ...[]string) []string {
+		joined := make([]string, len(commands))
+		for i, command := range commands {
+			joined[i] = shellquote.Join(command...)
+		}
+		return repo(append(append([]string{"submodule", "foreach"}, recursive...), strings.Join(joined, " && "))...)
+	}
+	commands := [][]string{repo(append([]string{"submodule", "sync"}, recursive...)...)}
+	if co.clean {
+		commands = append(commands, foreach([]string{"git", "clean", "-ffdx"}))
+	}
+	update := append([]string{"submodule", "update", "--init", "--force"}, recursive...)
+	if co.depth > 0 {
+		update = append(update, "--depth="+strconv.Itoa(co.depth))
+	}
+	include := []string{"git", "config", "--replace-all", "--fixed-value", credentialsInclude, co.credentials, co.credentials}
+	if co.lfs {
+		return append(commands, repo(update...), foreach([]string{"git", "lfs", "install", "--local"}, []string{"git", "lfs", "pull", "origin"}, include))
+	}
+	return append(commands, repo(update...), foreach(include))
+}
+
+func (co *checkout) resolve(advertised string) {
+	ref := co.ref
+	if !strings.HasPrefix(ref, "refs/") {
+		co.ref = ""
+	}
+	for line := range strings.Lines(advertised) {
+		value, name, _ := strings.Cut(strings.TrimSpace(line), "\t")
+		if target, ok := strings.CutPrefix(value, "ref: "); ok {
+			if name == "HEAD" {
+				co.ref = target
+			}
+			continue
+		}
+		co.objectFormat = cmp.Or(co.objectFormat, git.ObjectFormat(value))
+		switch name {
+		case "HEAD":
+			if co.ref == "" {
+				co.sha = value
+			}
+		case "refs/heads/" + ref:
+			co.ref = name
+		case "refs/tags/" + ref:
+			co.ref = cmp.Or(co.ref, name)
+		}
+	}
+	co.objectFormat = cmp.Or(co.objectFormat, "sha1")
+}
+
+func trackingRef(ref string) string {
+	if branch, ok := strings.CutPrefix(ref, "refs/heads/"); ok {
+		return "refs/remotes/origin/" + branch
+	}
+	if pull, ok := strings.CutPrefix(ref, "refs/pull/"); ok {
+		return "refs/remotes/pull/" + pull
+	}
+	return ref
+}
+
+func boolInput(inputs map[string]string, name string, fallback bool) bool {
+	value := strings.TrimSpace(inputs[name])
+	return strings.EqualFold(value, "true") || value == "" && fallback
 }
 
 func workspaceDestination(workspace, checkoutPath string) (string, error) {
@@ -91,7 +450,6 @@ func fetchDepth(input string) (int, error) {
 	return depth, nil
 }
 
-// NewGitCloneExecutor resolves branches by short name, a full tag ref stays exact.
-func shortBranch(ref string) string {
+func shortBranch(ref string) string { // full tag refs stay exact
 	return strings.TrimPrefix(ref, "refs/heads/")
 }

internal/pkg/action/checkout/checkout_test.go

@@ -4,14 +4,16 @@
 package checkout
 
 import (
-	"context"
+	"cmp"
+	"crypto/sha256"
+	"fmt"
+	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
 
-	"gitea.com/gitea/runner/act/common"
 	"gitea.com/gitea/runner/act/container"
 	"gitea.com/gitea/runner/internal/pkg/action"
 
@@ -20,22 +22,6 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-type fakeContainer struct {
-	container.ExecutionsEnvironment
-	dst, src string
-	log      []string
-}
-
-func (f *fakeContainer) CopyDir(dst, src string, _, _ bool) common.Executor {
-	return func(context.Context) error {
-		f.dst, f.src = dst, src
-		if out, err := exec.Command("git", "--git-dir", filepath.Join(src, ".git"), "log", "--format=%s").Output(); err == nil {
-			f.log = strings.Fields(string(out))
-		}
-		return nil
-	}
-}
-
 func runGit(t *testing.T, args ...string) string {
 	t.Helper()
 	cmd := exec.Command("git", args...)
@@ -49,67 +35,282 @@ func runGit(t *testing.T, args ...string) string {
 	return strings.TrimSpace(string(out))
 }
 
+func gitLog(dir string) []string {
+	out, err := exec.Command("git", "--git-dir", filepath.Join(dir, ".git"), "log", "--format=%s").Output()
+	if err != nil {
+		return nil
+	}
+	return strings.Fields(string(out))
+}
+
 func TestCheckout(t *testing.T) {
-	work := t.TempDir()
-	runGit(t, "init", "--initial-branch=main", work)
-	runGit(t, "-C", work, "commit", "--allow-empty", "-m", "c1")
-	sha := runGit(t, "-C", work, "rev-parse", "HEAD")
-	runGit(t, "-C", work, "commit", "--allow-empty", "-m", "c2")
-	runGit(t, "-C", work, "checkout", "-b", "feature")
-	runGit(t, "-C", work, "commit", "--allow-empty", "-m", "f1")
-	runGit(t, "-C", work, "checkout", "--orphan", "trunk")
-	runGit(t, "-C", work, "commit", "--allow-empty", "-m", "t1")
-	runGit(t, "-C", work, "commit", "--allow-empty", "-m", "t2")
-	runGit(t, "-C", work, "tag", "trunk", "main")
 	server := t.TempDir()
-	runGit(t, "clone", "--bare", "--branch", "main", work, filepath.Join(server, "org", "repo"))
-	runGit(t, "clone", "--bare", "--branch", "trunk", work, filepath.Join(server, "other", "repo"))
+	var sha string
+	_, lfsErr := exec.LookPath("git-lfs")
+	require.True(t, t.Run("fixtures", func(t *testing.T) {
+		t.Run("history", func(t *testing.T) {
+			t.Parallel()
+			work := t.TempDir()
+			runGit(t, "init", "--initial-branch=main", work)
+			runGit(t, "-C", work, "commit", "--allow-empty", "-m", "c1")
+			sha = runGit(t, "-C", work, "rev-parse", "HEAD")
+			runGit(t, "-C", work, "tag", "v1")
+			runGit(t, "-C", work, "commit", "--allow-empty", "-m", "c2")
+			runGit(t, "-C", work, "checkout", "-b", "feature")
+			runGit(t, "-C", work, "commit", "--allow-empty", "-m", "f1")
+			runGit(t, "-C", work, "checkout", "--orphan", "trunk")
+			runGit(t, "-C", work, "commit", "--allow-empty", "-m", "t1")
+			runGit(t, "-C", work, "commit", "--allow-empty", "-m", "t2")
+			runGit(t, "-C", work, "tag", "trunk", "main")
+			runGit(t, "clone", "--bare", "--branch", "main", work, filepath.Join(server, "org", "repo"))
+			runGit(t, "clone", "--bare", "--branch", "trunk", work, filepath.Join(server, "other", "repo"))
+			runGit(t, "-C", filepath.Join(server, "other", "repo"), "symbolic-ref", "refs/remotes/origin/HEAD", "refs/heads/main")
+		})
+		t.Run("sha256", func(t *testing.T) {
+			t.Parallel()
+			sha256Repo := filepath.Join(server, "org", "sha256")
+			runGit(t, "init", "--object-format=sha256", "--initial-branch=main", sha256Repo)
+			runGit(t, "-C", sha256Repo, "commit", "--allow-empty", "-m", "s1")
+			runGit(t, "-C", sha256Repo, "checkout", "--detach")
+		})
+		t.Run("submodules", func(t *testing.T) {
+			t.Parallel()
+			publish(t, server, "org/nested", map[string]string{"nested.txt": "nested"}, nil)
+			publish(t, server, "org/child", map[string]string{"child.txt": "child"}, map[string]string{"nested": "../nested"})
+			publish(t, server, "org/content", map[string]string{"root.txt": "root", "a/a.txt": "a", "b/b.txt": "b"}, map[string]string{"sub": "../child"})
+			runGit(t, "-C", filepath.Join(server, "org", "content"), "config", "uploadpack.allowFilter", "true")
+		})
+		t.Run("lfs", func(t *testing.T) {
+			t.Parallel()
+			oid := fmt.Sprintf("%x", sha256.Sum256([]byte("big")))
+			pointer := "version https://git-lfs.github.com/spec/v1\noid sha256:" + oid + "\nsize 3\n"
+			publish(t, server, "org/lfs", map[string]string{".gitattributes": "*.bin filter=lfs diff=lfs merge=lfs -text\n", "keep/big.bin": pointer, "drop/big.bin": pointer}, nil)
+			object := filepath.Join(server, "org", "lfs", "lfs", "objects", oid[:2], oid[2:4], oid)
+			require.NoError(t, os.MkdirAll(filepath.Dir(object), 0o755))
+			require.NoError(t, os.WriteFile(object, []byte("big"), 0o644))
+		})
+	}))
 	host := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(host, "marker"), []byte("marker"), 0o644))
+	tools := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(tools, "ssh"), []byte(`#!/bin/sh
+test -s "$2" || exit 1
+printf '%s\n' "$@" > "$SSH_ARGS"
+for last; do :; done
+exec sh -c "$(printf '%s' "$last" | sed "s#git-upload-pack '/\(.*\)\.git'#git upload-pack '$SSH_SERVER/\1'#")"
+`), 0o755))
+	globalConfig := filepath.Join(t.TempDir(), "gitconfig")
+	require.NoError(t, os.WriteFile(globalConfig, []byte("[protocol \"file\"]\n\tallow = always\n"), 0o644))
+	sshEvent := func(url string) map[string]any { return map[string]any{"repository": map[string]any{"ssh_url": url}} }
 
 	for _, tc := range []struct {
-		name          string
-		bind, noSkip  bool
-		inputs        map[string]string
-		dst           string
-		log           []string
-		hostCopy, err bool
+		name           string
+		bind, noSkip   bool
+		eventRef       string
+		event          map[string]any
+		before, inputs map[string]string
+		dst, head, err string
+		log, refs      []string
+		files, config  map[string]string
 	}{
 		{name: "bound workspace is skipped", bind: true},
-		{name: "workflow ref copies host workdir", inputs: map[string]string{"ref": "main", "path": "a/../src"}, dst: "/workspace/src", hostCopy: true},
-		{name: "bound path clones event sha", bind: true, inputs: map[string]string{"path": "src"}, dst: "/workspace/src", log: []string{"c1"}},
-		{name: "no-skip clones event sha", noSkip: true, dst: "/workspace", log: []string{"c1"}},
-		{name: "ref clones shallow", inputs: map[string]string{"ref": "refs/heads/feature"}, dst: "/workspace", log: []string{"f1"}},
-		{name: "tag ref wins over same-named branch", inputs: map[string]string{"ref": "refs/tags/trunk"}, dst: "/workspace", log: []string{"c2"}},
-		{name: "fetch-depth 0 clones full history", inputs: map[string]string{"ref": "feature", "fetch-depth": "0"}, dst: "/workspace", log: []string{"f1", "c2", "c1"}},
-		{name: "other repository defaults to its default branch", inputs: map[string]string{"repository": "other/repo"}, dst: "/workspace", log: []string{"t2"}},
-		{name: "unsupported input", inputs: map[string]string{"submodules": "true"}, err: true},
-		{name: "relative path escaping workspace", inputs: map[string]string{"path": "../x"}, err: true},
-		{name: "absolute path", inputs: map[string]string{"path": "/x"}, err: true},
-		{name: "negative fetch-depth", inputs: map[string]string{"fetch-depth": "-1"}, err: true},
+		{name: "workflow ref copies host workdir", inputs: map[string]string{"ref": "main", "path": "a/../src"}, dst: "src", files: map[string]string{"marker": "marker"}},
+		{name: "bound path checks out the event branch", bind: true, inputs: map[string]string{"path": "src"}, dst: "src", head: "main", log: []string{"c1"}},
+		{name: "no-skip checks out the event branch", noSkip: true, head: "main", log: []string{"c1"}, refs: []string{"refs/remotes/origin/main"}},
+		{name: "event tag is kept", noSkip: true, eventRef: "refs/tags/v1", log: []string{"c1"}, refs: []string{"refs/tags/v1"}},
+		{name: "moved event tag fails", noSkip: true, eventRef: "refs/tags/trunk", err: "does not point to the expected commit " + sha},
+		{name: "deleted event tag fails", noSkip: true, eventRef: "refs/tags/deleted", err: "checkout: clone"},
+		{
+			name: "sha input removes previously persisted credentials without clean", noSkip: true, before: map[string]string{"ref": sha},
+			inputs: map[string]string{"ref": sha, "persist-credentials": "false", "clean": "false"},
+			log:    []string{"c1"},
+		},
+		{name: "ref clones shallow", inputs: map[string]string{"ref": "refs/heads/feature"}, head: "feature", log: []string{"f1"}},
+		{name: "tag ref wins over same-named branch and is kept", inputs: map[string]string{"ref": "refs/tags/trunk"}, log: []string{"c2"}, refs: []string{"refs/tags/trunk"}},
+		{name: "branch ref wins over same-named tag", inputs: map[string]string{"ref": "refs/heads/trunk"}, head: "trunk", log: []string{"t2"}},
+		{
+			name: "short branch wins over same-named tag and fetch-tags fetches every tag", inputs: map[string]string{"ref": "trunk", "fetch-tags": "true"},
+			head: "trunk", log: []string{"t2"}, refs: []string{"refs/tags/trunk", "refs/tags/v1"},
+		},
+		{name: "short tag", inputs: map[string]string{"ref": "v1"}, log: []string{"c1"}, refs: []string{"refs/tags/v1"}},
+		{
+			name: "fetch-depth 0 deepens a shallow checkout to every branch and tag", before: map[string]string{"ref": "feature"},
+			inputs: map[string]string{"ref": "refs/heads/feature", "fetch-depth": "0"}, head: "feature", log: []string{"f1", "c2", "c1"},
+			refs: []string{"refs/remotes/origin/feature", "refs/remotes/origin/main", "refs/remotes/origin/trunk", "refs/tags/trunk", "refs/tags/v1"},
+		},
+		{name: "other repository defaults to its default branch", inputs: map[string]string{"repository": "other/repo"}, head: "trunk", log: []string{"t2"}},
+		{name: "explicit HEAD checks out the default branch", inputs: map[string]string{"repository": "other/repo", "ref": "HEAD"}, head: "trunk", log: []string{"t2"}},
+		{name: "detached sha256 HEAD is checked out", inputs: map[string]string{"repository": "org/sha256"}, log: []string{"s1"}},
+		{
+			name: "ssh key with the advertised endpoint persists", event: sshEvent("ssh://[email protected]:2222/org/repo.git"),
+			inputs: map[string]string{"ssh-key": "KEY", "ssh-user": "me", "ssh-known-hosts": "ssh.example ssh-ed25519 AAAA"},
+			head:   "main", log: []string{"c1"}, config: map[string]string{"remote.origin.url": "ssh://[email protected]:2222/org/repo.git"},
+		},
+		{
+			name: "ssh key without persisting is emptied", event: sshEvent("[email protected]:org/repo.git"),
+			inputs: map[string]string{"ssh-key": "KEY", "persist-credentials": "false"},
+			head:   "main", log: []string{"c1"}, config: map[string]string{"remote.origin.url": "ssh://[email protected]/org/repo.git"},
+		},
+		{
+			name: "sparse cone checkout filters blobs", inputs: map[string]string{"repository": "org/content", "sparse-checkout": "a\n", "show-progress": "false"},
+			head: "main", log: []string{"content"}, files: map[string]string{"root.txt": "root", "a/a.txt": "a", "b/b.txt": ""},
+			config: map[string]string{"remote.origin.partialclonefilter": "blob:none"},
+		},
+		{
+			name: "non-cone sparse checkout with an explicit filter", head: "main", log: []string{"content"},
+			inputs: map[string]string{"repository": "org/content", "sparse-checkout": "b/b.txt", "sparse-checkout-cone-mode": "false", "filter": "blob:limit=1024"},
+			files:  map[string]string{"root.txt": "", "a/a.txt": "", "b/b.txt": "b"}, config: map[string]string{"remote.origin.partialclonefilter": "blob:limit=1024"},
+		},
+		{
+			name: "full checkout after a sparse one restores every file", before: map[string]string{"repository": "org/content", "sparse-checkout": "a"},
+			inputs: map[string]string{"repository": "org/content", "set-safe-directory": "false"}, head: "main", log: []string{"content"},
+			files: map[string]string{"root.txt": "root", "a/a.txt": "a", "b/b.txt": "b", "sub/child.txt": ""},
+		},
+		{
+			name: "recursive submodules after plain ones", before: map[string]string{"repository": "org/content", "submodules": "true"},
+			inputs: map[string]string{"repository": "org/content", "submodules": "Recursive"}, head: "main", log: []string{"content"},
+			files: map[string]string{"sub/child.txt": "child", "sub/nested/nested.txt": "nested"},
+		},
+		{
+			name: "lfs content stays when narrowing a full checkout to a sparse one", before: map[string]string{"repository": "org/lfs", "lfs": "true"},
+			inputs: map[string]string{"repository": "org/lfs", "lfs": "true", "sparse-checkout": "keep"}, head: "main", log: []string{"content"},
+			files: map[string]string{"keep/big.bin": "big", "drop/big.bin": ""},
+		},
+		{name: "unknown ref", inputs: map[string]string{"ref": "missing"}, err: "has no ref"},
+		{name: "unsupported input", inputs: map[string]string{"github-server-url": "https://example.com"}, err: "unsupported input"},
+		{name: "relative path escaping workspace", inputs: map[string]string{"path": "../x"}, err: "must be relative"},
+		{name: "absolute path", inputs: map[string]string{"path": "/x"}, err: "must be relative"},
+		{name: "negative fetch-depth", inputs: map[string]string{"fetch-depth": "-1"}, err: "non-negative"},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
-			fc := &fakeContainer{}
-			err := Main(t.Context(), &action.Context{
-				Container:      fc,
-				Github:         &model.GithubContext{Repository: "org/repo", Ref: "refs/heads/main", Sha: sha, ServerURL: server},
-				Inputs:         tc.inputs,
-				HostWorkdir:    host,
-				Workspace:      "/workspace",
-				BindWorkdir:    tc.bind,
-				NoSkipCheckout: tc.noSkip,
-			})
-			if tc.err {
-				require.Error(t, err)
-				assert.Empty(t, fc.dst)
+			t.Parallel()
+			if tc.inputs["lfs"] == "true" && lfsErr != nil {
+				t.Skip("needs git-lfs")
+			}
+			workspace, runnerTemp := t.TempDir(), t.TempDir()
+			output := filepath.Join(runnerTemp, "output")
+			checkout := func(inputs map[string]string) error {
+				return Main(t.Context(), &action.Context{
+					Container: &container.HostEnvironment{Path: workspace, TmpDir: runnerTemp, StdOut: io.Discard},
+					Github: &model.GithubContext{
+						Repository: "org/repo", Ref: cmp.Or(tc.eventRef, "refs/heads/main"), Sha: sha, ServerURL: "file://" + server, Token: "tok", Event: tc.event,
+					},
+					Inputs:         inputs,
+					HostWorkdir:    host,
+					Workspace:      workspace,
+					BindWorkdir:    tc.bind,
+					NoSkipCheckout: tc.noSkip,
+					Env: map[string]string{
+						"PATH": tools + string(os.PathListSeparator) + os.Getenv("PATH"), "GIT_CONFIG_GLOBAL": globalConfig, "GIT_CONFIG_NOSYSTEM": "1",
+						"GIT_DIR": host, "GITHUB_OUTPUT": output, "SSH_SERVER": server, "SSH_ARGS": filepath.Join(runnerTemp, "ssh-args"),
+					},
+				})
+			}
+			dst := filepath.Join(workspace, tc.dst)
+			if tc.err != "" {
+				require.ErrorContains(t, checkout(tc.inputs), tc.err)
+				if tc.eventRef == "" {
+					entries, _ := os.ReadDir(workspace)
+					assert.Empty(t, entries)
+				} else {
+					assert.Nil(t, gitLog(dst))
+				}
 				return
 			}
+			first := tc.before
+			if first == nil {
+				first = tc.inputs
+			}
+			require.NoError(t, checkout(first))
+			repos := []string{dst}
+			if fileExists(filepath.Join(dst, "sub", ".git")) {
+				repos = append(repos, filepath.Join(dst, "sub"))
+			}
+			for _, repo := range repos {
+				require.NoError(t, os.WriteFile(filepath.Join(repo, "untracked"), nil, 0o644))
+			}
+			require.NoError(t, checkout(tc.inputs))
+			outputs, err := os.ReadFile(output)
 			require.NoError(t, err)
-			assert.Equal(t, tc.dst, fc.dst)
-			assert.Equal(t, tc.log, fc.log)
-			assert.Equal(t, tc.hostCopy, strings.HasPrefix(fc.src, host))
-			if tc.log != nil {
-				assert.NoDirExists(t, fc.src)
+			assert.Equal(t, tc.log, gitLog(dst))
+			for name, content := range tc.files {
+				body, err := os.ReadFile(filepath.Join(dst, name))
+				assert.Equal(t, content, strings.TrimSpace(string(body)), name)
+				assert.Equal(t, content == "", os.IsNotExist(err), name)
+			}
+			assert.Equal(t, tc.files["marker"] != "", fileExists(filepath.Join(dst, "marker")))
+			for key, value := range tc.config {
+				assert.Equal(t, value, gitOutput(dst, "config", key), key)
+			}
+			if tc.refs != nil {
+				assert.Subset(t, strings.Fields(runGit(t, "-C", dst, "for-each-ref", "--format=%(refname)")), tc.refs)
+			}
+			if tc.log == nil {
+				assert.Contains(t, string(outputs), "commit="+sha+"\n")
+				assert.Contains(t, string(outputs), "ref="+cmp.Or(tc.eventRef, "refs/heads/main")+"\n")
+				return
+			}
+			if tc.head == "" {
+				assert.Empty(t, gitOutput(dst, "symbolic-ref", "-q", "HEAD"))
+			} else {
+				assert.Equal(t, "refs/heads/"+tc.head, gitOutput(dst, "symbolic-ref", "-q", "HEAD"))
+				assert.Equal(t, "origin/"+tc.head, gitOutput(dst, "rev-parse", "--abbrev-ref", "@{u}"))
+			}
+			assert.Contains(t, string(outputs), "commit="+gitOutput(dst, "rev-parse", "HEAD")+"\n")
+			if inputRef := tc.inputs["ref"]; inputRef != "" && inputRef != sha {
+				assert.Contains(t, string(outputs), "ref="+inputRef+"\n")
+			}
+			assert.Equal(t, tc.inputs["sparse-checkout"] != "", gitOutput(dst, "config", "--local", "extensions.worktreeConfig") == "true")
+			persisted := tc.inputs["persist-credentials"] != "false"
+			for _, repo := range repos {
+				assert.Equal(t, tc.inputs["clean"] == "false", fileExists(filepath.Join(repo, "untracked")), repo)
+				assert.Len(t, strings.Fields(gitOutput(repo, "config", "--local", "--get-all", credentialsInclude)), 1, repo)
+				headers, _ := exec.Command("git", "-C", repo, "config", "--get-all", "http.file://"+server+"/.extraheader").Output()
+				assert.Equal(t, persisted, string(headers) == "\nAuthorization: Basic dG9rZW46dG9r\n", repo)
+			}
+			if tc.inputs["ssh-key"] != "" {
+				keys, _ := filepath.Glob(filepath.Join(runnerTemp, "git-ssh-key-*"))
+				require.Len(t, keys, 1)
+				key, _ := os.ReadFile(keys[0])
+				if persisted {
+					assert.Equal(t, "KEY\n", string(key))
+				} else {
+					assert.Empty(t, key)
+				}
+				args, _ := os.ReadFile(filepath.Join(runnerTemp, "ssh-args"))
+				assert.Contains(t, string(args), "StrictHostKeyChecking=yes")
+				assert.Equal(t, tc.inputs["ssh-known-hosts"] != "", strings.Contains(string(args), "UserKnownHostsFile="))
+				assert.Equal(t, persisted, gitOutput(dst, "config", "core.sshCommand") != "")
 			}
 		})
 	}
 }
+
+func publish(t *testing.T, server, name string, files, submodules map[string]string) {
+	work := t.TempDir()
+	runGit(t, "init", "--initial-branch=main", work)
+	for file, content := range files {
+		require.NoError(t, os.MkdirAll(filepath.Dir(filepath.Join(work, file)), 0o755))
+		require.NoError(t, os.WriteFile(filepath.Join(work, file), []byte(content), 0o644))
+	}
+	runGit(t, "-C", work, "add", ".")
+	for path, url := range submodules {
+		runGit(t, "-C", work, "config", "-f", ".gitmodules", "submodule."+path+".path", path)
+		runGit(t, "-C", work, "config", "-f", ".gitmodules", "submodule."+path+".url", url)
+		commit := runGit(t, "--git-dir", filepath.Join(server, name, url), "rev-parse", "main")
+		runGit(t, "-C", work, "update-index", "--add", "--cacheinfo", "160000,"+commit+","+path)
+		runGit(t, "-C", work, "add", ".gitmodules")
+	}
+	runGit(t, "-C", work, "commit", "-m", "content")
+	runGit(t, "clone", "--bare", "--quiet", work, filepath.Join(server, name))
+}
+
+func gitOutput(dir string, args ...string) string {
+	out, _ := exec.Command("git", append([]string{"-C", dir}, args...)...).Output()
+	return strings.TrimSpace(string(out))
+}
+
+func fileExists(name string) bool {
+	_, err := os.Stat(name)
+	return err == nil
+}