refactor: move act under internal

The runner is an application, not a library. `act/model` and
`act/exprparser` were the last packages anything outside this repository
consumed and they now live in actionslib, so nothing needs the rest of
`act` to be importable, and keeping it importable invites the coupling
that was just removed.

Import paths only, the files are unchanged.

Assisted-by: Codet:GPT-5.1-Codex

internal/act/common/context_helpers_test.go

@@ -0,0 +1,73 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/sirupsen/logrus"
+)
+
+func TestDryrunContext(t *testing.T) {
+	ctx := context.Background()
+	if Dryrun(ctx) {
+		t.Fatal("plain context should not be dryrun")
+	}
+	if !Dryrun(WithDryrun(ctx, true)) {
+		t.Fatal("WithDryrun(true) should set dryrun")
+	}
+	if Dryrun(WithDryrun(ctx, false)) {
+		t.Fatal("WithDryrun(false) should clear dryrun")
+	}
+}
+
+func TestJobErrorContainer(t *testing.T) {
+	ctx := context.Background()
+	err := errors.New("job failed")
+
+	SetJobError(ctx, err)
+	if got := JobError(ctx); got != nil {
+		t.Fatalf("JobError without container = %v, want nil", got)
+	}
+
+	ctx = WithJobErrorContainer(ctx)
+	SetJobError(ctx, err)
+	if got := JobError(ctx); !errors.Is(got, err) {
+		t.Fatalf("JobError = %v, want %v", got, err)
+	}
+}
+
+func TestLoggerAndHookContext(t *testing.T) {
+	ctx := context.Background()
+	if Logger(ctx) != logrus.StandardLogger() {
+		t.Fatal("plain context should use standard logger")
+	}
+	if LoggerHook(ctx) != nil {
+		t.Fatal("plain context should not have a logger hook")
+	}
+
+	logger := logrus.New()
+	ctx = WithLogger(ctx, logger)
+	if Logger(ctx) != logger {
+		t.Fatal("WithLogger should set logger")
+	}
+
+	hook := testHook{}
+	ctx = WithLoggerHook(ctx, hook)
+	if LoggerHook(ctx) != hook {
+		t.Fatal("WithLoggerHook should set hook")
+	}
+}
+
+type testHook struct{}
+
+func (testHook) Levels() []logrus.Level {
+	return logrus.AllLevels
+}
+
+func (testHook) Fire(*logrus.Entry) error {
+	return nil
+}

internal/act/common/dryrun.go

@@ -0,0 +1,29 @@
+// Copyright 2020 The Gitea Authors. All rights reserved.
+// Copyright 2020 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+)
+
+type dryrunContextKey string
+
+const dryrunContextKeyVal = dryrunContextKey("dryrun")
+
+// Dryrun returns true if the current context is dryrun
+func Dryrun(ctx context.Context) bool {
+	val := ctx.Value(dryrunContextKeyVal)
+	if val != nil {
+		if dryrun, ok := val.(bool); ok {
+			return dryrun
+		}
+	}
+	return false
+}
+
+// WithDryrun adds a value to the context for dryrun
+func WithDryrun(ctx context.Context, dryrun bool) context.Context {
+	return context.WithValue(ctx, dryrunContextKeyVal, dryrun)
+}

internal/act/common/executor.go

@@ -0,0 +1,201 @@
+// Copyright 2023 The Gitea Authors. All rights reserved.
+// Copyright 2020 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+	"fmt"
+	"runtime/debug"
+
+	log "github.com/sirupsen/logrus"
+)
+
+// Executor define contract for the steps of a workflow
+type Executor func(ctx context.Context) error
+
+// Conditional define contract for the conditional predicate
+type Conditional func(ctx context.Context) bool
+
+// NewInfoExecutor is an executor that logs messages
+func NewInfoExecutor(format string, args ...any) Executor {
+	return func(ctx context.Context) error {
+		logger := Logger(ctx)
+		logger.Infof(format, args...)
+		return nil
+	}
+}
+
+// NewDebugExecutor is an executor that logs messages
+func NewDebugExecutor(format string, args ...any) Executor {
+	return func(ctx context.Context) error {
+		logger := Logger(ctx)
+		logger.Debugf(format, args...)
+		return nil
+	}
+}
+
+// NewPipelineExecutor creates a new executor from a series of other executors
+func NewPipelineExecutor(executors ...Executor) Executor {
+	if len(executors) == 0 {
+		return func(ctx context.Context) error {
+			return nil
+		}
+	}
+	var rtn Executor
+	for _, executor := range executors {
+		if rtn == nil {
+			rtn = executor
+		} else {
+			rtn = rtn.Then(executor)
+		}
+	}
+	return rtn
+}
+
+// NewConditionalExecutor creates a new executor based on conditions
+func NewConditionalExecutor(conditional Conditional, trueExecutor, falseExecutor Executor) Executor {
+	return func(ctx context.Context) error {
+		if conditional(ctx) {
+			if trueExecutor != nil {
+				return trueExecutor(ctx)
+			}
+		} else {
+			if falseExecutor != nil {
+				return falseExecutor(ctx)
+			}
+		}
+		return nil
+	}
+}
+
+// NewErrorExecutor creates a new executor that always errors out
+func NewErrorExecutor(err error) Executor {
+	return func(ctx context.Context) error {
+		return err
+	}
+}
+
+// NewParallelExecutor creates a new executor from a parallel of other executors
+func NewParallelExecutor(parallel int, executors ...Executor) Executor {
+	if len(executors) == 0 {
+		return func(ctx context.Context) error {
+			return ctx.Err()
+		}
+	}
+
+	return func(ctx context.Context) error {
+		work := make(chan Executor, len(executors))
+		errs := make(chan error, len(executors))
+
+		if 1 > parallel {
+			log.Debugf("Parallel tasks (%d) below minimum, setting to 1", parallel)
+			parallel = 1
+		}
+
+		log.Infof("NewParallelExecutor: Creating %d workers for %d executors", parallel, len(executors))
+
+		for i := 0; i < parallel; i++ {
+			go func(workerID int, work <-chan Executor, errs chan<- error) {
+				log.Debugf("Worker %d started", workerID)
+				taskCount := 0
+				for executor := range work {
+					taskCount++
+					log.Debugf("Worker %d executing task %d", workerID, taskCount)
+					// Recover from panics in executors to avoid crashing the worker
+					// goroutine which would leave the runner process hung.
+					// https://gitea.com/gitea/runner/issues/371
+					errs <- func() (err error) {
+						defer func() {
+							if r := recover(); r != nil {
+								log.Errorf("panic in executor: %v\n%s", r, debug.Stack())
+								err = fmt.Errorf("panic: %v", r)
+							}
+						}()
+						return executor(ctx)
+					}()
+				}
+				log.Debugf("Worker %d finished (%d tasks executed)", workerID, taskCount)
+			}(i, work, errs)
+		}
+
+		for i := range executors {
+			work <- executors[i]
+		}
+		close(work)
+
+		// Executor waits all executors to cleanup these resources.
+		var firstErr error
+		for range executors {
+			err := <-errs
+			if firstErr == nil {
+				firstErr = err
+			}
+		}
+
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		return firstErr
+	}
+}
+
+// Then runs another executor if this executor succeeds
+func (e Executor) Then(then Executor) Executor {
+	return func(ctx context.Context) error {
+		if err := e(ctx); err != nil {
+			return err
+		}
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+		return then(ctx)
+	}
+}
+
+// If only runs this executor if conditional is true
+func (e Executor) If(conditional Conditional) Executor {
+	return func(ctx context.Context) error {
+		if conditional(ctx) {
+			return e(ctx)
+		}
+		return nil
+	}
+}
+
+// IfNot only runs this executor if conditional is true
+func (e Executor) IfNot(conditional Conditional) Executor {
+	return func(ctx context.Context) error {
+		if !conditional(ctx) {
+			return e(ctx)
+		}
+		return nil
+	}
+}
+
+// IfBool only runs this executor if conditional is true
+func (e Executor) IfBool(conditional bool) Executor {
+	return e.If(func(ctx context.Context) bool {
+		return conditional
+	})
+}
+
+// Finally adds an executor to run after other executor
+func (e Executor) Finally(finally Executor) Executor {
+	return func(ctx context.Context) error {
+		err := e(ctx)
+		err2 := finally(ctx)
+		if err2 != nil {
+			return fmt.Errorf("Error occurred running finally: %v (original error: %v)", err2, err)
+		}
+		return err
+	}
+}
+
+// Not return an inverted conditional
+func (c Conditional) Not() Conditional {
+	return func(ctx context.Context) bool {
+		return !c(ctx)
+	}
+}

internal/act/common/executor_test.go

@@ -0,0 +1,232 @@
+// Copyright 2023 The Gitea Authors. All rights reserved.
+// Copyright 2020 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewWorkflow(t *testing.T) {
+	assert := assert.New(t)
+
+	ctx := context.Background()
+
+	// empty
+	emptyWorkflow := NewPipelineExecutor()
+	assert.NoError(emptyWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
+
+	// error case
+	errorWorkflow := NewErrorExecutor(errors.New("test error"))
+	assert.Error(errorWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
+
+	// multiple success case
+	runcount := 0
+	successWorkflow := NewPipelineExecutor(
+		func(ctx context.Context) error {
+			runcount++
+			return nil
+		},
+		func(ctx context.Context) error {
+			runcount++
+			return nil
+		})
+	assert.NoError(successWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
+	assert.Equal(2, runcount)
+}
+
+func TestNewConditionalExecutor(t *testing.T) {
+	assert := assert.New(t)
+
+	ctx := context.Background()
+
+	trueCount := 0
+	falseCount := 0
+
+	err := NewConditionalExecutor(func(ctx context.Context) bool {
+		return false
+	}, func(ctx context.Context) error {
+		trueCount++
+		return nil
+	}, func(ctx context.Context) error {
+		falseCount++
+		return nil
+	})(ctx)
+
+	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	assert.Equal(0, trueCount)
+	assert.Equal(1, falseCount)
+
+	err = NewConditionalExecutor(func(ctx context.Context) bool {
+		return true
+	}, func(ctx context.Context) error {
+		trueCount++
+		return nil
+	}, func(ctx context.Context) error {
+		falseCount++
+		return nil
+	})(ctx)
+
+	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	assert.Equal(1, trueCount)
+	assert.Equal(1, falseCount)
+}
+
+// concurrencyProbe returns an executor recording the peak number of concurrent copies. Copies
+// block until wantActive are in flight so the peak is exact without sleeping, and later copies
+// find the gate already open so the last one still finishes with no partner left.
+func concurrencyProbe(wantActive int32) (exec Executor, count, maxActive *atomic.Int32) {
+	var counted, active, peak atomic.Int32
+	var once sync.Once
+	reached := make(chan struct{})
+
+	return func(ctx context.Context) error {
+		counted.Add(1)
+		running := active.Add(1)
+		for {
+			seen := peak.Load()
+			if running <= seen || peak.CompareAndSwap(seen, running) {
+				break
+			}
+		}
+		if running >= wantActive {
+			once.Do(func() { close(reached) })
+		}
+		<-reached
+		active.Add(-1)
+		return nil
+	}, &counted, &peak
+}
+
+func TestNewParallelExecutor(t *testing.T) {
+	ctx := context.Background()
+
+	exec, count, maxActive := concurrencyProbe(2)
+	require.NoError(t, NewParallelExecutor(2, exec, exec, exec)(ctx))
+	assert.Equal(t, int32(3), count.Load(), "should run all 3 executors")
+	assert.Equal(t, int32(2), maxActive.Load(), "should run at most 2 executors in parallel")
+
+	// parallelism below 1 falls back to a single worker
+	exec, count, maxActive = concurrencyProbe(1)
+	require.NoError(t, NewParallelExecutor(0, exec, exec, exec)(ctx))
+	assert.Equal(t, int32(3), count.Load(), "should run all 3 executors")
+	assert.Equal(t, int32(1), maxActive.Load(), "should run at most 1 executor in parallel")
+}
+
+func TestNewParallelExecutorEmpty(t *testing.T) {
+	assert := assert.New(t)
+
+	ctx := context.Background()
+	require.NoError(t, NewParallelExecutor(2)(ctx))
+
+	canceledCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err := NewParallelExecutor(2)(canceledCtx)
+	assert.ErrorIs(err, context.Canceled)
+}
+
+func TestNewParallelExecutorFailed(t *testing.T) {
+	assert := assert.New(t)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	count := 0
+	errorWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
+		count++
+		return errors.New("fake error")
+	})
+	err := NewParallelExecutor(1, errorWorkflow)(ctx)
+	assert.Equal(1, count)
+	assert.ErrorIs(context.Canceled, err)
+}
+
+func TestNewParallelExecutorCanceled(t *testing.T) {
+	assert := assert.New(t)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	errExpected := errors.New("fake error")
+
+	var count atomic.Int32
+	successWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
+		count.Add(1)
+		return nil
+	})
+	errorWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
+		count.Add(1)
+		return errExpected
+	})
+	err := NewParallelExecutor(3, errorWorkflow, successWorkflow, successWorkflow)(ctx)
+	assert.Equal(int32(3), count.Load())
+	assert.Error(errExpected, err) //nolint:testifylint // pre-existing issue from nektos/act
+}
+
+func TestNewParallelExecutorRunsRemainingAfterFailure(t *testing.T) {
+	var successCount atomic.Int32
+	executors := make([]Executor, 5)
+	for i := range executors {
+		executors[i] = func(ctx context.Context) error {
+			if i == 2 {
+				return errors.New("fake error")
+			}
+			successCount.Add(1)
+			return nil
+		}
+	}
+
+	require.Error(t, NewParallelExecutor(2, executors...)(context.Background()))
+	assert.Equal(t, int32(4), successCount.Load(), "a failing executor must not stop the others")
+}
+
+func TestExecutorConditionalsAndFinally(t *testing.T) {
+	ctx := context.Background()
+	var calls []string
+	record := func(name string) Executor {
+		return func(ctx context.Context) error {
+			calls = append(calls, name)
+			return nil
+		}
+	}
+
+	require.NoError(t, record("if-true").If(func(context.Context) bool { return true })(ctx))
+	require.NoError(t, record("if-false").If(func(context.Context) bool { return false })(ctx))
+	require.NoError(t, record("if-not").IfNot(func(context.Context) bool { return false })(ctx))
+	require.NoError(t, record("if-bool").IfBool(true)(ctx))
+	require.NoError(t, record("main").Finally(record("finally"))(ctx))
+
+	want := []string{"if-true", "if-not", "if-bool", "main", "finally"}
+	if !reflect.DeepEqual(calls, want) {
+		t.Fatalf("calls = %v, want %v", calls, want)
+	}
+}
+
+func TestExecutorFinallyReturnsFinallyErrorWithOriginal(t *testing.T) {
+	mainErr := errors.New("main failed")
+	finalErr := errors.New("cleanup failed")
+
+	err := NewErrorExecutor(mainErr).Finally(NewErrorExecutor(finalErr))(context.Background())
+	require.Error(t, err)
+	if !strings.Contains(err.Error(), "cleanup failed") || !strings.Contains(err.Error(), "main failed") {
+		t.Fatalf("finally error = %q, want both cleanup and original error", err)
+	}
+}
+
+func TestConditionalNot(t *testing.T) {
+	cond := Conditional(func(context.Context) bool { return false })
+	if !cond.Not()(context.Background()) {
+		t.Fatal("inverted conditional should be true")
+	}
+}

internal/act/common/git/git.go

@@ -0,0 +1,542 @@
+// Copyright 2022 The Gitea Authors. All rights reserved.
+// Copyright 2022 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package git
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path"
+	"regexp"
+	"strings"
+	"sync"
+
+	"gitea.com/gitea/runner/internal/act/common"
+	"gitea.com/gitea/runner/internal/pkg/lock"
+
+	"github.com/go-git/go-git/v5"
+	"github.com/go-git/go-git/v5/config"
+	"github.com/go-git/go-git/v5/plumbing"
+	"github.com/go-git/go-git/v5/plumbing/storer"
+	"github.com/go-git/go-git/v5/plumbing/transport/http"
+	"github.com/mattn/go-isatty"
+	log "github.com/sirupsen/logrus"
+)
+
+var (
+	codeCommitHTTPRegex = regexp.MustCompile(`^https?://git-codecommit\.(.+)\.amazonaws.com/v1/repos/(.+)$`)
+	codeCommitSSHRegex  = regexp.MustCompile(`ssh://git-codecommit\.(.+)\.amazonaws.com/v1/repos/(.+)$`)
+	githubHTTPRegex     = regexp.MustCompile(`^https?://.*github.com.*/(.+)/(.+?)(?:.git)?$`)
+	githubSSHRegex      = regexp.MustCompile(`github.com[:/](.+)/(.+?)(?:.git)?$`)
+
+	cloneLocks lock.Keyed[string] // key: clone target directory
+
+	ErrShortRef = errors.New("short SHA references are not supported")
+	ErrNoRepo   = errors.New("unable to find git repo")
+)
+
+// AcquireCloneLock returns an unlock function after locking the per-directory mutex for dir.
+// Only concurrent operations targeting the same directory are serialized; clones into different directories run in parallel.
+// Callers reading files inside dir (e.g. tarring a checked-out action into a job container) must hold this lock too,
+// otherwise a concurrent NewGitCloneExecutor on the same dir can mutate the worktree mid-read.
+func AcquireCloneLock(dir string) func() {
+	return cloneLocks.Lock(dir)
+}
+
+type Error struct {
+	err    error
+	commit string
+}
+
+func (e *Error) Error() string {
+	return e.err.Error()
+}
+
+func (e *Error) Unwrap() error {
+	return e.err
+}
+
+func (e *Error) Commit() string {
+	return e.commit
+}
+
+// goGitMu serializes go-git repository access across the process. go-git is not safe for
+// concurrent use of the same repository (even read access decodes packfiles into shared
+// state), so parallel jobs inspecting the shared workdir repo race without this. The guarded
+// operations are fast local reads; gitea runs one job per process, so the lock is effectively
+// uncontended in production.
+var goGitMu sync.Mutex
+
+// FindGitRevision get the current git revision
+func FindGitRevision(ctx context.Context, file string) (shortSha, sha string, err error) {
+	goGitMu.Lock()
+	defer goGitMu.Unlock()
+	return findGitRevision(ctx, file)
+}
+
+func findGitRevision(ctx context.Context, file string) (shortSha, sha string, err error) {
+	logger := common.Logger(ctx)
+
+	gitDir, err := git.PlainOpenWithOptions(
+		file,
+		&git.PlainOpenOptions{
+			DetectDotGit:          true,
+			EnableDotGitCommonDir: true,
+		},
+	)
+	if err != nil {
+		logger.WithError(err).Error("path", file, "not located inside a git repository")
+		return "", "", err
+	}
+
+	head, err := gitDir.Reference(plumbing.HEAD, true)
+	if err != nil {
+		return "", "", err
+	}
+
+	if head.Hash().IsZero() {
+		return "", "", errors.New("HEAD sha1 could not be resolved")
+	}
+
+	hash := head.Hash().String()
+
+	logger.Debugf("Found revision: %s", hash)
+	return hash[:7], strings.TrimSpace(hash), nil
+}
+
+// FindGitRef get the current git ref
+func FindGitRef(ctx context.Context, file string) (string, error) {
+	goGitMu.Lock()
+	defer goGitMu.Unlock()
+
+	logger := common.Logger(ctx)
+
+	logger.Debugf("Loading revision from git directory")
+	_, ref, err := findGitRevision(ctx, file)
+	if err != nil {
+		return "", err
+	}
+
+	logger.Debugf("HEAD points to '%s'", ref)
+
+	// Prefer the git library to iterate over the references and find a matching tag or branch.
+	refTag := ""
+	refBranch := ""
+	repo, err := git.PlainOpenWithOptions(
+		file,
+		&git.PlainOpenOptions{
+			DetectDotGit:          true,
+			EnableDotGitCommonDir: true,
+		},
+	)
+	if err != nil {
+		return "", err
+	}
+
+	iter, err := repo.References()
+	if err != nil {
+		return "", err
+	}
+
+	// find the reference that matches the revision's has
+	err = iter.ForEach(func(r *plumbing.Reference) error {
+		/* tags and branches will have the same hash
+		 * when a user checks out a tag, it is not mentioned explicitly
+		 * in the go-git package, we must identify the revision
+		 * then check if any tag matches that revision,
+		 * if so then we checked out a tag
+		 * else we look for branches and if matches,
+		 * it means we checked out a branch
+		 *
+		 * If a branches matches first we must continue and check all tags (all references)
+		 * in case we match with a tag later in the interation
+		 */
+		if r.Hash().String() == ref {
+			if r.Name().IsTag() {
+				refTag = r.Name().String()
+			}
+			if r.Name().IsBranch() {
+				refBranch = r.Name().String()
+			}
+		}
+
+		// we found what we where looking for
+		if refTag != "" && refBranch != "" {
+			return storer.ErrStop
+		}
+
+		return nil
+	})
+	if err != nil {
+		return "", err
+	}
+
+	// order matters here see above comment.
+	if refTag != "" {
+		return refTag, nil
+	}
+	if refBranch != "" {
+		return refBranch, nil
+	}
+
+	return "", fmt.Errorf("failed to identify reference (tag/branch) for the checked-out revision '%s'", ref)
+}
+
+// FindGithubRepo get the repo
+func FindGithubRepo(ctx context.Context, file, githubInstance, remoteName string) (string, error) {
+	goGitMu.Lock()
+	defer goGitMu.Unlock()
+	if remoteName == "" {
+		remoteName = "origin"
+	}
+
+	url, err := findGitRemoteURL(ctx, file, remoteName)
+	if err != nil {
+		return "", err
+	}
+	_, slug, err := findGitSlug(url, githubInstance)
+	return slug, err
+}
+
+func findGitRemoteURL(_ context.Context, file, remoteName string) (string, error) {
+	repo, err := git.PlainOpenWithOptions(
+		file,
+		&git.PlainOpenOptions{
+			DetectDotGit:          true,
+			EnableDotGitCommonDir: true,
+		},
+	)
+	if err != nil {
+		return "", err
+	}
+
+	remote, err := repo.Remote(remoteName)
+	if err != nil {
+		return "", err
+	}
+
+	if len(remote.Config().URLs) < 1 {
+		return "", fmt.Errorf("remote '%s' exists but has no URL", remoteName)
+	}
+
+	return remote.Config().URLs[0], nil
+}
+
+func findGitSlug(url, githubInstance string) (string, string, error) { //nolint:unparam // pre-existing issue from nektos/act
+	if matches := codeCommitHTTPRegex.FindStringSubmatch(url); matches != nil {
+		return "CodeCommit", matches[2], nil
+	} else if matches := codeCommitSSHRegex.FindStringSubmatch(url); matches != nil {
+		return "CodeCommit", matches[2], nil
+	} else if matches := githubHTTPRegex.FindStringSubmatch(url); matches != nil {
+		return "GitHub", fmt.Sprintf("%s/%s", matches[1], matches[2]), nil
+	} else if matches := githubSSHRegex.FindStringSubmatch(url); matches != nil {
+		return "GitHub", fmt.Sprintf("%s/%s", matches[1], matches[2]), nil
+	} else if githubInstance != "github.com" {
+		gheHTTPRegex := regexp.MustCompile(fmt.Sprintf(`^https?://%s/(.+)/(.+?)(?:.git)?$`, githubInstance))
+		gheSSHRegex := regexp.MustCompile(githubInstance + "[:/](.+)/(.+?)(?:.git)?$")
+		if matches := gheHTTPRegex.FindStringSubmatch(url); matches != nil {
+			return "GitHubEnterprise", fmt.Sprintf("%s/%s", matches[1], matches[2]), nil
+		} else if matches := gheSSHRegex.FindStringSubmatch(url); matches != nil {
+			return "GitHubEnterprise", fmt.Sprintf("%s/%s", matches[1], matches[2]), nil
+		}
+	}
+	return "", url, nil
+}
+
+// NewGitCloneExecutorInput the input for the NewGitCloneExecutor
+type NewGitCloneExecutorInput struct {
+	URL         string
+	Ref         string
+	Dir         string
+	Token       string
+	OfflineMode bool
+
+	// Depth limits the clone/fetch to the given number of commits from the tip of the requested ref.
+	// 0 for full clone.
+	Depth int
+
+	// Quiet drops the informational clone line to debug level, for callers that log their own
+	// download summary (the setup section's action report).
+	Quiet bool
+
+	// For Gitea
+	InsecureSkipTLS bool
+}
+
+// CloneIfRequired returns the repository and a boolean indicating whether an existing local clone was reused.
+func CloneIfRequired(ctx context.Context, refName plumbing.ReferenceName, input NewGitCloneExecutorInput, logger log.FieldLogger) (*git.Repository, bool, error) {
+	r, err := git.PlainOpen(input.Dir)
+	if err == nil {
+		// Verify the cached clone still points to the resolved URL before reusing it.
+		remote, err := r.Remote("origin")
+		if err == nil && len(remote.Config().URLs) > 0 && remote.Config().URLs[0] == input.URL {
+			// Reuse existing clone
+			return r, true, nil
+		}
+
+		if err != nil {
+			logger.Debugf("Removing cached clone at %s because origin cannot be read: %v", input.Dir, err)
+		} else if len(remote.Config().URLs) == 0 {
+			logger.Debugf("Removing cached clone at %s because origin has no URL", input.Dir)
+		} else {
+			logger.Debugf("Removing cached clone at %s because origin URL changed from %s to %s", input.Dir, remote.Config().URLs[0], input.URL)
+		}
+		if err := os.RemoveAll(input.Dir); err != nil {
+			return nil, false, fmt.Errorf("remove cached clone %s: %w", input.Dir, err)
+		}
+	}
+
+	var progressWriter io.Writer
+	if isatty.IsTerminal(os.Stdout.Fd()) || isatty.IsCygwinTerminal(os.Stdout.Fd()) {
+		if entry, ok := logger.(*log.Entry); ok {
+			progressWriter = entry.WriterLevel(log.DebugLevel)
+		} else if lgr, ok := logger.(*log.Logger); ok {
+			progressWriter = lgr.WriterLevel(log.DebugLevel)
+		} else {
+			log.Errorf("Unable to get writer from logger (type=%T)", logger)
+			progressWriter = os.Stdout
+		}
+	}
+
+	cloneOptions := git.CloneOptions{
+		URL:      input.URL,
+		Progress: progressWriter,
+
+		InsecureSkipTLS: input.InsecureSkipTLS, // For Gitea
+	}
+	if input.Token != "" {
+		cloneOptions.Auth = &http.BasicAuth{
+			Username: "token",
+			Password: input.Token,
+		}
+	}
+
+	r, err = cloneAtDepth(ctx, input, cloneOptions, logger)
+	if err != nil {
+		logger.Errorf("Unable to clone %v %s: %v", input.URL, refName, err)
+		return nil, false, err
+	}
+
+	if err = os.Chmod(input.Dir, 0o755); err != nil {
+		return nil, false, err
+	}
+
+	return r, false, nil
+}
+
+func gitOptions(token string) (fetchOptions git.FetchOptions, pullOptions git.PullOptions) {
+	fetchOptions.RefSpecs = []config.RefSpec{"refs/*:refs/*", "HEAD:refs/heads/HEAD"}
+	fetchOptions.Force = true
+	pullOptions.Force = true
+
+	if token != "" {
+		auth := &http.BasicAuth{
+			Username: "token",
+			Password: token,
+		}
+		fetchOptions.Auth = auth
+		pullOptions.Auth = auth
+	}
+
+	return fetchOptions, pullOptions
+}
+
+// NewGitCloneExecutor creates an executor to clone git repos
+func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
+	return func(ctx context.Context) error {
+		logger := common.Logger(ctx)
+		if input.Quiet {
+			logger.Debugf("git clone '%s' # ref=%s", input.URL, input.Ref)
+		} else {
+			logger.Infof("git clone '%s' # ref=%s", input.URL, input.Ref)
+		}
+		logger.Debugf("  cloning %s to %s", input.URL, input.Dir)
+
+		defer AcquireCloneLock(input.Dir)()
+
+		refName := plumbing.ReferenceName("refs/heads/" + input.Ref)
+		r, reused, err := CloneIfRequired(ctx, refName, input, logger)
+		if err != nil {
+			return err
+		}
+
+		isOfflineMode := input.OfflineMode
+
+		// fetch latest changes
+		fetchOptions, pullOptions := gitOptions(input.Token)
+
+		if input.InsecureSkipTLS { // For Gitea
+			fetchOptions.InsecureSkipTLS = true
+			pullOptions.InsecureSkipTLS = true
+		}
+
+		// Action clones only ever need the tip commit, so keep a shallow cache cheap on update at depth 1 regardless of its original depth
+		// Turning action_shallow_clone off does not convert an existing shallow cache; evict it for a full clone.
+		shallow := isShallow(r)
+		if shallow {
+			fetchOptions.Depth = 1
+			if spec, ok := shallowFetchRefSpec(r, input.Ref); ok {
+				fetchOptions.RefSpecs = []config.RefSpec{spec}
+			}
+		}
+
+		if !isOfflineMode {
+			err = r.Fetch(&fetchOptions)
+			if err != nil && !errors.Is(err, git.NoErrAlreadyUpToDate) {
+				return err
+			}
+		}
+
+		var hash *plumbing.Hash
+		rev := plumbing.Revision(input.Ref)
+		if hash, err = r.ResolveRevision(rev); err != nil {
+			// ResolveRevision returns a nil hash on error, and a branch ref legitimately fails
+			// here (no local refs/heads/<ref>); the duck-typing below resolves it.
+			logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
+		} else if hash.String() != input.Ref && strings.HasPrefix(hash.String(), input.Ref) {
+			return &Error{
+				err:    ErrShortRef,
+				commit: hash.String(),
+			}
+		}
+
+		// At this point we need to know if it's a tag or a branch
+		// And the easiest way to do it is duck typing
+		//
+		// If err is nil, it's a tag so let's proceed with that hash like we would if
+		// it was a sha
+		refType := "tag"
+		rev = plumbing.Revision(path.Join("refs", "tags", input.Ref))
+		if _, err := r.Tag(input.Ref); errors.Is(err, git.ErrTagNotFound) {
+			rName := plumbing.ReferenceName(path.Join("refs", "remotes", "origin", input.Ref))
+			if _, err := r.Reference(rName, false); errors.Is(err, plumbing.ErrReferenceNotFound) {
+				refType = "sha"
+				rev = plumbing.Revision(input.Ref)
+			} else {
+				refType = "branch"
+				rev = plumbing.Revision(rName)
+			}
+		}
+
+		if hash, err = r.ResolveRevision(rev); err != nil {
+			logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
+			return err
+		}
+
+		var w *git.Worktree
+		if w, err = r.Worktree(); err != nil {
+			return err
+		}
+
+		// If the hash resolved doesn't match the ref provided in a workflow then we're
+		// using a branch or tag ref, not a sha
+		//
+		// Repos on disk point to commit hashes, and need to checkout input.Ref before
+		// we try and pull down any changes
+		if hash.String() != input.Ref && refType == "branch" {
+			logger.Debugf("Provided ref is not a sha. Checking out branch before pulling changes")
+			sourceRef := plumbing.ReferenceName(path.Join("refs", "remotes", "origin", input.Ref))
+			if err = w.Checkout(&git.CheckoutOptions{
+				Branch: sourceRef,
+				Force:  true,
+			}); err != nil {
+				logger.Errorf("Unable to checkout %s: %v", sourceRef, err)
+				return err
+			}
+		}
+
+		reusedMsg := ""
+
+		switch {
+		case !isOfflineMode && !shallow:
+			// In shallow mode the depth-limited fetch above already advanced the ref.
+			if err = w.Pull(&pullOptions); err != nil && err != git.NoErrAlreadyUpToDate {
+				logger.Debugf("Unable to pull %s: %v", refName, err)
+			}
+		case isOfflineMode && reused:
+			reusedMsg = " (reused in offline mode)"
+		}
+
+		logger.Debugf("Cloned %s to %s%s", input.URL, input.Dir, reusedMsg)
+
+		if hash.String() != input.Ref && refType == "branch" {
+			logger.Debugf("Provided ref is not a sha. Updating branch ref after pull")
+			if hash, err = r.ResolveRevision(rev); err != nil {
+				logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
+				return err
+			}
+		}
+		if err = w.Checkout(&git.CheckoutOptions{
+			Hash:  *hash,
+			Force: true,
+		}); err != nil {
+			logger.Errorf("Unable to checkout %s: %v", *hash, err)
+			return err
+		}
+
+		if err = w.Reset(&git.ResetOptions{
+			Mode:   git.HardReset,
+			Commit: *hash,
+		}); err != nil {
+			logger.Errorf("Unable to reset to %s: %v", hash.String(), err)
+			return err
+		}
+
+		logger.Debugf("Checked out %s", input.Ref)
+		return nil
+	}
+}
+
+// cloneAtDepth clones input.URL into input.Dir using opts.
+// With input.Depth > 0 it first tries a shallow, single-branch clone of input.Ref, falling back when error.
+func cloneAtDepth(ctx context.Context, input NewGitCloneExecutorInput, opts git.CloneOptions, logger log.FieldLogger) (*git.Repository, error) {
+	if input.Depth > 0 {
+		for _, refName := range []plumbing.ReferenceName{
+			plumbing.NewBranchReferenceName(input.Ref),
+			plumbing.NewTagReferenceName(input.Ref),
+		} {
+			shallowOpts := opts
+			shallowOpts.Depth = input.Depth
+			shallowOpts.SingleBranch = true
+			shallowOpts.ReferenceName = refName
+			shallowOpts.Tags = git.NoTags
+
+			r, err := git.PlainCloneContext(ctx, input.Dir, false, &shallowOpts)
+			if err == nil {
+				return r, nil
+			}
+			logger.Debugf("Shallow clone of %s as %s failed: %v", input.URL, refName, err)
+			if rmErr := os.RemoveAll(input.Dir); rmErr != nil {
+				return nil, fmt.Errorf("remove partial clone %s: %w", input.Dir, rmErr)
+			}
+		}
+		logger.Debugf("Falling back to a full clone of %s for ref %q", input.URL, input.Ref)
+	}
+
+	return git.PlainCloneContext(ctx, input.Dir, false, &opts)
+}
+
+// isShallow reports whether the local repository was cloned with a limited depth.
+func isShallow(r *git.Repository) bool {
+	shallows, err := r.Storer.Shallow()
+	return err == nil && len(shallows) > 0
+}
+
+// shallowFetchRefSpec returns the single refspec that updates only input.Ref, keeping a shallow clone from re-downloading every branch's history.
+// ok is false when the ref is not present locally as a tag or remote-tracking branch, in which case the broad default refspec is used.
+func shallowFetchRefSpec(r *git.Repository, ref string) (config.RefSpec, bool) {
+	tagRef := plumbing.NewTagReferenceName(ref)
+	if _, err := r.Reference(tagRef, false); err == nil {
+		return config.RefSpec(fmt.Sprintf("+%s:%s", tagRef, tagRef)), true
+	}
+	remoteRef := plumbing.NewRemoteReferenceName("origin", ref)
+	if _, err := r.Reference(remoteRef, false); err == nil {
+		branchRef := plumbing.NewBranchReferenceName(ref)
+		return config.RefSpec(fmt.Sprintf("+%s:%s", branchRef, remoteRef)), true
+	}
+	return "", false
+}

internal/act/common/git/git_test.go

@@ -0,0 +1,612 @@
+// Copyright 2022 The Gitea Authors. All rights reserved.
+// Copyright 2022 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package git
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+
+	"gitea.com/gitea/runner/internal/act/common"
+
+	log "github.com/sirupsen/logrus"
+	logrustest "github.com/sirupsen/logrus/hooks/test"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestFindGitSlug(t *testing.T) {
+	assert := assert.New(t)
+
+	slugTests := []struct {
+		url      string // input
+		provider string // expected result
+		slug     string // expected result
+	}{
+		{"https://git-codecommit.us-east-1.amazonaws.com/v1/repos/my-repo-name", "CodeCommit", "my-repo-name"},
+		{"ssh://git-codecommit.us-west-2.amazonaws.com/v1/repos/my-repo", "CodeCommit", "my-repo"},
+		{"[email protected]:nektos/act.git", "GitHub", "nektos/act"},
+		{"[email protected]:nektos/act", "GitHub", "nektos/act"},
+		{"https://github.com/nektos/act.git", "GitHub", "nektos/act"},
+		{"http://github.com/nektos/act.git", "GitHub", "nektos/act"},
+		{"https://github.com/nektos/act", "GitHub", "nektos/act"},
+		{"http://github.com/nektos/act", "GitHub", "nektos/act"},
+		{"git+ssh://[email protected]/owner/repo.git", "GitHub", "owner/repo"},
+		{"http://myotherrepo.com/act.git", "", "http://myotherrepo.com/act.git"},
+	}
+
+	for _, tt := range slugTests {
+		provider, slug, err := findGitSlug(tt.url, "github.com")
+
+		assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+		assert.Equal(tt.provider, provider)
+		assert.Equal(tt.slug, slug)
+	}
+}
+
+func TestErrorWrapsCommitAndCause(t *testing.T) {
+	err := &Error{err: ErrShortRef, commit: "abc123"}
+	require.Equal(t, ErrShortRef.Error(), err.Error())
+	require.ErrorIs(t, err, ErrShortRef)
+	require.Equal(t, "abc123", err.Commit())
+}
+
+func cleanGitHooks(dir string) error {
+	hooksDir := filepath.Join(dir, ".git", "hooks")
+	files, err := os.ReadDir(hooksDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	for _, f := range files {
+		if f.IsDir() {
+			continue
+		}
+		relName := filepath.Join(hooksDir, f.Name())
+		if err := os.Remove(relName); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func TestFindGitRemoteURL(t *testing.T) {
+	assert := assert.New(t)
+
+	basedir := t.TempDir()
+	err := gitCmd("init", basedir)
+	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	err = cleanGitHooks(basedir)
+	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+
+	remoteURL := "https://git-codecommit.us-east-1.amazonaws.com/v1/repos/my-repo-name"
+	err = gitCmd("-C", basedir, "remote", "add", "origin", remoteURL)
+	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+
+	u, err := findGitRemoteURL(context.Background(), basedir, "origin")
+	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	assert.Equal(remoteURL, u)
+
+	remoteURL = "[email protected]/AwesomeOwner/MyAwesomeRepo.git"
+	err = gitCmd("-C", basedir, "remote", "add", "upstream", remoteURL)
+	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	u, err = findGitRemoteURL(context.Background(), basedir, "upstream")
+	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	assert.Equal(remoteURL, u)
+}
+
+func TestFindGithubRepoUsesOriginAndCustomRemote(t *testing.T) {
+	basedir := t.TempDir()
+	require.NoError(t, gitCmd("init", basedir))
+	require.NoError(t, cleanGitHooks(basedir))
+	require.NoError(t, gitCmd("-C", basedir, "remote", "add", "origin", "https://github.com/owner/repo.git"))
+	require.NoError(t, gitCmd("-C", basedir, "remote", "add", "ghe", "[email protected]:team/project.git"))
+
+	slug, err := FindGithubRepo(context.Background(), basedir, "github.com", "")
+	require.NoError(t, err)
+	require.Equal(t, "owner/repo", slug)
+
+	slug, err = FindGithubRepo(context.Background(), basedir, "git.example.com", "ghe")
+	require.NoError(t, err)
+	require.Equal(t, "team/project", slug)
+}
+
+func TestGitFindRef(t *testing.T) {
+	basedir := t.TempDir()
+
+	for name, tt := range map[string]struct {
+		Prepare func(t *testing.T, dir string)
+		Assert  func(t *testing.T, ref string, err error)
+	}{
+		"new_repo": {
+			Prepare: func(t *testing.T, dir string) {},
+			Assert: func(t *testing.T, ref string, err error) {
+				require.Error(t, err)
+			},
+		},
+		"new_repo_with_commit": {
+			Prepare: func(t *testing.T, dir string) {
+				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "msg"))
+			},
+			Assert: func(t *testing.T, ref string, err error) {
+				require.NoError(t, err)
+				require.Equal(t, "refs/heads/master", ref)
+			},
+		},
+		"current_head_is_tag": {
+			Prepare: func(t *testing.T, dir string) {
+				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "commit msg"))
+				require.NoError(t, gitCmd("-C", dir, "tag", "v1.2.3"))
+				require.NoError(t, gitCmd("-C", dir, "checkout", "v1.2.3"))
+			},
+			Assert: func(t *testing.T, ref string, err error) {
+				require.NoError(t, err)
+				require.Equal(t, "refs/tags/v1.2.3", ref)
+			},
+		},
+		"current_head_is_same_as_tag": {
+			Prepare: func(t *testing.T, dir string) {
+				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "1.4.2 release"))
+				require.NoError(t, gitCmd("-C", dir, "tag", "v1.4.2"))
+			},
+			Assert: func(t *testing.T, ref string, err error) {
+				require.NoError(t, err)
+				require.Equal(t, "refs/tags/v1.4.2", ref)
+			},
+		},
+		"current_head_is_not_tag": {
+			Prepare: func(t *testing.T, dir string) {
+				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "msg"))
+				require.NoError(t, gitCmd("-C", dir, "tag", "v1.4.2"))
+				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "msg2"))
+			},
+			Assert: func(t *testing.T, ref string, err error) {
+				require.NoError(t, err)
+				require.Equal(t, "refs/heads/master", ref)
+			},
+		},
+		"current_head_is_another_branch": {
+			Prepare: func(t *testing.T, dir string) {
+				require.NoError(t, gitCmd("-C", dir, "checkout", "-b", "mybranch"))
+				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "msg"))
+			},
+			Assert: func(t *testing.T, ref string, err error) {
+				require.NoError(t, err)
+				require.Equal(t, "refs/heads/mybranch", ref)
+			},
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			dir := filepath.Join(basedir, name)
+			require.NoError(t, os.MkdirAll(dir, 0o755))
+			require.NoError(t, gitCmd("-C", dir, "init", "--initial-branch=master"))
+			require.NoError(t, cleanGitHooks(dir))
+			tt.Prepare(t, dir)
+			ref, err := FindGitRef(context.Background(), dir)
+			tt.Assert(t, ref, err)
+		})
+	}
+}
+
+func TestGitCloneExecutor(t *testing.T) {
+	// Build a local bare "remote" so this runs offline and fast. The cases below mirror
+	// the tag/branch/sha/short-sha ref paths the executor handles, formerly exercised by
+	// cloning actions/checkout and anchore/scan-action over the network.
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "initial"))
+	require.NoError(t, gitCmd("-C", workDir, "tag", "v2"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "v2"))
+
+	// A branch with a dash in the name (mirrors the historical scan-action@act-fails case).
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "act-fails"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "branch-commit"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "act-fails"))
+
+	out, err := exec.Command("git", "-C", workDir, "rev-parse", "main").Output()
+	require.NoError(t, err)
+	fullSha := strings.TrimSpace(string(out))
+
+	for name, tt := range map[string]struct {
+		Err error
+		Ref string
+	}{
+		"tag": {
+			Err: nil,
+			Ref: "v2",
+		},
+		"branch": {
+			Err: nil,
+			Ref: "act-fails",
+		},
+		"sha": {
+			Err: nil,
+			Ref: fullSha,
+		},
+		"short-sha": {
+			Err: &Error{ErrShortRef, fullSha},
+			Ref: fullSha[:7],
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: remoteDir,
+				Ref: tt.Ref,
+				Dir: t.TempDir(),
+			})
+
+			err := clone(context.Background())
+			if tt.Err != nil {
+				assert.Error(t, err) //nolint:testifylint // pre-existing issue from nektos/act
+				assert.Equal(t, tt.Err, err)
+			} else {
+				assert.Empty(t, err) //nolint:testifylint // pre-existing issue from nektos/act
+			}
+		})
+	}
+}
+
+func TestGitCloneExecutorReclonesWhenOriginURLChanges(t *testing.T) {
+	createRemote := func(message string) string {
+		remoteDir := t.TempDir()
+		require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+
+		workDir := t.TempDir()
+		require.NoError(t, gitCmd("clone", remoteDir, workDir))
+		require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", message))
+		require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+
+		return remoteDir
+	}
+
+	oldRemoteDir := createRemote("old-action")
+	newRemoteDir := createRemote("new-action")
+	cacheDir := t.TempDir()
+
+	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+		URL: oldRemoteDir,
+		Ref: "main",
+		Dir: cacheDir,
+	})(t.Context()))
+
+	markerPath := filepath.Join(cacheDir, "stale-marker")
+	require.NoError(t, os.WriteFile(markerPath, []byte("stale"), 0o644))
+
+	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+		URL: newRemoteDir,
+		Ref: "main",
+		Dir: cacheDir,
+	})(t.Context()))
+
+	originURL, err := findGitRemoteURL(t.Context(), cacheDir, "origin")
+	require.NoError(t, err)
+	assert.Equal(t, newRemoteDir, originURL)
+
+	out, err := exec.Command("git", "-C", cacheDir, "log", "--oneline", "-1", "--format=%s").Output()
+	require.NoError(t, err)
+	assert.Equal(t, "new-action", strings.TrimSpace(string(out)))
+
+	_, err = os.Stat(markerPath)
+	require.True(t, os.IsNotExist(err), "stale cached directory should be removed before recloning")
+}
+
+func TestGitCloneExecutorNonFastForwardRef(t *testing.T) {
+	// Simulate the scenario where a remote ref (e.g. a GitHub PR head ref) changes
+	// non-fast-forward between two fetches. Before the fix, the fetch used Force=false,
+	// causing go-git to return ErrForceNeeded and short-circuit the checkout.
+
+	// Create a bare "remote" repo with an initial commit on main and a feature branch.
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+
+	// We need a working clone to push commits from.
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "initial"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+
+	// Create a feature branch (simulates refs/pull/N/head).
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "feature"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "feature-1"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "feature"))
+
+	// First clone via the executor — should succeed and cache the repo.
+	cloneDir := t.TempDir()
+	clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
+		URL: remoteDir,
+		Ref: "main",
+		Dir: cloneDir,
+	})
+	require.NoError(t, clone(context.Background()))
+
+	// Now force-push the feature branch to a non-fast-forward commit (simulates
+	// a PR rebase). This makes refs/heads/feature non-fast-forward.
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "branch", "-D", "feature"))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "feature"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "feature-rewritten"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "--force", "origin", "feature"))
+
+	// Also advance main so we can verify the clone picks up the new commit.
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "second"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "main"))
+
+	// Second clone to the same directory — before the fix this returned ErrForceNeeded
+	// and left the working tree at the old commit.
+	err := clone(context.Background())
+	require.NoError(t, err, "fetch with non-fast-forward refs must not fail when Force=true")
+
+	// Verify the working tree was actually updated to the latest main commit.
+	out, err := exec.Command("git", "-C", cloneDir, "log", "--oneline", "-1", "--format=%s").Output()
+	require.NoError(t, err)
+	assert.Equal(t, "second", strings.TrimSpace(string(out)), "working tree should be at the latest commit")
+}
+
+func TestGitCloneExecutorOfflineMode(t *testing.T) {
+	// Build a local "remote" with a single commit on main.
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "initial"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+
+	// Prime the cache with an online clone of main.
+	cacheDir := t.TempDir()
+	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+		URL: remoteDir,
+		Ref: "main",
+		Dir: cacheDir,
+	})(context.Background()))
+
+	t.Run("cached branch resolves without fetching", func(t *testing.T) {
+		// Offline reuse of a cached branch must succeed even though ResolveRevision(input.Ref)
+		// finds no local refs/heads/<ref>.
+		err := NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL:         remoteDir,
+			Ref:         "main",
+			Dir:         cacheDir,
+			OfflineMode: true,
+		})(context.Background())
+		require.NoError(t, err)
+
+		out, err := exec.Command("git", "-C", cacheDir, "log", "--oneline", "-1", "--format=%s").Output()
+		require.NoError(t, err)
+		assert.Equal(t, "initial", strings.TrimSpace(string(out)))
+	})
+
+	t.Run("unresolvable cached ref returns error", func(t *testing.T) {
+		// The ref was never cached; offline mode cannot resolve it and must return an error.
+		err := NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL:         remoteDir,
+			Ref:         "never-fetched",
+			Dir:         cacheDir,
+			OfflineMode: true,
+		})(context.Background())
+		require.Error(t, err)
+	})
+}
+
+func TestGitCloneExecutorQuietDemotesCloneLine(t *testing.T) {
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "initial"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+
+	// Quiet callers report the download themselves, so the clone line must not reach the job log.
+	for name, quiet := range map[string]bool{"quiet": true, "not quiet": false} {
+		t.Run(name, func(t *testing.T) {
+			logger, hook := logrustest.NewNullLogger()
+			logger.SetLevel(log.InfoLevel)
+			ctx := common.WithLogger(context.Background(), logger.WithField("job", "j1"))
+
+			require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL:   remoteDir,
+				Ref:   "main",
+				Dir:   t.TempDir(),
+				Quiet: quiet,
+			})(ctx))
+
+			var cloneLines int
+			for _, entry := range hook.AllEntries() {
+				if strings.HasPrefix(entry.Message, "git clone ") {
+					cloneLines++
+				}
+			}
+			if quiet {
+				assert.Zero(t, cloneLines)
+			} else {
+				assert.Equal(t, 1, cloneLines)
+			}
+		})
+	}
+}
+
+func TestGitCloneExecutorShallow(t *testing.T) {
+	// Build a local "remote" with several commits on main plus a tag, so a full clone would pull noticeably more history than a shallow one.
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	for _, m := range []string{"c1", "c2", "c3"} {
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", m))
+	}
+	require.NoError(t, gitCmd("-C", workDir, "tag", "v1"))
+	sha := gitRevParse(t, workDir, "HEAD~1") // c2, a SHA that go-git cannot shallow-clone
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "v1"))
+
+	shallowMarker := func(dir string) string { return filepath.Join(dir, ".git", "shallow") }
+
+	t.Run("branch is cloned shallowly", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.FileExists(t, shallowMarker(dir), "clone should be shallow")
+		assert.Equal(t, 1, gitRevCount(t, dir), "only the tip commit should be present")
+		assert.Equal(t, "c3", gitHeadSubject(t, dir))
+	})
+
+	t.Run("tag is cloned shallowly", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "v1", Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.FileExists(t, shallowMarker(dir), "clone should be shallow")
+		assert.Equal(t, 1, gitRevCount(t, dir))
+		assert.Equal(t, "c3", gitHeadSubject(t, dir))
+	})
+
+	t.Run("SHA falls back to a full clone", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: sha, Dir: dir, Depth: 1,
+		})(t.Context()))
+		// go-git cannot shallow-clone a raw SHA, so it falls back to a full clone; the absence of a shallow marker proves the fallback happened.
+		assert.NoFileExists(t, shallowMarker(dir), "a SHA ref must not produce a shallow clone")
+		assert.Equal(t, sha, gitRevParse(t, dir, "HEAD"))
+	})
+
+	t.Run("moving branch updates while staying shallow", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
+		})(t.Context()))
+		require.Equal(t, "c3", gitHeadSubject(t, dir))
+
+		// Advance main on the remote, then reuse the existing shallow clone.
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "c4"))
+		require.NoError(t, gitCmd("-C", workDir, "push", "origin", "main"))
+
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.Equal(t, "c4", gitHeadSubject(t, dir), "reused shallow clone should update to the new tip")
+		assert.FileExists(t, shallowMarker(dir), "repo should remain shallow after update")
+		assert.Equal(t, 1, gitRevCount(t, dir))
+	})
+}
+
+func gitRevParse(t *testing.T, dir, rev string) string {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "rev-parse", rev).Output()
+	require.NoError(t, err)
+	return strings.TrimSpace(string(out))
+}
+
+func gitRevCount(t *testing.T, dir string) int {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "rev-list", "--count", "HEAD").Output()
+	require.NoError(t, err)
+	n, err := strconv.Atoi(strings.TrimSpace(string(out)))
+	require.NoError(t, err)
+	return n
+}
+
+func gitHeadSubject(t *testing.T, dir string) string {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "log", "-1", "--format=%s").Output()
+	require.NoError(t, err)
+	return strings.TrimSpace(string(out))
+}
+
+func gitCmd(args ...string) error {
+	cmd := exec.Command("git", args...)
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	// Inject a deterministic identity and ignore the host's global/system config so commits
+	// succeed regardless of the host having no user.name/user.email (e.g. CI, GITHUB_ACTIONS
+	// unset) or a global commit.gpgsign, and without mutating the developer's ~/.gitconfig.
+	cmd.Env = append(os.Environ(),
+		"GIT_AUTHOR_NAME=Unit Test",
+		"[email protected]",
+		"GIT_COMMITTER_NAME=Unit Test",
+		"[email protected]",
+		"GIT_CONFIG_GLOBAL=/dev/null",
+		"GIT_CONFIG_SYSTEM=/dev/null",
+	)
+
+	err := cmd.Run()
+	if exitError, ok := err.(*exec.ExitError); ok {
+		if waitStatus, ok := exitError.Sys().(syscall.WaitStatus); ok {
+			return fmt.Errorf("Exit error %d", waitStatus.ExitStatus())
+		}
+		return exitError
+	}
+	return nil
+}
+
+func TestAcquireCloneLock(t *testing.T) {
+	t.Run("same directory serializes", func(t *testing.T) {
+		dir := t.TempDir()
+
+		unlock1 := AcquireCloneLock(dir)
+
+		secondAcquired := make(chan struct{})
+		go func() {
+			unlock := AcquireCloneLock(dir)
+			close(secondAcquired)
+			unlock()
+		}()
+
+		select {
+		case <-secondAcquired:
+			t.Fatal("second acquire should block while first holds the lock")
+		case <-time.After(50 * time.Millisecond):
+		}
+
+		unlock1()
+
+		select {
+		case <-secondAcquired:
+		case <-time.After(time.Second):
+			t.Fatal("second acquire should proceed after first releases the lock")
+		}
+	})
+
+	t.Run("different directories do not block", func(t *testing.T) {
+		dirA := t.TempDir()
+		dirB := t.TempDir()
+
+		unlockA := AcquireCloneLock(dirA)
+		defer unlockA()
+
+		done := make(chan struct{})
+		go func() {
+			unlock := AcquireCloneLock(dirB)
+			unlock()
+			close(done)
+		}()
+
+		select {
+		case <-done:
+		case <-time.After(time.Second):
+			t.Fatal("acquire on a different directory must not block")
+		}
+	})
+}

internal/act/common/job_error.go

@@ -0,0 +1,36 @@
+// Copyright 2021 The Gitea Authors. All rights reserved.
+// Copyright 2021 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+)
+
+type jobErrorContextKey string
+
+const jobErrorContextKeyVal = jobErrorContextKey("job.error")
+
+// JobError returns the job error for current context if any
+func JobError(ctx context.Context) error {
+	val := ctx.Value(jobErrorContextKeyVal)
+	if val != nil {
+		if container, ok := val.(map[string]error); ok {
+			return container["error"]
+		}
+	}
+	return nil
+}
+
+func SetJobError(ctx context.Context, err error) {
+	if container, ok := ctx.Value(jobErrorContextKeyVal).(map[string]error); ok {
+		container["error"] = err
+	}
+}
+
+// WithJobErrorContainer adds a value to the context as a container for an error
+func WithJobErrorContainer(ctx context.Context) context.Context {
+	container := map[string]error{}
+	return context.WithValue(ctx, jobErrorContextKeyVal, container)
+}

internal/act/common/line_writer.go

@@ -0,0 +1,80 @@
+// Copyright 2020 The Gitea Authors. All rights reserved.
+// Copyright 2020 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"bytes"
+	"io"
+)
+
+// LineHandler is a callback function for handling a line
+type LineHandler func(line string) bool
+
+// Flusher is implemented by writers that buffer a trailing, not-yet-terminated
+// line. Callers should flush once the underlying stream has reached EOF so the
+// final line (when it is not newline-terminated) is not lost.
+type Flusher interface {
+	Flush()
+}
+
+type lineWriter struct {
+	buffer   bytes.Buffer
+	handlers []LineHandler
+}
+
+// NewLineWriter creates a new instance of a line writer
+func NewLineWriter(handlers ...LineHandler) io.Writer {
+	w := new(lineWriter)
+	w.handlers = handlers
+	return w
+}
+
+// FlushWriter flushes w if it implements Flusher. It is a no-op otherwise, so
+// callers can flush an io.Writer without knowing its concrete type.
+func FlushWriter(w io.Writer) {
+	if f, ok := w.(Flusher); ok {
+		f.Flush()
+	}
+}
+
+func (lw *lineWriter) Write(p []byte) (n int, err error) {
+	pBuf := bytes.NewBuffer(p)
+	written := 0
+	for {
+		line, err := pBuf.ReadString('\n')
+		w, _ := lw.buffer.WriteString(line)
+		written += w
+		if err == nil {
+			lw.handleLine(lw.buffer.String())
+			lw.buffer.Reset()
+		} else if err == io.EOF {
+			break
+		} else {
+			return written, err
+		}
+	}
+
+	return written, nil
+}
+
+// Flush emits any buffered, not-yet-newline-terminated content as a final line.
+// It is safe to call multiple times; subsequent calls with an empty buffer are
+// no-ops.
+func (lw *lineWriter) Flush() {
+	if lw.buffer.Len() == 0 {
+		return
+	}
+	lw.handleLine(lw.buffer.String())
+	lw.buffer.Reset()
+}
+
+func (lw *lineWriter) handleLine(line string) {
+	for _, h := range lw.handlers {
+		ok := h(line)
+		if !ok {
+			break
+		}
+	}
+}

internal/act/common/line_writer_test.go

@@ -0,0 +1,72 @@
+// Copyright 2020 The Gitea Authors. All rights reserved.
+// Copyright 2020 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"io"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestLineWriter(t *testing.T) {
+	lines := make([]string, 0)
+	lineHandler := func(s string) bool {
+		lines = append(lines, s)
+		return true
+	}
+
+	lineWriter := NewLineWriter(lineHandler)
+
+	assert := assert.New(t)
+	write := func(s string) {
+		n, err := lineWriter.Write([]byte(s))
+		assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+		assert.Equal(len(s), n, s)
+	}
+
+	write("hello")
+	write(" ")
+	write("world!!\nextra")
+	write(" line\n and another\nlast")
+	write(" line\n")
+	write("no newline here...")
+
+	assert.Len(lines, 4)
+	assert.Equal("hello world!!\n", lines[0])
+	assert.Equal("extra line\n", lines[1])
+	assert.Equal(" and another\n", lines[2])
+	assert.Equal("last line\n", lines[3])
+}
+
+func TestLineWriterFlush(t *testing.T) {
+	lines := make([]string, 0)
+	lineHandler := func(s string) bool {
+		lines = append(lines, s)
+		return true
+	}
+
+	lineWriter := NewLineWriter(lineHandler)
+
+	assert := assert.New(t)
+	_, err := lineWriter.Write([]byte("complete line\npartial line without newline"))
+	assert.NoError(err) //nolint:testifylint // pre-existing pattern from nektos/act
+
+	// Only the newline-terminated line is emitted before flushing.
+	assert.Equal([]string{"complete line\n"}, lines)
+
+	// Flushing emits the buffered, not-yet-terminated trailing line.
+	FlushWriter(lineWriter)
+	assert.Equal([]string{"complete line\n", "partial line without newline"}, lines)
+
+	// Flushing again is a no-op: nothing is buffered.
+	FlushWriter(lineWriter)
+	assert.Len(lines, 2)
+}
+
+func TestFlushWriterIgnoresNonFlusher(t *testing.T) {
+	// FlushWriter must be a safe no-op for writers that do not buffer lines.
+	assert.NotPanics(t, func() { FlushWriter(io.Discard) })
+}

internal/act/common/logger.go

@@ -0,0 +1,52 @@
+// Copyright 2022 The Gitea Authors. All rights reserved.
+// Copyright 2020 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+
+	"github.com/sirupsen/logrus"
+)
+
+type loggerContextKey string
+
+const loggerContextKeyVal = loggerContextKey("logrus.FieldLogger")
+
+// Logger returns the appropriate logger for current context
+func Logger(ctx context.Context) logrus.FieldLogger {
+	val := ctx.Value(loggerContextKeyVal)
+	if val != nil {
+		if logger, ok := val.(logrus.FieldLogger); ok {
+			return logger
+		}
+	}
+	return logrus.StandardLogger()
+}
+
+// WithLogger adds a value to the context for the logger
+func WithLogger(ctx context.Context, logger logrus.FieldLogger) context.Context {
+	return context.WithValue(ctx, loggerContextKeyVal, logger)
+}
+
+type loggerHookKey string
+
+const loggerHookKeyVal = loggerHookKey("logrus.Hook")
+
+// LoggerHook returns the appropriate logger hook for current context
+// the hook affects job logger, not global logger
+func LoggerHook(ctx context.Context) logrus.Hook {
+	val := ctx.Value(loggerHookKeyVal)
+	if val != nil {
+		if hook, ok := val.(logrus.Hook); ok {
+			return hook
+		}
+	}
+	return nil
+}
+
+// WithLoggerHook adds a value to the context for the logger hook
+func WithLoggerHook(ctx context.Context, hook logrus.Hook) context.Context {
+	return context.WithValue(ctx, loggerHookKeyVal, hook)
+}

internal/act/common/outbound_ip.go

@@ -0,0 +1,81 @@
+// Copyright 2023 The Gitea Authors. All rights reserved.
+// Copyright 2021 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"net"
+	"sort"
+	"strings"
+)
+
+// GetOutboundIP returns an outbound IP address of this machine.
+// It tries to access the internet and returns the local IP address of the connection.
+// If the machine cannot access the internet, it returns a preferred IP address from network interfaces.
+// It returns nil if no IP address is found.
+func GetOutboundIP() net.IP {
+	// See https://stackoverflow.com/a/37382208
+	conn, err := net.Dial("udp", "8.8.8.8:80")
+	if err == nil {
+		defer conn.Close()
+		if addr, ok := conn.LocalAddr().(*net.UDPAddr); ok {
+			return addr.IP
+		}
+	}
+
+	// So the machine cannot access the internet. Pick an IP address from network interfaces.
+	if ifs, err := net.Interfaces(); err == nil {
+		type IP struct {
+			net.IP
+			net.Interface
+		}
+		var ips []IP
+		for _, i := range ifs {
+			if addrs, err := i.Addrs(); err == nil {
+				for _, addr := range addrs {
+					var ip net.IP
+					switch v := addr.(type) {
+					case *net.IPNet:
+						ip = v.IP
+					case *net.IPAddr:
+						ip = v.IP
+					}
+					if ip.IsGlobalUnicast() {
+						ips = append(ips, IP{ip, i})
+					}
+				}
+			}
+		}
+		if len(ips) > 1 {
+			sort.Slice(ips, func(i, j int) bool {
+				ifi := ips[i].Interface
+				ifj := ips[j].Interface
+
+				// ethernet is preferred
+				if vi, vj := strings.HasPrefix(ifi.Name, "e"), strings.HasPrefix(ifj.Name, "e"); vi != vj {
+					return vi
+				}
+
+				ipi := ips[i].IP
+				ipj := ips[j].IP
+
+				// IPv4 is preferred
+				if vi, vj := ipi.To4() != nil, ipj.To4() != nil; vi != vj {
+					return vi
+				}
+
+				// en0 is preferred to en1
+				if ifi.Name != ifj.Name {
+					return ifi.Name < ifj.Name
+				}
+
+				// fallback
+				return ipi.String() < ipj.String()
+			})
+			return ips[0].IP
+		}
+	}
+
+	return nil
+}