enhance: add runner.tool_cache_mode and default it to none (#1171)

The current shared tools cache is not concurrency-safe, e.g. multiple jobs can write and corrupt it, for example `setup-go` with explicit go version under concurrency reliably corrupts the tool cache and fails all jobs.

This adds a new `runner.tool_cache_mode` (and `--tool-cache-mode` exec option) option which defaults to unshared tools cache:

- `none` mounts nothing, so a job uses what its image ships there and discards what it installs
- `shared` keeps the single volume every job reuses, and warns when `runner.capacity` is above 1

Under `none` effective tool cache can only come from the image or host, which is the same as it is on GitHub Actions which ships many preinstalled tools in its fat VM images.

Co-authored-by: bircni <bircni@icloud.com>
Reviewed-on: https://gitea.com/gitea/runner/pulls/1171
Reviewed-by: bircni <bircni@icloud.com>
Co-authored-by: silverwind <me@silverwind.io>

act/runner/run_context.go

@@ -229,14 +229,19 @@ func (rc *RunContext) containerDaemonSocket() string {
 	return rc.Config.ContainerDaemonSocket
 }
 
+const sharedToolCacheVolume = "act-toolcache" // mounted only when the tool cache is shared
+
 // validVolumes returns the volumes allowed on this job's containers: the configured base
 // plus the volumes the runner mounts automatically. It derives a fresh slice every call and
 // never mutates the shared Config (see containerDaemonSocket).
 func (rc *RunContext) validVolumes() []string {
 	name := rc.jobContainerName()
 	volumes := slices.Clone(rc.Config.ValidVolumes)
+	if rc.Config.SharedToolCache {
+		volumes = append(volumes, sharedToolCacheVolume)
+	}
 	// TODO: add a new configuration to control whether the docker daemon can be mounted
-	return append(volumes, "act-toolcache", name, name+"-env",
+	return append(volumes, name, name+"-env",
 		getDockerDaemonSocketMountPath(rc.containerDaemonSocket()))
 }
 
@@ -309,8 +314,10 @@ func (rc *RunContext) GetBindsAndMounts() ([]string, map[string]string) {
 	if daemonSocket := rc.containerDaemonSocket(); daemonSocket != "-" && !claimed["/var/run/docker.sock"] {
 		binds = append(binds, getDockerDaemonSocketMountPath(daemonSocket)+":/var/run/docker.sock")
 	}
-	if toolCache := rc.toolCache(container.DefaultToolCache); !claimed[toolCache] {
-		mounts["act-toolcache"] = toolCache
+	if rc.Config.SharedToolCache {
+		if toolCache := rc.toolCache(container.DefaultToolCache); !claimed[toolCache] {
+			mounts[sharedToolCacheVolume] = toolCache
+		}
 	}
 	mounts[name+"-env"] = ext.GetActPath() // runner-internal, never overridable
 
@@ -360,7 +367,11 @@ func (rc *RunContext) startHostEnvironment() common.Executor {
 		if err := os.MkdirAll(runnerTmp, 0o777); err != nil {
 			return err
 		}
-		toolCache := rc.toolCache(filepath.Join(cacheDir, "tool_cache"))
+		toolCacheParent := miscpath // per job, so cleanup removes it with the job
+		if rc.Config.SharedToolCache {
+			toolCacheParent = cacheDir
+		}
+		toolCache := rc.toolCache(filepath.Join(toolCacheParent, "tool_cache"))
 		if err := os.MkdirAll(toolCache, 0o777); err != nil {
 			return err
 		}

act/runner/run_context_test.go

@@ -502,7 +502,8 @@ func TestRunContext_GetBindsAndMounts(t *testing.T) {
 						},
 					},
 					Config: &Config{
-						BindWorkdir: false,
+						BindWorkdir:     false,
+						SharedToolCache: true, // so OverridesToolCache has a mount to displace
 					},
 				}
 				rc.Run.JobID = "job1"
@@ -543,25 +544,44 @@ func TestRunContext_GetBindsAndMounts(t *testing.T) {
 			})
 		}
 	})
+
+	t.Run("ToolCacheMount", func(t *testing.T) {
+		rc := &RunContext{
+			Name:   "TestRCName",
+			Run:    &model.Run{Workflow: &model.Workflow{Name: "TestWorkflowName"}},
+			Config: &Config{},
+		}
+
+		_, gotmount := rc.GetBindsAndMounts()
+		assert.NotContains(t, gotmount, sharedToolCacheVolume)
+
+		rc.Config.SharedToolCache = true
+		_, gotmount = rc.GetBindsAndMounts()
+		assert.Equal(t, container.DefaultToolCache, gotmount[sharedToolCacheVolume])
+	})
 }
 
 func TestRunContextValidVolumes(t *testing.T) {
 	rc := &RunContext{
 		Name:   "job",
 		Run:    &model.Run{Workflow: &model.Workflow{Name: "wf"}},
-		Config: &Config{ValidVolumes: []string{"my-vol", "/host/path"}},
+		Config: &Config{ValidVolumes: []string{"my-vol", "/host/path"}, SharedToolCache: true},
 	}
 	name := rc.jobContainerName()
 
 	got := rc.validVolumes()
 
-	// the configured volumes plus the four the runner mounts automatically
-	assert.Subset(t, got, []string{"my-vol", "/host/path", "act-toolcache", name, name + "-env", "/var/run/docker.sock"})
+	// the configured volumes plus the ones the runner mounts automatically
+	assert.Subset(t, got, []string{"my-vol", "/host/path", sharedToolCacheVolume, name, name + "-env", "/var/run/docker.sock"})
 
 	// deriving the list must never mutate or grow the shared Config slice: parallel matrix
 	// combinations share one *Config, and the previous in-place append was a data race.
 	assert.Equal(t, []string{"my-vol", "/host/path"}, rc.Config.ValidVolumes)
 	assert.Len(t, rc.validVolumes(), len(got), "repeated calls must be stable, not accumulate")
+
+	// a job may mount it only while the runner does
+	rc.Config.SharedToolCache = false
+	assert.NotContains(t, rc.validVolumes(), sharedToolCacheVolume)
 }
 
 func TestCleanupJobResourcesCleansServicesWithoutJobContainer(t *testing.T) {

act/runner/runner.go

@@ -91,6 +91,7 @@ type Config struct {
 	PlatformPicker                    func(labels []string) string // platform picker, it will take precedence over Platforms if isn't nil
 	JobLoggerLevel                    *log.Level                   // the level of job logger
 	ValidVolumes                      []string                     // only volumes (and bind mounts) in this slice can be mounted on the job container or service containers
+	SharedToolCache                   bool                         // one tool cache for all jobs instead of one per job
 	InsecureSkipTLS                   bool                         // whether to skip verifying TLS certificate of the Gitea instance
 	MaxParallel                       int                          // max parallel jobs to run across all workflows (0 = no limit, uses CPU count)
 	AllocatePTY                       bool                         // allocate a pseudo-TTY for each step's process