Clone different git repos in parallel via per-directory locks (#866)

Old `cloneLock` is a package-level `sync.Mutex` that serialized every action clone across all goroutines, regardless of target directory.
This PR replaces it with a `sync.Map` of per-directory mutexes keyed by `input.Dir`. Same-directory operations still serialize; different directories now clone in parallel.

Reviewed-on: https://gitea.com/gitea/act_runner/pulls/866
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Zettat123 <[email protected]>
Co-committed-by: Zettat123 <[email protected]>

act/artifactcache/model.go

@@ -29,6 +29,7 @@ func (c *Request) ToCache() *Cache {
 
 type Cache struct {
 	ID        uint64 `json:"id" boltholdKey:"ID"`
+	Repo      string `json:"repo" boltholdIndex:"Repo"`
 	Key       string `json:"key" boltholdIndex:"Key"`
 	Version   string `json:"version" boltholdIndex:"Version"`
 	Size      int64  `json:"cacheSize"`

act/common/git/git.go

@@ -32,12 +32,21 @@ var (
 	githubHTTPRegex     = regexp.MustCompile(`^https?://.*github.com.*/(.+)/(.+?)(?:.git)?$`)
 	githubSSHRegex      = regexp.MustCompile(`github.com[:/](.+)/(.+?)(?:.git)?$`)
 
-	cloneLock sync.Mutex
+	cloneLocks sync.Map // key: clone target directory; value: *sync.Mutex
 
 	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 erialized; clones into different directories run in parallel.
+func acquireCloneLock(dir string) func() {
+	v, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
+	mu := v.(*sync.Mutex)
+	mu.Lock()
+	return mu.Unlock
+}
+
 type Error struct {
 	err    error
 	commit string
@@ -301,8 +310,7 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 		logger.Infof("  \u2601  git clone '%s' # ref=%s", input.URL, input.Ref)
 		logger.Debugf("  cloning %s to %s", input.URL, input.Dir)
 
-		cloneLock.Lock()
-		defer cloneLock.Unlock()
+		defer acquireCloneLock(input.Dir)()
 
 		refName := plumbing.ReferenceName("refs/heads/" + input.Ref)
 		r, err := CloneIfRequired(ctx, refName, input, logger)

act/common/git/git_test.go

@@ -11,8 +11,10 @@ import (
 	"os/exec"
 	"path/filepath"
 	"strings"
+	"sync"
 	"syscall"
 	"testing"
+	"time"
 
 	log "github.com/sirupsen/logrus"
 	"github.com/stretchr/testify/assert"
@@ -303,3 +305,61 @@ func gitCmd(args ...string) error {
 	}
 	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")
+		}
+	})
+
+	t.Run("same directory reuses the same mutex", func(t *testing.T) {
+		dir := t.TempDir()
+
+		v1, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
+		v2, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
+		require.Same(t, v1, v2)
+	})
+}

act/runner/action.go

@@ -429,7 +429,7 @@ func newStepContainer(ctx context.Context, step step, image string, cmd, entrypo
 		Image:        image,
 		Username:     rc.Config.Secrets["DOCKER_USERNAME"],
 		Password:     rc.Config.Secrets["DOCKER_PASSWORD"],
-		Name:         createSimpleContainerName(rc.jobContainerName(), "STEP-"+stepModel.ID),
+		Name:         createContainerName(rc.jobContainerName(), "STEP-"+stepModel.ID),
 		Env:          envList,
 		Mounts:       mounts,
 		NetworkMode:  networkMode,

act/runner/logger.go

@@ -30,6 +30,11 @@ const (
 	gray    = 37
 )
 
+const (
+	rawOutputField      = "raw_output"
+	scriptLineCyanField = "script_line_cyan"
+)
+
 var (
 	colors    []int
 	nextColor int
@@ -161,6 +166,8 @@ func withStepLogger(ctx context.Context, stepNumber int, stepID, stepName, stage
 
 type entryProcessor func(entry *logrus.Entry) *logrus.Entry
 
+// valueMasker applies secrets and ::add-mask:: patterns to every log entry, including
+// raw_output (command/stream) lines; there is no bypass by field.
 func valueMasker(insecureSecrets bool, secrets map[string]string) entryProcessor {
 	return func(entry *logrus.Entry) *logrus.Entry {
 		if insecureSecrets {
@@ -227,8 +234,12 @@ func (f *jobLogFormatter) printColored(b *bytes.Buffer, entry *logrus.Entry) {
 		debugFlag = "[DEBUG] "
 	}
 
-	if entry.Data["raw_output"] == true {
-		fmt.Fprintf(b, "\x1b[%dm|\x1b[0m %s", f.color, entry.Message)
+	if entry.Data[rawOutputField] == true {
+		if entry.Data[scriptLineCyanField] == true {
+			fmt.Fprintf(b, "\x1b[%dm|\x1b[0m \x1b[36;1m%s\x1b[0m", f.color, entry.Message)
+		} else {
+			fmt.Fprintf(b, "\x1b[%dm|\x1b[0m %s", f.color, entry.Message)
+		}
 	} else if entry.Data["dryrun"] == true {
 		fmt.Fprintf(b, "\x1b[1m\x1b[%dm\x1b[7m*DRYRUN*\x1b[0m \x1b[%dm[%s] \x1b[0m%s%s", gray, f.color, job, debugFlag, entry.Message)
 	} else {
@@ -251,7 +262,7 @@ func (f *jobLogFormatter) print(b *bytes.Buffer, entry *logrus.Entry) {
 		debugFlag = "[DEBUG] "
 	}
 
-	if entry.Data["raw_output"] == true {
+	if entry.Data[rawOutputField] == true {
 		fmt.Fprintf(b, "[%s]   | %s", job, entry.Message)
 	} else if entry.Data["dryrun"] == true {
 		fmt.Fprintf(b, "*DRYRUN* [%s] %s%s", job, debugFlag, entry.Message)

act/runner/run_context.go

@@ -101,8 +101,7 @@ func (rc *RunContext) jobContainerName() string {
 	if rc.caller != nil {
 		nameParts = append(nameParts, "CALLED-BY-"+rc.caller.runContext.JobName)
 	}
-	// return createSimpleContainerName(rc.Config.ContainerNamePrefix, "WORKFLOW-"+rc.Run.Workflow.Name, "JOB-"+rc.Name)
-	return createSimpleContainerName(nameParts...) // For Gitea
+	return createContainerName(nameParts...) // For Gitea
 }
 
 // networkNameForGitea return the name of the network
@@ -769,7 +768,6 @@ func mergeMaps(maps ...map[string]string) map[string]string {
 	return rtnMap
 }
 
-// Deprecated: use createSimpleContainerName
 func createContainerName(parts ...string) string {
 	name := strings.Join(parts, "-")
 	pattern := regexp.MustCompile("[^a-zA-Z0-9]")
@@ -783,22 +781,6 @@ func createContainerName(parts ...string) string {
 	return fmt.Sprintf("%s-%x", trimmedName, hash)
 }
 
-func createSimpleContainerName(parts ...string) string {
-	pattern := regexp.MustCompile("[^a-zA-Z0-9-]")
-	name := make([]string, 0, len(parts))
-	for _, v := range parts {
-		v = pattern.ReplaceAllString(v, "-")
-		v = strings.Trim(v, "-")
-		for strings.Contains(v, "--") {
-			v = strings.ReplaceAll(v, "--", "-")
-		}
-		if v != "" {
-			name = append(name, v)
-		}
-	}
-	return strings.Join(name, "_")
-}
-
 func trimToLen(s string, l int) string {
 	if l < 0 {
 		l = 0

act/runner/run_context_test.go

@@ -622,23 +622,16 @@ func TestRunContextGetEnv(t *testing.T) {
 	}
 }
 
-func Test_createSimpleContainerName(t *testing.T) {
-	tests := []struct {
-		parts []string
-		want  string
-	}{
-		{
-			parts: []string{"a--a", "BB正", "c-C"},
-			want:  "a-a_BB_c-C",
-		},
-		{
-			parts: []string{"a-a", "", "-"},
-			want:  "a-a",
-		},
-	}
-	for _, tt := range tests {
-		t.Run(strings.Join(tt.parts, " "), func(t *testing.T) {
-			assert.Equalf(t, tt.want, createSimpleContainerName(tt.parts...), "createSimpleContainerName(%v)", tt.parts)
-		})
-	}
+func TestCreateContainerNameBoundedForLongMatrixInput(t *testing.T) {
+	longMatrixValue := strings.Repeat("os=ubuntu-latest-go=1.24-node=22-", 20)
+	name := createContainerName(
+		"gitea",
+		"WORKFLOW-super-long-workflow-name",
+		"JOB-build-matrix-"+longMatrixValue,
+	)
+
+	assert.LessOrEqual(t, len(name), 128)
+	assert.LessOrEqual(t, len(name+"-env"), 255)
+	assert.LessOrEqual(t, len(name+"-network"), 255)
+	assert.LessOrEqual(t, len(name+"-job1234567890"), 255)
 }

act/runner/step_action_local.go

@@ -44,6 +44,10 @@ func (sal *stepActionLocal) main() common.Executor {
 			return nil
 		}
 
+		printRunActionHeader(ctx, sal.Step, sal.env, sal.getRunContext())
+		rawLogger := common.Logger(ctx).WithField(rawOutputField, true)
+		defer rawLogger.Infof("::endgroup::")
+
 		actionDir := filepath.Join(sal.getRunContext().Config.Workdir, sal.Step.Uses)
 
 		localReader := func(ctx context.Context) actionYamlReader {

act/runner/step_action_remote.go

@@ -166,6 +166,10 @@ func (sar *stepActionRemote) main() common.Executor {
 	return common.NewPipelineExecutor(
 		sar.prepareActionExecutor(),
 		runStepExecutor(sar, stepStageMain, func(ctx context.Context) error {
+			printRunActionHeader(ctx, sar.Step, sar.env, sar.RunContext)
+			rawLogger := common.Logger(ctx).WithField(rawOutputField, true)
+			defer rawLogger.Infof("::endgroup::")
+
 			github := sar.getGithubContext(ctx)
 			if sar.remoteAction.IsCheckout() && isLocalCheckout(github, sar.Step) && !sar.RunContext.Config.NoSkipCheckout {
 				if sar.RunContext.Config.BindWorkdir {

act/runner/step_docker.go

@@ -116,6 +116,10 @@ func (sd *stepDocker) newStepContainer(ctx context.Context, image string, cmd, e
 	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_TEMP", "/tmp"))
 
 	binds, mounts := rc.GetBindsAndMounts()
+	networkMode := "container:" + rc.jobContainerName()
+	if rc.IsHostEnv(ctx) {
+		networkMode = "default"
+	}
 	stepContainer := ContainerNewContainer(&container.NewContainerInput{
 		Cmd:          cmd,
 		Entrypoint:   entrypoint,
@@ -123,10 +127,10 @@ func (sd *stepDocker) newStepContainer(ctx context.Context, image string, cmd, e
 		Image:        image,
 		Username:     rc.Config.Secrets["DOCKER_USERNAME"],
 		Password:     rc.Config.Secrets["DOCKER_PASSWORD"],
-		Name:         createSimpleContainerName(rc.jobContainerName(), "STEP-"+step.ID),
+		Name:         createContainerName(rc.jobContainerName(), "STEP-"+step.ID),
 		Env:          envList,
 		Mounts:       mounts,
-		NetworkMode:  "container:" + rc.jobContainerName(),
+		NetworkMode:  networkMode,
 		Binds:        binds,
 		Stdout:       logWriter,
 		Stderr:       logWriter,

act/runner/step_docker_test.go

@@ -8,6 +8,7 @@ import (
 	"bytes"
 	"context"
 	"io"
+	"strings"
 	"testing"
 
 	"gitea.com/gitea/act_runner/act/container"
@@ -118,3 +119,81 @@ func TestStepDockerPrePost(t *testing.T) {
 	err = sd.post()(ctx)
 	assert.Nil(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 }
+
+func TestStepDockerNewStepContainerNetworkMode(t *testing.T) {
+	cases := []struct {
+		name          string
+		platform      string
+		expectDefault bool
+	}{
+		{
+			name:          "docker mode attaches to job container network",
+			platform:      "node:14",
+			expectDefault: false,
+		},
+		{
+			name:          "host mode uses default network",
+			platform:      "-self-hosted",
+			expectDefault: true,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cm := &containerMock{}
+
+			var captured *container.NewContainerInput
+			origContainerNewContainer := ContainerNewContainer
+			ContainerNewContainer = func(input *container.NewContainerInput) container.ExecutionsEnvironment {
+				captured = input
+				return cm
+			}
+			defer func() {
+				ContainerNewContainer = origContainerNewContainer
+			}()
+
+			ctx := context.Background()
+
+			platform := tc.platform
+			sd := &stepDocker{
+				RunContext: &RunContext{
+					StepResults: map[string]*model.StepResult{},
+					Config: &Config{
+						PlatformPicker: func(_ []string) string {
+							return platform
+						},
+					},
+					Run: &model.Run{
+						JobID: "1",
+						Workflow: &model.Workflow{
+							Jobs: map[string]*model.Job{
+								"1": {},
+							},
+						},
+					},
+					JobContainer: cm,
+				},
+				Step: &model.Step{
+					ID:   "1",
+					Uses: "docker://alpine:3.20",
+				},
+			}
+			sd.RunContext.ExprEval = sd.RunContext.NewExpressionEvaluator(ctx)
+
+			assert.Equal(t, tc.expectDefault, sd.RunContext.IsHostEnv(ctx),
+				"IsHostEnv mismatch for platform %q", tc.platform)
+
+			_ = sd.newStepContainer(ctx, "alpine:3.20", []string{"echo", "hello"}, nil)
+
+			if tc.expectDefault {
+				assert.Equal(t, "default", captured.NetworkMode,
+					"host-mode step container must use 'default' network, got %q",
+					captured.NetworkMode)
+			} else {
+				assert.True(t, strings.HasPrefix(captured.NetworkMode, "container:"),
+					"docker-mode step container must attach to job container network, got %q",
+					captured.NetworkMode)
+			}
+		})
+	}
+}

act/runner/step_run.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"maps"
 	"runtime"
+	"slices"
 	"strings"
 
 	"gitea.com/gitea/act_runner/act/common"
@@ -17,15 +18,18 @@ import (
 	"gitea.com/gitea/act_runner/act/model"
 
 	"github.com/kballard/go-shellquote"
+	yaml "go.yaml.in/yaml/v4"
 )
 
 type stepRun struct {
-	Step             *model.Step
-	RunContext       *RunContext
-	cmd              []string
-	cmdline          string
-	env              map[string]string
-	WorkingDirectory string
+	Step               *model.Step
+	RunContext         *RunContext
+	cmd                []string
+	cmdline            string
+	env                map[string]string
+	WorkingDirectory   string
+	interpolatedScript string
+	shellCommand       string
 }
 
 func (sr *stepRun) pre() common.Executor {
@@ -39,15 +43,154 @@ func (sr *stepRun) main() common.Executor {
 	return runStepExecutor(sr, stepStageMain, common.NewPipelineExecutor(
 		sr.setupShellCommandExecutor(),
 		func(ctx context.Context) error {
-			sr.getRunContext().ApplyExtraPath(ctx, &sr.env)
-			if he, ok := sr.getRunContext().JobContainer.(*container.HostEnvironment); ok && he != nil {
+			rc := sr.getRunContext()
+			// Apply ::add-path:: effects before printing so PATH is accurate in the env: block.
+			rc.ApplyExtraPath(ctx, &sr.env)
+			sr.printRunScriptActionDetails(ctx)
+			if he, ok := rc.JobContainer.(*container.HostEnvironment); ok && he != nil {
 				return he.ExecWithCmdLine(sr.cmd, sr.cmdline, sr.env, "", sr.WorkingDirectory)(ctx)
 			}
-			return sr.getRunContext().JobContainer.Exec(sr.cmd, sr.env, "", sr.WorkingDirectory)(ctx)
+			return rc.JobContainer.Exec(sr.cmd, sr.env, "", sr.WorkingDirectory)(ctx)
 		},
 	))
 }
 
+// printRunScriptActionDetails mirrors actions/runner ScriptHandler.PrintActionDetails
+// for script steps.
+func (sr *stepRun) printRunScriptActionDetails(ctx context.Context) {
+	rawLogger := common.Logger(ctx).WithField(rawOutputField, true)
+	scriptLineLogger := rawLogger.WithField(scriptLineCyanField, true)
+
+	normalized := strings.TrimRight(strings.ReplaceAll(sr.interpolatedScript, "\r\n", "\n"), "\n")
+
+	rawLogger.Infof("::group::Run %s", sr.runScriptGroupTitle(normalized))
+
+	if normalized != "" {
+		for line := range strings.SplitSeq(normalized, "\n") {
+			scriptLineLogger.Info(line)
+		}
+	}
+
+	rawLogger.Infof("shell: %s", sr.shellCommand)
+
+	printStepEnvBlock(ctx, sr.Step, sr.env, sr.getRunContext())
+	rawLogger.Infof("::endgroup::")
+}
+
+// printRunActionHeader mirrors actions/runner's "Run <action>" header for `uses:` steps,
+// including the with: inputs and the step-level env: block. The caller is responsible
+// for emitting ::endgroup:: after the action finishes.
+func printRunActionHeader(ctx context.Context, step *model.Step, env map[string]string, rc *RunContext) {
+	if step == nil {
+		return
+	}
+	rawLogger := common.Logger(ctx).WithField(rawOutputField, true)
+
+	title := step.Uses
+	if step.Name != "" {
+		title = step.Name
+	}
+	rawLogger.Infof("::group::Run %s", title)
+
+	if len(step.With) > 0 {
+		rawLogger.Infof("with:")
+		for _, k := range slices.Sorted(maps.Keys(step.With)) {
+			rawLogger.Infof("  %s: %s", k, step.With[k])
+		}
+	}
+
+	printStepEnvBlock(ctx, step, env, rc)
+}
+
+// printStepEnvBlock emits the declared-env block (YAML order, internal vars filtered)
+// shared by the run: and uses: "Run" headers.
+func printStepEnvBlock(ctx context.Context, step *model.Step, env map[string]string, rc *RunContext) {
+	rawLogger := common.Logger(ctx).WithField(rawOutputField, true)
+	caseInsensitive := rc != nil && rc.JobContainer != nil && rc.JobContainer.IsEnvironmentCaseInsensitive()
+	var visible []string
+	for _, k := range stepDeclaredEnvKeysInOrder(step) {
+		if !isInternalEnvKey(k, caseInsensitive) {
+			visible = append(visible, k)
+		}
+	}
+	if len(visible) == 0 {
+		return
+	}
+	rawLogger.Infof("env:")
+	envLookup := env
+	if caseInsensitive {
+		envLookup = make(map[string]string, len(env))
+		for k, v := range env {
+			envLookup[strings.ToUpper(k)] = v
+		}
+	}
+	for _, k := range visible {
+		lookupKey := k
+		if caseInsensitive {
+			lookupKey = strings.ToUpper(k)
+		}
+		rawLogger.Infof("  %s: %s", k, envLookup[lookupKey])
+	}
+}
+
+// isInternalEnvKey matches actions/runner's filtered set of vars that are hidden
+// from the "Run" header's env: block because they are injected by the runner itself.
+func isInternalEnvKey(k string, caseInsensitive bool) bool {
+	upper := k
+	if caseInsensitive {
+		upper = strings.ToUpper(k)
+	}
+	switch upper {
+	case "PATH", "HOME", "CI":
+		return true
+	}
+	return strings.HasPrefix(upper, "GITHUB_") ||
+		strings.HasPrefix(upper, "GITEA_") ||
+		strings.HasPrefix(upper, "RUNNER_") ||
+		strings.HasPrefix(upper, "INPUT_")
+}
+
+func (sr *stepRun) runScriptGroupTitle(normalizedScript string) string {
+	trimmed := strings.TrimLeft(normalizedScript, " \t\r\n")
+	if idx := strings.IndexAny(trimmed, "\r\n"); idx >= 0 {
+		trimmed = trimmed[:idx]
+	}
+	if trimmed != "" {
+		return trimmed
+	}
+	if sr.Step != nil {
+		if sr.Step.Name != "" {
+			return sr.Step.Name
+		}
+		return sr.Step.ID
+	}
+	return ""
+}
+
+// stepDeclaredEnvKeysInOrder walks the raw YAML Env mapping so keys are emitted in
+// the order the workflow author wrote them; step.Environment() decodes into a Go map
+// and loses ordering.
+func stepDeclaredEnvKeysInOrder(step *model.Step) []string {
+	if step == nil || step.Env.Kind != yaml.MappingNode {
+		return nil
+	}
+	content := step.Env.Content
+	keys := make([]string, 0, len(content)/2)
+	seen := make(map[string]struct{}, len(content)/2)
+	for i := 0; i+1 < len(content); i += 2 {
+		k := content[i]
+		if k.Kind != yaml.ScalarNode || k.Tag == "!!merge" || k.Value == "<<" {
+			continue
+		}
+		if _, dup := seen[k.Value]; dup {
+			continue
+		}
+		seen[k.Value] = struct{}{}
+		keys = append(keys, k.Value)
+	}
+	return keys
+}
+
 func (sr *stepRun) post() common.Executor {
 	return func(ctx context.Context) error {
 		return nil
@@ -111,8 +254,10 @@ func (sr *stepRun) setupShellCommand(ctx context.Context) (name, script string,
 	step := sr.Step
 
 	script = sr.RunContext.NewStepExpressionEvaluator(ctx, sr).Interpolate(ctx, step.Run)
+	sr.interpolatedScript = script
 
 	scCmd := step.ShellCommand()
+	sr.shellCommand = scCmd
 
 	name = getScriptName(sr.RunContext, step)
 

act/runner/step_run_print_test.go

@@ -0,0 +1,182 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// Copyright 2026 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package runner
+
+import (
+	"bytes"
+	"context"
+	"strings"
+	"testing"
+
+	"gitea.com/gitea/act_runner/act/common"
+	"gitea.com/gitea/act_runner/act/model"
+
+	"github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	yaml "go.yaml.in/yaml/v4"
+)
+
+func TestRunScriptGroupTitle(t *testing.T) {
+	sr := &stepRun{Step: &model.Step{Name: "Build"}}
+	assert.Equal(t, "make build", sr.runScriptGroupTitle("make build"))
+	assert.Equal(t, "echo one", sr.runScriptGroupTitle("  \techo one\necho two"))
+	assert.Equal(t, "Build", sr.runScriptGroupTitle(""))
+
+	sr = &stepRun{Step: &model.Step{ID: "s1"}}
+	assert.Equal(t, "s1", sr.runScriptGroupTitle("\n  \n"))
+}
+
+func TestStepDeclaredEnvOrderPreservesYAML(t *testing.T) {
+	raw := `id: s1
+run: "echo 1"
+env:
+  GITHUB_TOKEN: tok
+  PATH: /custom/bin
+  MY_VAR: hello
+`
+	var step model.Step
+	require.NoError(t, yaml.Unmarshal([]byte(raw), &step))
+	assert.Equal(t, []string{"GITHUB_TOKEN", "PATH", "MY_VAR"}, stepDeclaredEnvKeysInOrder(&step))
+}
+
+func TestStepDeclaredEnvKeysInOrderEmpty(t *testing.T) {
+	assert.Nil(t, stepDeclaredEnvKeysInOrder(nil))
+	assert.Empty(t, stepDeclaredEnvKeysInOrder(&model.Step{}))
+}
+
+func TestStepDeclaredEnvKeysIgnoreYAMLMergeKey(t *testing.T) {
+	doc := `
+common: &common
+  COMMON_A: a
+  COMMON_B: b
+step:
+  env:
+    LOCAL_BEFORE: before
+    <<: *common
+    COMMON_B: overridden
+    LOCAL_AFTER: after
+`
+	var root struct {
+		Step model.Step `yaml:"step"`
+	}
+	require.NoError(t, yaml.Unmarshal([]byte(doc), &root))
+
+	keys := stepDeclaredEnvKeysInOrder(&root.Step)
+	assert.Equal(t, []string{"LOCAL_BEFORE", "COMMON_B", "LOCAL_AFTER"}, keys)
+}
+
+func TestPrintRunScriptActionDetailsGolden(t *testing.T) {
+	raw := `id: s1
+name: Build
+run: |
+  echo one
+  echo two
+shell: pwsh
+env:
+  PATH_PREFIX: /custom/bin
+  GITHUB_TOKEN: tok
+  GREETING: hello
+`
+	var step model.Step
+	require.NoError(t, yaml.Unmarshal([]byte(raw), &step))
+
+	buf := &bytes.Buffer{}
+	logger := logrus.New()
+	logger.SetOutput(buf)
+	logger.SetLevel(logrus.InfoLevel)
+	logger.SetFormatter(&jobLogFormatter{color: cyan})
+	entry := logger.WithFields(logrus.Fields{"job": "j1"})
+	ctx := common.WithLogger(context.Background(), entry)
+
+	sr := &stepRun{
+		Step:               &step,
+		RunContext:         &RunContext{},
+		shellCommand:       "pwsh -command . '{0}'",
+		interpolatedScript: "echo one\necho two\n",
+		env: map[string]string{
+			"PATH_PREFIX":  "/custom/bin",
+			"GITHUB_TOKEN": "tok",
+			"GREETING":     "hello",
+		},
+	}
+
+	sr.printRunScriptActionDetails(ctx)
+
+	want := strings.Join([]string{
+		"[j1]   | ::group::Run echo one",
+		"[j1]   | echo one",
+		"[j1]   | echo two",
+		"[j1]   | shell: pwsh -command . '{0}'",
+		"[j1]   | env:",
+		"[j1]   |   PATH_PREFIX: /custom/bin",
+		"[j1]   |   GREETING: hello",
+		"[j1]   | ::endgroup::",
+		"",
+	}, "\n")
+	assert.Equal(t, want, buf.String())
+}
+
+func TestPrintRunActionHeaderGolden(t *testing.T) {
+	raw := `id: s1
+uses: actions/checkout@v4
+with:
+  fetch-depth: "0"
+  token: secret
+env:
+  CUSTOM: value
+  GITHUB_TOKEN: tok
+`
+	var step model.Step
+	require.NoError(t, yaml.Unmarshal([]byte(raw), &step))
+
+	buf := &bytes.Buffer{}
+	logger := logrus.New()
+	logger.SetOutput(buf)
+	logger.SetLevel(logrus.InfoLevel)
+	logger.SetFormatter(&jobLogFormatter{color: cyan})
+	entry := logger.WithFields(logrus.Fields{"job": "j1"})
+	ctx := common.WithLogger(context.Background(), entry)
+
+	printRunActionHeader(ctx, &step, map[string]string{"CUSTOM": "value", "GITHUB_TOKEN": "tok"}, &RunContext{})
+
+	want := strings.Join([]string{
+		"[j1]   | ::group::Run actions/checkout@v4",
+		"[j1]   | with:",
+		"[j1]   |   fetch-depth: 0",
+		"[j1]   |   token: secret",
+		"[j1]   | env:",
+		"[j1]   |   CUSTOM: value",
+		"",
+	}, "\n")
+	assert.Equal(t, want, buf.String())
+}
+
+func TestIsInternalEnvKey(t *testing.T) {
+	for _, k := range []string{"PATH", "HOME", "CI", "GITHUB_TOKEN", "GITEA_ACTIONS", "RUNNER_OS", "INPUT_FOO"} {
+		assert.True(t, isInternalEnvKey(k, false), k)
+	}
+	for _, k := range []string{"PATH_PREFIX", "MY_VAR", "GREETING", "HOMEPAGE"} {
+		assert.False(t, isInternalEnvKey(k, false), k)
+	}
+	assert.True(t, isInternalEnvKey("path", true))
+	assert.False(t, isInternalEnvKey("path", false))
+}
+
+func TestPrintColoredScriptLineCyan(t *testing.T) {
+	f := &jobLogFormatter{color: cyan}
+	entry := &logrus.Entry{
+		Level:   logrus.InfoLevel,
+		Message: "echo one",
+		Data: logrus.Fields{
+			"job":               "j1",
+			rawOutputField:      true,
+			scriptLineCyanField: true,
+		},
+	}
+	buf := &bytes.Buffer{}
+	f.printColored(buf, entry)
+	assert.Equal(t, "\x1b[36m|\x1b[0m \x1b[36;1mecho one\x1b[0m", buf.String())
+}

go.mod

@@ -6,9 +6,9 @@ require (
 	code.gitea.io/actions-proto-go v0.4.1
 	connectrpc.com/connect v1.19.2
 	github.com/avast/retry-go/v4 v4.7.0
-	github.com/docker/docker v25.0.13+incompatible
+	github.com/docker/docker v25.0.14+incompatible
 	github.com/joho/godotenv v1.5.1
-	github.com/mattn/go-isatty v0.0.20
+	github.com/mattn/go-isatty v0.0.22
 	github.com/sirupsen/logrus v1.9.4
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1
@@ -114,7 +114,3 @@ require (
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )
-
-// Remove after github.com/docker/distribution is updated to support distribution/reference v0.6.0
-// (pulled in via moby/buildkit, breaks on undefined: reference.SplitHostname)
-replace github.com/distribution/reference v0.6.0 => github.com/distribution/reference v0.5.0

go.sum

@@ -1,7 +1,5 @@
 code.gitea.io/actions-proto-go v0.4.1 h1:l0EYhjsgpUe/1VABo2eK7zcoNX2W44WOnb0MSLrKfls=
 code.gitea.io/actions-proto-go v0.4.1/go.mod h1:mn7Wkqz6JbnTOHQpot3yDeHx+O5C9EGhMEE+htvHBas=
-connectrpc.com/connect v1.19.1 h1:R5M57z05+90EfEvCY1b7hBxDVOUl45PrtXtAV2fOC14=
-connectrpc.com/connect v1.19.1/go.mod h1:tN20fjdGlewnSFeZxLKb0xwIZ6ozc3OQs2hTXy4du9w=
 connectrpc.com/connect v1.19.2 h1:McQ83FGdzL+t60peksi0gXC7MQ/iLKgLduAnThbM0mo=
 connectrpc.com/connect v1.19.2/go.mod h1:tN20fjdGlewnSFeZxLKb0xwIZ6ozc3OQs2hTXy4du9w=
 cyphar.com/go-pathrs v0.2.3 h1:0pH8gep37wB0BgaXrEaN1OtZhUMeS7VvaejSr6i822o=
@@ -51,14 +49,14 @@ github.com/cyphar/filepath-securejoin v0.6.1/go.mod h1:A8hd4EnAeyujCJRrICiOWqjS1
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/distribution/reference v0.5.0 h1:/FUIFXtfc/x2gpa5/VGfiGLuOIdYa1t65IKK2OFGvA0=
-github.com/distribution/reference v0.5.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
-github.com/docker/cli v25.0.3+incompatible h1:KLeNs7zws74oFuVhgZQ5ONGZiXUUdgsdy6/EsX/6284=
-github.com/docker/cli v25.0.3+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
+github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
+github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
 github.com/docker/cli v25.0.7+incompatible h1:scW/AbGafKmANsonsFckFHTwpz2QypoPA/zpoLnDs/E=
 github.com/docker/cli v25.0.7+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
 github.com/docker/docker v25.0.13+incompatible h1:YeBrkUd3q0ZoRDNoEzuopwCLU+uD8GZahDHwBdsTnkU=
 github.com/docker/docker v25.0.13+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/docker v25.0.14+incompatible h1:+HNue3fKbqiDHYFAriyiMjfS5u25zB0E2/R8f42lOMc=
+github.com/docker/docker v25.0.14+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
 github.com/docker/docker-credential-helpers v0.9.5 h1:EFNN8DHvaiK8zVqFA2DT6BjXE0GzfLOZ38ggPTKePkY=
 github.com/docker/docker-credential-helpers v0.9.5/go.mod h1:v1S+hepowrQXITkEfw6o4+BMbGot02wiKpzWhGUZK6c=
 github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
@@ -135,6 +133,8 @@ github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHP
 github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4=
+github.com/mattn/go-isatty v0.0.22/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
 github.com/mattn/go-runewidth v0.0.20 h1:WcT52H91ZUAwy8+HUkdM3THM6gXqXuLJi9O3rjcQQaQ=
 github.com/mattn/go-runewidth v0.0.20/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/mattn/go-shellwords v1.0.12 h1:M2zGm7EW6UQJvDeQxo4T51eKPurbeFbe8WtebGE2xrk=

internal/app/cmd/cache-server.go

@@ -4,6 +4,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"os"
 	"os/signal"
@@ -47,10 +48,15 @@ func runCacheServer(configFile *string, cacheArgs *cacheServerArgs) func(cmd *co
 			port = cacheArgs.Port
 		}
 
+		secret := cfg.Cache.ExternalSecret
+		if secret == "" {
+			return errors.New("cache.external_secret must be set for cache-server; configure the same value on each runner that points at this server via cache.external_server")
+		}
 		cacheHandler, err := artifactcache.StartHandler(
 			dir,
 			host,
 			port,
+			secret,
 			log.StandardLogger().WithField("module", "cache_request"),
 		)
 		if err != nil {

internal/app/cmd/exec.go

@@ -6,6 +6,8 @@ package cmd
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"maps"
@@ -368,7 +370,7 @@ func runExec(ctx context.Context, execArgs *executeArgs) func(cmd *cobra.Command
 		}
 
 		// init a cache server
-		handler, err := artifactcache.StartHandler("", "", 0, log.StandardLogger().WithField("module", "cache_request"))
+		handler, err := artifactcache.StartHandler("", "", 0, "", log.StandardLogger().WithField("module", "cache_request"))
 		if err != nil {
 			return err
 		}
@@ -393,6 +395,25 @@ func runExec(ctx context.Context, execArgs *executeArgs) func(cmd *cobra.Command
 			execArgs.artifactServerPath = tempDir
 		}
 
+		// Register ACTIONS_RUNTIME_TOKEN against local cache server
+		env := execArgs.LoadEnvs()
+		const actionsRuntimeTokenEnvName = "ACTIONS_RUNTIME_TOKEN"
+		actionsRuntimeToken := env[actionsRuntimeTokenEnvName]
+		if actionsRuntimeToken == "" {
+			actionsRuntimeToken = os.Getenv(actionsRuntimeTokenEnvName)
+		}
+		if actionsRuntimeToken == "" {
+			tmpBranch := make([]byte, 12)
+			if _, err := rand.Read(tmpBranch); err != nil {
+				actionsRuntimeToken = "token"
+			} else {
+				actionsRuntimeToken = hex.EncodeToString(tmpBranch)
+			}
+			env[actionsRuntimeTokenEnvName] = actionsRuntimeToken
+			os.Setenv(actionsRuntimeTokenEnvName, actionsRuntimeToken)
+		}
+		handler.RegisterJob(actionsRuntimeToken, "__local/__exec")
+
 		// run the plan
 		config := &runner.Config{
 			Workdir:               execArgs.Workdir(),
@@ -402,7 +423,7 @@ func runExec(ctx context.Context, execArgs *executeArgs) func(cmd *cobra.Command
 			ForceRebuild:          execArgs.forceRebuild,
 			LogOutput:             true,
 			JSONLogger:            execArgs.jsonLogger,
-			Env:                   execArgs.LoadEnvs(),
+			Env:                   env,
 			Vars:                  execArgs.LoadVars(),
 			Secrets:               execArgs.LoadSecrets(),
 			InsecureSecrets:       execArgs.insecureSecrets,

internal/app/run/runner.go

@@ -4,10 +4,12 @@
 package run
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
 	"maps"
+	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
@@ -38,9 +40,10 @@ type Runner struct {
 
 	cfg *config.Config
 
-	client client.Client
-	labels labels.Labels
-	envs   map[string]string
+	client       client.Client
+	labels       labels.Labels
+	envs         map[string]string
+	cacheHandler *artifactcache.Handler
 
 	runningTasks sync.Map
 	runningCount atomic.Int64
@@ -55,21 +58,24 @@ func NewRunner(cfg *config.Config, reg *config.Registration, cli client.Client)
 	}
 	envs := make(map[string]string, len(cfg.Runner.Envs))
 	maps.Copy(envs, cfg.Runner.Envs)
+	var cacheHandler *artifactcache.Handler
 	if cfg.Cache.Enabled == nil || *cfg.Cache.Enabled {
 		if cfg.Cache.ExternalServer != "" {
 			envs["ACTIONS_CACHE_URL"] = cfg.Cache.ExternalServer
 		} else {
-			cacheHandler, err := artifactcache.StartHandler(
+			handler, err := artifactcache.StartHandler(
 				cfg.Cache.Dir,
 				cfg.Cache.Host,
 				cfg.Cache.Port,
+				"",
 				log.StandardLogger().WithField("module", "cache_request"),
 			)
 			if err != nil {
 				log.Errorf("cannot init cache server, it will be disabled: %v", err)
 				// go on
 			} else {
-				envs["ACTIONS_CACHE_URL"] = cacheHandler.ExternalURL() + "/"
+				cacheHandler = handler
+				envs["ACTIONS_CACHE_URL"] = handler.ExternalURL() + "/"
 			}
 		}
 	}
@@ -84,11 +90,12 @@ func NewRunner(cfg *config.Config, reg *config.Registration, cli client.Client)
 	envs["GITEA_ACTIONS_RUNNER_VERSION"] = ver.Version()
 
 	return &Runner{
-		name:   reg.Name,
-		cfg:    cfg,
-		client: cli,
-		labels: ls,
-		envs:   envs,
+		name:         reg.Name,
+		cfg:          cfg,
+		client:       cli,
+		labels:       ls,
+		envs:         envs,
+		cacheHandler: cacheHandler,
 	}
 }
 
@@ -199,6 +206,21 @@ func (r *Runner) run(ctx context.Context, task *runnerv1.Task, reporter *report.
 		giteaRuntimeToken = preset.Token
 	}
 	r.envs["ACTIONS_RUNTIME_TOKEN"] = giteaRuntimeToken
+	// Mask the runtime token so it cannot be echoed in user step output; it is
+	// now also the cache server's bearer credential and leaking it would let
+	// any reader of the log impersonate this job against the cache.
+	if giteaRuntimeToken != "" {
+		task.Secrets["ACTIONS_RUNTIME_TOKEN"] = giteaRuntimeToken
+	}
+
+	// Register this job's runtime token with the local cache server so that
+	// cache requests from the job container can authenticate. The credential
+	// is removed when the task finishes, so a leaked token stops working as
+	// soon as the job ends rather than remaining valid for the runner's
+	// lifetime. Only applies to the embedded cache server; when the operator
+	// points the runner at an external cache via cfg.Cache.ExternalServer, it
+	// is that server's responsibility to authenticate requests.
+	defer r.registerCacheForTask(giteaRuntimeToken, preset.Repository, reporter)()
 
 	eventJSON, err := json.Marshal(preset.Event)
 	if err != nil {
@@ -278,6 +300,82 @@ func (r *Runner) run(ctx context.Context, task *runnerv1.Task, reporter *report.
 	return execErr
 }
 
+// registerCacheForTask tells the cache server to accept requests authenticated
+// with the given runtime token for the duration of this task. Returns a
+// function the caller must invoke (typically via defer) to revoke the
+// credential when the task finishes.
+//
+// Three modes:
+//   - Embedded handler: register in-process via RegisterJob.
+//   - external_server + external_secret: POST to the remote server's
+//     /_internal/register, defer a POST to /_internal/revoke. This is what
+//     enables full per-job auth and repo scoping over the network.
+//   - external_server alone (no secret): no-op revoker. The remote server is
+//     in legacy openMode and ignores the runtime token; trust is at the
+//     network layer.
+//
+// Safe with an empty token (older Gitea did not issue one).
+func (r *Runner) registerCacheForTask(token, repo string, reporter *report.Reporter) func() {
+	if token == "" {
+		return func() {}
+	}
+	if r.cacheHandler != nil {
+		return r.cacheHandler.RegisterJob(token, repo)
+	}
+	if r.cfg.Cache.ExternalServer != "" && r.cfg.Cache.ExternalSecret != "" {
+		return r.registerExternalCacheJob(token, repo, reporter)
+	}
+	return func() {}
+}
+
+// registerExternalCacheJob POSTs to the remote cache-server's control-plane.
+// Failures are logged but not fatal: if registration fails, the cache will
+// 401 the job's requests — better than failing the whole task for a cache
+// outage. The warning is mirrored to the job log so users can see why their
+// cache calls 401, instead of having to read the runner daemon's stderr.
+func (r *Runner) registerExternalCacheJob(token, repo string, reporter *report.Reporter) func() {
+	base := strings.TrimRight(r.cfg.Cache.ExternalServer, "/")
+	if err := postInternalCache(base+"/_internal/register", r.cfg.Cache.ExternalSecret,
+		map[string]string{"token": token, "repo": repo}); err != nil {
+		log.Warnf("cache external_server register failed (%s): %v", base, err)
+		if reporter != nil {
+			reporter.Logf("::warning::cache external_server register failed (%s): %v — cache requests from this job will be unauthenticated and likely return 401", base, err)
+		}
+	}
+	return func() {
+		if err := postInternalCache(base+"/_internal/revoke", r.cfg.Cache.ExternalSecret,
+			map[string]string{"token": token}); err != nil {
+			log.Warnf("cache external_server revoke failed (%s): %v", base, err)
+			if reporter != nil {
+				reporter.Logf("::warning::cache external_server revoke failed (%s): %v", base, err)
+			}
+		}
+	}
+}
+
+func postInternalCache(url, secret string, body map[string]string) error {
+	buf, err := json.Marshal(body)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(buf))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+secret)
+	req.Header.Set("Content-Type", "application/json")
+	client := &http.Client{Timeout: 5 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode/100 != 2 {
+		return fmt.Errorf("status %d", resp.StatusCode)
+	}
+	return nil
+}
+
 func (r *Runner) RunningCount() int64 {
 	return r.runningCount.Load()
 }

internal/app/run/runner_cache_test.go

@@ -0,0 +1,239 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package run
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.com/gitea/act_runner/act/artifactcache"
+	"gitea.com/gitea/act_runner/internal/pkg/config"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func emptyCfg() *config.Config { return &config.Config{} }
+
+func TestRunner_registerCacheForTask(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "artifactcache")
+	handler, err := artifactcache.StartHandler(dir, "127.0.0.1", 0, "", nil)
+	require.NoError(t, err)
+	defer handler.Close()
+
+	r := &Runner{cfg: emptyCfg(), cacheHandler: handler}
+	token := "run-token-123"
+	unregister := r.registerCacheForTask(token, "owner/repo", nil)
+
+	base := handler.ExternalURL() + "/_apis/artifactcache"
+	probe := func() int {
+		req, err := http.NewRequest(http.MethodGet, base+"/cache?keys=x&version=v", nil)
+		require.NoError(t, err)
+		req.Header.Set("Authorization", "Bearer "+token)
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		resp.Body.Close()
+		return resp.StatusCode
+	}
+
+	assert.NotEqual(t, http.StatusUnauthorized, probe(),
+		"token should be accepted while task is registered")
+
+	unregister()
+	assert.Equal(t, http.StatusUnauthorized, probe(),
+		"token must be rejected after the revoker runs")
+}
+
+func TestRunner_registerCacheForTask_NoOps(t *testing.T) {
+	t.Run("nil cacheHandler", func(t *testing.T) {
+		r := &Runner{cfg: emptyCfg()}
+		unregister := r.registerCacheForTask("tok", "owner/repo", nil)
+		require.NotNil(t, unregister)
+		unregister()
+	})
+
+	t.Run("empty token", func(t *testing.T) {
+		dir := filepath.Join(t.TempDir(), "artifactcache")
+		handler, err := artifactcache.StartHandler(dir, "127.0.0.1", 0, "", nil)
+		require.NoError(t, err)
+		defer handler.Close()
+
+		r := &Runner{cfg: emptyCfg(), cacheHandler: handler}
+		unregister := r.registerCacheForTask("", "owner/repo", nil)
+		require.NotNil(t, unregister)
+		unregister()
+	})
+}
+
+// Locks in @actions/cache's wire protocol: bearer on reserve/upload/commit
+// /find, no auth on the signed archiveLocation download.
+func TestRunner_CacheFullFlow_MatchesToolkit(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "artifactcache")
+	handler, err := artifactcache.StartHandler(dir, "127.0.0.1", 0, "", nil)
+	require.NoError(t, err)
+	defer handler.Close()
+
+	r := &Runner{cfg: emptyCfg(), cacheHandler: handler}
+	token := "full-flow-token"
+	unregister := r.registerCacheForTask(token, "owner/repo", nil)
+	defer unregister()
+
+	base := handler.ExternalURL() + "/_apis/artifactcache"
+	do := func(method, url, contentType, contentRange, body string) *http.Response {
+		req, err := http.NewRequest(method, url, strings.NewReader(body))
+		require.NoError(t, err)
+		req.Header.Set("Authorization", "Bearer "+token)
+		if contentType != "" {
+			req.Header.Set("Content-Type", contentType)
+		}
+		if contentRange != "" {
+			req.Header.Set("Content-Range", contentRange)
+		}
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		return resp
+	}
+
+	key := "toolkit-flow"
+	version := "c19da02a2bd7e77277f1ac29ab45c09b7d46a4ee758284e26bb3045ad11d9d20"
+	body := `hello-cache-body`
+
+	// reserve
+	resp := do(http.MethodPost, base+"/caches", "application/json", "",
+		fmt.Sprintf(`{"key":"%s","version":"%s","cacheSize":%d}`, key, version, len(body)))
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	var reserved struct {
+		CacheID uint64 `json:"cacheId"`
+	}
+	require.NoError(t, decodeJSON(resp, &reserved))
+	require.NotZero(t, reserved.CacheID)
+
+	// upload
+	resp = do(http.MethodPatch, fmt.Sprintf("%s/caches/%d", base, reserved.CacheID),
+		"application/octet-stream", fmt.Sprintf("bytes 0-%d/*", len(body)-1), body)
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	resp.Body.Close()
+
+	// commit
+	resp = do(http.MethodPost, fmt.Sprintf("%s/caches/%d", base, reserved.CacheID), "", "", "")
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	resp.Body.Close()
+
+	// find — @actions/cache always sends comma-separated keys here
+	resp = do(http.MethodGet,
+		fmt.Sprintf("%s/cache?keys=%s,fallback&version=%s", base, key, version), "", "", "")
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	var hit struct {
+		ArchiveLocation string `json:"archiveLocation"`
+		CacheKey        string `json:"cacheKey"`
+	}
+	require.NoError(t, decodeJSON(resp, &hit))
+	require.Equal(t, key, hit.CacheKey)
+	require.NotEmpty(t, hit.ArchiveLocation)
+
+	// download — toolkit does NOT attach Authorization here; the signature
+	// in the URL must be enough.
+	dl, err := http.Get(hit.ArchiveLocation)
+	require.NoError(t, err)
+	defer dl.Body.Close()
+	require.Equal(t, http.StatusOK, dl.StatusCode)
+	got := make([]byte, 64)
+	n, _ := dl.Body.Read(got)
+	assert.Equal(t, body, string(got[:n]))
+}
+
+func decodeJSON(resp *http.Response, v any) error {
+	defer resp.Body.Close()
+	return json.NewDecoder(resp.Body).Decode(v)
+}
+
+// End-to-end against a remote cache-server: token unknown → 401, register →
+// reserve/upload/commit/find/download all OK, revoke → 401 again.
+func TestRunner_ExternalCacheServer_RegisterRevoke(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "remote-cache")
+	const secret = "shared-secret-for-tests"
+	remote, err := artifactcache.StartHandler(dir, "127.0.0.1", 0, secret, nil)
+	require.NoError(t, err)
+	defer remote.Close()
+
+	r := &Runner{cfg: &config.Config{Cache: config.Cache{
+		ExternalServer: remote.ExternalURL(),
+		ExternalSecret: secret,
+	}}}
+
+	token := "external-task-token"
+	repo := "owner/repoX"
+	base := remote.ExternalURL() + "/_apis/artifactcache"
+	probe := func() int {
+		req, _ := http.NewRequest(http.MethodGet, base+"/cache?keys=k&version=v", nil)
+		req.Header.Set("Authorization", "Bearer "+token)
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		resp.Body.Close()
+		return resp.StatusCode
+	}
+
+	require.Equal(t, http.StatusUnauthorized, probe(),
+		"token must be unknown to the remote server before registration")
+
+	unregister := r.registerCacheForTask(token, repo, nil)
+	require.NotEqual(t, http.StatusUnauthorized, probe(),
+		"token must be accepted after registerCacheForTask")
+
+	// Full reserve→upload→commit→find→download cycle, identical to what
+	// @actions/cache does, against the remote (external) server.
+	body := []byte("payload-from-task")
+	reserveBody, _ := json.Marshal(&artifactcache.Request{Key: "ext-key", Version: "v", Size: int64(len(body))})
+	req, _ := http.NewRequest(http.MethodPost, base+"/caches", bytes.NewReader(reserveBody))
+	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	var reserved struct {
+		CacheID uint64 `json:"cacheId"`
+	}
+	require.NoError(t, decodeJSON(resp, &reserved))
+	require.NotZero(t, reserved.CacheID)
+
+	req, _ = http.NewRequest(http.MethodPatch, fmt.Sprintf("%s/caches/%d", base, reserved.CacheID), bytes.NewReader(body))
+	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Content-Range", fmt.Sprintf("bytes 0-%d/*", len(body)-1))
+	resp, err = http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	req, _ = http.NewRequest(http.MethodPost, fmt.Sprintf("%s/caches/%d", base, reserved.CacheID), nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err = http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	req, _ = http.NewRequest(http.MethodGet, base+"/cache?keys=ext-key&version=v", nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	resp, err = http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	var hit struct {
+		ArchiveLocation string `json:"archiveLocation"`
+	}
+	require.NoError(t, decodeJSON(resp, &hit))
+	require.NotEmpty(t, hit.ArchiveLocation)
+
+	dl, err := http.Get(hit.ArchiveLocation)
+	require.NoError(t, err)
+	defer dl.Body.Close()
+	require.Equal(t, http.StatusOK, dl.StatusCode)
+
+	unregister()
+	assert.Equal(t, http.StatusUnauthorized, probe(),
+		"token must be rejected after the revoker runs")
+}

internal/pkg/config/config.example.yaml

@@ -81,7 +81,12 @@ cache:
   # The external cache server URL. Valid only when enable is true.
   # If it's specified, act_runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself.
   # The URL should generally end with "/".
+  # Requires external_secret below to be set to the same value on both this runner and the cache-server.
   external_server: ""
+  # Shared secret between this runner and the external `act_runner cache-server`. Required when external_server
+  # (or `act_runner cache-server`) is in use: the runner pre-registers each job's ACTIONS_RUNTIME_TOKEN with the
+  # cache-server, and the cache-server enforces bearer auth + per-repo cache isolation.
+  external_secret: ""
 
 container:
   # Specifies the network to which the container will connect.

internal/pkg/config/config.go

@@ -4,6 +4,7 @@
 package config
 
 import (
+	"errors"
 	"fmt"
 	"maps"
 	"os"
@@ -47,6 +48,7 @@ type Cache struct {
 	Host           string `yaml:"host"`            // Host specifies the caching host.
 	Port           uint16 `yaml:"port"`            // Port specifies the caching port.
 	ExternalServer string `yaml:"external_server"` // ExternalServer specifies the URL of external cache server
+	ExternalSecret string `yaml:"external_secret"` // ExternalSecret is a shared secret between this runner and an external act_runner cache-server, enabling per-job ACTIONS_RUNTIME_TOKEN authentication and repo scoping over the network. Leave empty to keep the legacy unauthenticated behavior.
 }
 
 // Container represents the configuration for the container.
@@ -135,6 +137,9 @@ func LoadDefault(file string) (*Config, error) {
 			home, _ := os.UserHomeDir()
 			cfg.Cache.Dir = filepath.Join(home, ".cache", "actcache")
 		}
+		if cfg.Cache.ExternalServer != "" && cfg.Cache.ExternalSecret == "" {
+			return nil, errors.New("cache.external_server is set but cache.external_secret is empty; configure the same external_secret on this runner and the act_runner cache-server")
+		}
 	}
 	if cfg.Container.WorkdirParent == "" {
 		cfg.Container.WorkdirParent = "workspace"

internal/pkg/config/config_test.go

@@ -0,0 +1,41 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLoadDefault_RejectsExternalServerWithoutSecret(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	require.NoError(t, os.WriteFile(path, []byte(`
+cache:
+  enabled: true
+  external_server: "http://cache.invalid/"
+`), 0o600))
+
+	_, err := LoadDefault(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "external_secret")
+}
+
+func TestLoadDefault_AcceptsExternalServerWithSecret(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	require.NoError(t, os.WriteFile(path, []byte(`
+cache:
+  enabled: true
+  external_server: "http://cache.invalid/"
+  external_secret: "shh"
+`), 0o600))
+
+	_, err := LoadDefault(path)
+	require.NoError(t, err)
+}