fix: resolve symlinked container paths before building tar entries (#1130)

Docker 29.7 extracts copied archives through `os.Root`, which refuses to follow a symlink to an absolute target, so copying into `/var/run/act` fails with `path escapes from parent` on the many images that link `/var/run` to `/run`. The daemon now resolves every path component for us before any tar entry name is built, and the destination is created with one directory entry per missing component, which no daemon version rejects.

Verified against real daemons (29.4.0, 29.5.0, 29.5.1, 29.5.3, 29.6.2, 29.7.0-rc.1) with `debian:bookworm` (absolute symlink) and `alpine:3` (relative symlink), and against `moby/go-archive` v0.2.0 through the pending fix branch.

1. Fixes https://gitea.com/gitea/runner/issues/1128
1. Upstream bug: https://github.com/moby/moby/issues/53258
1. Supersedes the no-op change in https://gitea.com/gitea/runner/pulls/1129, which cannot help since the daemon strips leading slashes itself

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

.gitea/workflows/test.yml

@@ -33,6 +33,8 @@ jobs:
           done
       - name: lint
         run: make lint
+      - name: checks
+        run: make checks
       - name: build
         run: make build
       - name: test

.gitignore

@@ -2,6 +2,7 @@
 .env
 !/act/runner/testdata/secrets/.env
 .runner
+.runner.lock
 coverage.txt
 .tmp/
 /config.yaml

.golangci.yml

@@ -11,6 +11,7 @@ linters:
     - dupl
     - errcheck
     - forbidigo
+    - forcetypeassert
     - gocheckcompilerdirectives
     - gocritic
     - goheader
@@ -102,6 +103,9 @@ linters:
       - linters:
           - forbidigo
         path: cmd
+      - linters:
+          - forcetypeassert
+        path: _test\.go
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0

Makefile

@@ -4,9 +4,9 @@ DIST_DIRS := $(DIST)/binaries $(DIST)/release
 GO ?= go
 SHASUM ?= shasum -a 256
 HAS_GO = $(shell hash $(GO) > /dev/null 2>&1 && echo "GO" || echo "NOGO" )
-XGO_PACKAGE ?= src.techknowlogick.com/xgo@latest
+XGO_PACKAGE ?= src.techknowlogick.com/xgo@v1.9.0 # renovate: datasource=go
 XGO_VERSION := go-1.26.x
-GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/gxz@v0.5.10
+GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/gxz@v0.5.15 # renovate: datasource=go
 
 LINUX_ARCHS ?= linux/amd64,linux/arm64
 DARWIN_ARCHS ?= darwin-12/amd64,darwin-12/arm64
@@ -18,8 +18,10 @@ DOCKER_TAG ?= nightly
 DOCKER_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)
 DOCKER_ROOTLESS_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)-dind-rootless
 
-GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
-GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.3.0
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 # renovate: datasource=go
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.3.0 # renovate: datasource=go
+
+GOTEST_FLAGS ?= -race -timeout 20m -parallel 8
 
 STATIC ?=
 EXTLDFLAGS ?=
@@ -95,7 +97,7 @@ go-check:
 
 .PHONY: fmt-check
 fmt-check: fmt
-	@diff=$$(git diff --color=always); \
+	@diff=$$(git diff --color=always -- '*.go'); \
 	if [ -n "$$diff" ]; then \
 		echo "Please run 'make fmt' and commit the result:"; \
 		printf "%s" "$${diff}"; \
@@ -110,6 +112,9 @@ deps-tools: ## install tool dependencies
 	$(GO) install $(GOVULNCHECK_PACKAGE) & \
 	wait
 
+.PHONY: checks
+checks: tidy-check fmt-check security-check ## run the non-lint source checks
+
 .PHONY: lint
 lint: lint-go lint-go-windows ## lint everything
 
@@ -131,7 +136,7 @@ lint-pr-title: ## lint PR title against Conventional Commits (set PR_TITLE=...)
 	@node ./tools/lint-pr-title.ts
 
 .PHONY: security-check
-security-check: deps-tools
+security-check:
 	GOEXPERIMENT= $(GO) run $(GOVULNCHECK_PACKAGE) -show color ./... || true
 
 .PHONY: tidy
@@ -148,8 +153,8 @@ tidy-check: tidy
 	fi
 
 .PHONY: test
-test: fmt-check security-check ## test everything (integration tests self-skip without docker/network)
-	@$(GO) test -race -timeout 20m -v -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
+test: ## test everything (integration tests self-skip without docker/network)
+	@$(GO) test $(GOTEST_FLAGS) -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
 
 .PHONY: coverage-report
 coverage-report: ## turn coverage.txt from `make test` into .tmp/coverage.md

README.md

@@ -209,10 +209,50 @@ Whenever the resulting labels differ from the ones in the registration file, the
 
 > **Note:** A runner that only exposes `host` labels still needs access to a Docker daemon (e.g. a mounted `/var/run/docker.sock`) whenever a job uses a `docker://` action or a service container. `host` labels only change where the job's own steps run; container-based steps and actions are still executed with Docker.
 
+#### Proxy
+
+Set these variables in the runner's environment, with systemd `Environment=`, `docker run -e`, or Kubernetes `env:`:
+
+```sh
+http_proxy=http://proxy.example:3128
+https_proxy=http://proxy.example:3128
+no_proxy=gitea.internal,.example.local
+```
+
+The runner uses them for its own requests and gives them to every job, in lower and upper case.
+
+These hosts are added to `no_proxy` for jobs, so they are always reached directly:
+
+- the cache server
+- `localhost`, `127.0.0.1` and `::1`
+- the job's service containers
+- the Docker daemon, when it is reached over `tcp://`
+
+Gitea is not added. Add it to `no_proxy` yourself if it should be reached directly.
+
+To change a value for one job, set it in a step's `env:` or in the job's `container.env`. Setting it at workflow or job level has no effect. To change it for the whole runner, set it in `runner.envs`. A `no_proxy` set there is added to the list above instead of replacing it.
+
+Images are pulled by the Docker daemon, which needs its own proxy setting. In the `dind` images the daemon runs in the same container and reads the variables above. For any other daemon, see [the Docker documentation](https://docs.docker.com/engine/daemon/proxy/). The runner logs a warning at startup if it has a proxy and the daemon does not.
+
+Dockerfile actions are built with these variables as build arguments, so their `RUN` steps can reach the network.
+
+A password in a proxy URL is hidden in job logs. Any step can still read it, because the step is given the proxy URL in its environment.
+
 #### Caching (`actions/cache`)
 
 Each runner starts its own cache server automatically. Cache entries are local to that runner — runners do not share a cache by default.
 
+**Cache service v2**
+
+`actions/cache@v4.2` and later can use the *cache service v2* API. The runner serves it from the same store as v1, on by default, and it works with `external_server`. Turn it off with:
+
+```yaml
+cache:
+  v2: false
+```
+
+Those actions refuse any host they do not take for GitHub. Rather than misreport the server URL, the runner edits that check out of the action's own bundle and keeps the untouched copy beside it; a bundle it does not recognise is left alone and keeps to v1. The same edit lets the stock `actions/upload-artifact` and `actions/download-artifact` work from `v4.4.0` on, without the `gitea-upload-artifact` fork.
+
 **Shared cache across multiple runners**
 
 Run one dedicated `gitea-runner cache-server` that all runners point at.
@@ -254,11 +294,12 @@ Besides `GITEA_INSTANCE_URL` and `GITEA_RUNNER_REGISTRATION_TOKEN`, the image en
 
 For a fuller container-oriented walkthrough, see [examples/docker](examples/docker/README.md).
 
-When `container.bind_workdir` is enabled, stale task workspace directories can be cleaned while the runner is idle:
-- directories older than `runner.workdir_cleanup_age` are removed (default: `24h`; set `0` to disable)
-- cleanup runs every `runner.idle_cleanup_interval` (default: `10m`; set `0` to disable)
+While the runner is idle it cleans up after earlier jobs:
+- when `container.bind_workdir` is enabled, stale task workspace directories older than `runner.workdir_cleanup_age` are removed (default: `24h`; set `0` to disable)
 - only purely numeric subdirectories under `container.workdir_parent` are treated as task workspaces and may be removed
 - cleanup assumes `container.workdir_parent` is not shared across multiple runners
+- on runners that use docker, per-job networks left behind by jobs the runner did not live to tear down are removed, identified by the `com.gitea.runner.uuid` label carrying this runner's uuid
+- cleanup runs every `runner.idle_cleanup_interval` (default: `10m`; set `0` to disable), and setting either knob to `0` disables all of the above
 
 #### Post-task script (`runner.post_task_script`)
 
@@ -270,6 +311,16 @@ On Windows, use `.exe`, `.bat`, or `.cmd` paths; **PowerShell (`.ps1`) is not su
 
 See **[docs/post-task-script.md](docs/post-task-script.md)** for lifecycle details, environment variables, timeout interaction, and platform notes.
 
+#### Job hooks (`runner.hooks.job_started`, `runner.hooks.job_completed`)
+
+Optional scripts that run **inside the job environment** (the job container, or the host in host mode), before the job's first step and after its last one. They are the equivalent of GitHub's `ACTIONS_RUNNER_HOOK_JOB_STARTED` / `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`, which are read when the settings are unset.
+
+Because they run where the steps run and see the job's environment, they are the place for per-job setup no workflow should have to carry: registry logins, mirror configuration, or masking runner-wide secrets with `::add-mask::`. Their output is part of the job log and is scanned for workflow commands, and they can export to the job through `$GITHUB_ENV` and `$GITHUB_PATH`.
+
+Both hooks are synchronous and block the job while they run. Either one exiting non-zero fails the job, and there is no per-hook timeout.
+
+See **[docs/job-hooks.md](docs/job-hooks.md)** for the execution order, environment, and platform notes.
+
 ### Example Deployments
 
 Check out the [examples](examples) directory for sample deployment types.

act/artifactcache/handler.go

@@ -70,6 +70,7 @@ type Handler struct {
 	storage  *Storage
 	router   *httprouter.Router
 	listener net.Listener
+	port     int
 	server   *http.Server
 	logger   logrus.FieldLogger
 
@@ -157,12 +158,13 @@ func StartHandler(dir, outboundIP string, port uint16, internalSecret string, lo
 	router.POST(apiPath+"/clean", h.bearerAuth(h.clean))
 	// Artifact GET is signed via query-string HMAC because @actions/cache
 	// does not attach Authorization when downloading archiveLocation.
-	router.GET(apiPath+"/artifacts/:id", h.signedURLAuth(h.get))
+	router.GET(apiPath+"/artifacts/:id", h.signedAuth("", h.get))
 	// Control-plane: a remote runner registers/revokes per-job tokens so the
 	// cache API can authenticate them. Always wired so the routes exist; the
 	// handlers themselves 401 when internalSecret is unset.
 	router.POST(internalPath+"/register", h.internalAuth(h.internalRegister))
 	router.POST(internalPath+"/revoke", h.internalAuth(h.internalRevoke))
+	h.registerV2Routes(router)
 
 	h.router = router
 
@@ -177,6 +179,12 @@ func StartHandler(dir, outboundIP string, port uint16, internalSecret string, lo
 	if err != nil {
 		return nil, err
 	}
+	addr, ok := listener.Addr().(*net.TCPAddr)
+	if !ok {
+		listener.Close()
+		return nil, fmt.Errorf("cache server listens on %T, want a TCP address", listener.Addr())
+	}
+	h.port = addr.Port
 	server := &http.Server{
 		ReadHeaderTimeout: 2 * time.Second,
 		Handler:           router,
@@ -194,9 +202,7 @@ func StartHandler(dir, outboundIP string, port uint16, internalSecret string, lo
 
 func (h *Handler) ExternalURL() string {
 	// TODO: make the external url configurable if necessary
-	return fmt.Sprintf("http://%s:%d",
-		h.outboundIP,
-		h.listener.Addr().(*net.TCPAddr).Port)
+	return fmt.Sprintf("http://%s:%d", h.outboundIP, h.port)
 }
 
 // RegisterJob makes token a valid bearer credential for cache requests from
@@ -334,7 +340,7 @@ func (h *Handler) find(w http.ResponseWriter, r *http.Request, _ httprouter.Para
 	}
 	defer db.Close()
 
-	cache, err := findCache(db, cred.Repo, keys, version)
+	cache, err := h.lookupCache(db, cred.Repo, keys, version)
 	if err != nil {
 		h.responseJSON(w, r, 500, err)
 		return
@@ -343,15 +349,6 @@ func (h *Handler) find(w http.ResponseWriter, r *http.Request, _ httprouter.Para
 		h.responseJSON(w, r, 204)
 		return
 	}
-
-	if ok, err := h.storage.Exist(cache.ID); err != nil {
-		h.responseJSON(w, r, 500, err)
-		return
-	} else if !ok {
-		_ = db.Delete(cache.ID, cache)
-		h.responseJSON(w, r, 204)
-		return
-	}
 	h.responseJSON(w, r, 200, map[string]any{
 		"result":          "hit",
 		"archiveLocation": h.signedArtifactURL(cache.ID, time.Now().Add(artifactURLTTL)),
@@ -359,6 +356,25 @@ func (h *Handler) find(w http.ResponseWriter, r *http.Request, _ httprouter.Para
 	})
 }
 
+// lookupCache returns the entry to restore for these keys, or (nil, nil) when there is none:
+// either nothing matched, or the match had lost its blob to a prune, in which case the dangling
+// entry is dropped on the way out.
+func (h *Handler) lookupCache(db *bolthold.Store, repo string, keys []string, version string) (*Cache, error) {
+	cache, err := findCache(db, repo, keys, version)
+	if err != nil || cache == nil {
+		return nil, err
+	}
+	ok, err := h.storage.Exist(cache.ID)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		_ = db.Delete(cache.ID, cache)
+		return nil, nil //nolint:nilnil // absence is not an error here
+	}
+	return cache, nil
+}
+
 // POST /_apis/artifactcache/caches
 func (h *Handler) reserve(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
 	cred := credFromContext(r.Context())
@@ -433,7 +449,7 @@ func (h *Handler) upload(w http.ResponseWriter, r *http.Request, params httprout
 		h.responseJSON(w, r, 500, err)
 		return
 	}
-	h.useCache(id)
+	_ = h.touchCache(uint64(id), false)
 	h.responseJSON(w, r, 200)
 }
 
@@ -474,23 +490,7 @@ func (h *Handler) commit(w http.ResponseWriter, r *http.Request, params httprout
 
 	db.Close()
 
-	size, err := h.storage.Commit(cache.ID, cache.Size)
-	if err != nil {
-		h.responseJSON(w, r, 500, err)
-		return
-	}
-	// write real size back to cache, it may be different from the current value when the request doesn't specify it.
-	cache.Size = size
-
-	db, err = h.openDB()
-	if err != nil {
-		h.responseJSON(w, r, 500, err)
-		return
-	}
-	defer db.Close()
-
-	cache.Complete = true
-	if err := db.Update(cache.ID, cache); err != nil {
+	if err := h.commitCache(cache); err != nil {
 		h.responseJSON(w, r, 500, err)
 		return
 	}
@@ -498,8 +498,28 @@ func (h *Handler) commit(w http.ResponseWriter, r *http.Request, params httprout
 	h.responseJSON(w, r, 200)
 }
 
+// commitCache assembles the uploaded parts and marks the entry complete. The caller must
+// have closed its store first: Commit concatenates the whole archive and would otherwise
+// hold bolt's exclusive file lock for the duration.
+func (h *Handler) commitCache(cache *Cache) error {
+	written, err := h.storage.Commit(cache.ID, cache.Size)
+	if err != nil {
+		return err
+	}
+	// write real size back to cache, it may be different from the current value when the request doesn't specify it.
+	cache.Size = written
+	cache.Complete = true
+
+	db, err := h.openDB()
+	if err != nil {
+		return err
+	}
+	defer db.Close()
+	return db.Update(cache.ID, cache)
+}
+
 // GET /_apis/artifactcache/artifacts/:id
-// Authenticated via signed URL (see signedURLAuth), not bearer, because the
+// Authenticated via signed URL (see signedAuth), not bearer, because the
 // @actions/cache toolkit downloads archiveLocation without Authorization.
 // Repository scoping is already enforced at find() time; the signature binds
 // the URL to the specific cache ID and an expiry.
@@ -509,7 +529,7 @@ func (h *Handler) get(w http.ResponseWriter, r *http.Request, params httprouter.
 		h.responseJSON(w, r, 400, err)
 		return
 	}
-	h.useCache(id)
+	_ = h.touchCache(uint64(id), false)
 	h.storage.Serve(w, r, uint64(id))
 }
 
@@ -543,7 +563,9 @@ func (h *Handler) bearerAuth(handler httprouter.Handle) httprouter.Handle {
 	}
 }
 
-func (h *Handler) signedURLAuth(handler httprouter.Handle) httprouter.Handle {
+// signedAuth authenticates a signed URL. purpose separates the flavours of URL the
+// handler hands out, so one cannot be replayed as another; see computeSignature.
+func (h *Handler) signedAuth(purpose string, handler httprouter.Handle) httprouter.Handle {
 	return func(w http.ResponseWriter, r *http.Request, params httprouter.Params) {
 		h.logger.Debugf("%s %s", r.Method, r.URL.Path)
 		id, err := strconv.ParseInt(params.ByName("id"), 10, 64)
@@ -566,7 +588,7 @@ func (h *Handler) signedURLAuth(handler httprouter.Handle) httprouter.Handle {
 			h.responseJSON(w, r, http.StatusUnauthorized, errors.New("signature expired"))
 			return
 		}
-		expected := h.computeSignature(id, exp)
+		expected := h.computeSignature(purpose, id, exp)
 		if !hmac.Equal([]byte(sig), []byte(expected)) {
 			h.responseJSON(w, r, http.StatusUnauthorized, errors.New("bad signature"))
 			return
@@ -650,19 +672,26 @@ func credFromContext(ctx context.Context) JobCredential {
 	return JobCredential{}
 }
 
-func (h *Handler) computeSignature(cacheID, exp int64) string {
+// computeSignature signs a URL for one cache entry and expiry. purpose is mixed into the
+// message so a URL handed out for writing an entry cannot be replayed to read one, and the
+// other way round. Downloads use the empty purpose, the message v1 has always signed.
+func (h *Handler) computeSignature(purpose string, cacheID, exp int64) string {
 	mac := hmac.New(sha256.New, h.secret)
-	fmt.Fprintf(mac, "%d:%d", cacheID, exp)
+	fmt.Fprintf(mac, "%s%d:%d", purpose, cacheID, exp)
 	return hex.EncodeToString(mac.Sum(nil))
 }
 
-func (h *Handler) signedArtifactURL(cacheID uint64, exp time.Time) string {
+// signedURL builds a URL under path that signedAuth accepts for the same purpose.
+func (h *Handler) signedURL(path, purpose string, cacheID uint64, exp time.Time) string {
 	expUnix := exp.Unix()
-	sig := h.computeSignature(int64(cacheID), expUnix)
 	q := url.Values{}
 	q.Set("exp", strconv.FormatInt(expUnix, 10))
-	q.Set("sig", sig)
-	return fmt.Sprintf("%s%s/artifacts/%d?%s", h.ExternalURL(), apiPath, cacheID, q.Encode())
+	q.Set("sig", h.computeSignature(purpose, int64(cacheID), expUnix))
+	return fmt.Sprintf("%s%s/%d?%s", h.ExternalURL(), path, cacheID, q.Encode())
+}
+
+func (h *Handler) signedArtifactURL(cacheID uint64, exp time.Time) string {
+	return h.signedURL(apiPath+"/artifacts", "", cacheID, exp)
 }
 
 // if not found, return (nil, nil) instead of an error.
@@ -670,16 +699,12 @@ func findCache(db *bolthold.Store, repo string, keys []string, version string) (
 	cache := &Cache{}
 	for _, prefix := range keys {
 		// if a key in the list matches exactly, don't return partial matches
-		if err := db.FindOne(cache,
-			bolthold.Where("Repo").Eq(repo).
-				And("Key").Eq(prefix).
-				And("Version").Eq(version).
-				And("Complete").Eq(true).
-				SortBy("CreatedAt").Reverse()); err == nil || !errors.Is(err, bolthold.ErrNotFound) {
-			if err != nil {
-				return nil, fmt.Errorf("find cache: %w", err)
-			}
-			return cache, nil
+		exact, err := findExactCache(db, repo, prefix, version, true)
+		if err != nil {
+			return nil, err
+		}
+		if exact != nil {
+			return exact, nil
 		}
 		prefixPattern := "^" + regexp.QuoteMeta(prefix)
 		re, err := regexp.Compile(prefixPattern)
@@ -702,6 +727,34 @@ func findCache(db *bolthold.Store, repo string, keys []string, version string) (
 	return nil, nil //nolint:nilnil // pre-existing issue from nektos/act
 }
 
+// findExactCache returns the entry for exactly this key and version, or (nil, nil) if there is
+// none. Unlike findCache it never falls back to a prefix (restore-key) match, which is what both
+// its callers need: a new key that is only a prefix of an existing key is not the same entry.
+//
+// A completed entry is the one to restore, sorted by when it was written. An incomplete one is a
+// reservation being uploaded to, sorted by when it was last written to, because the upload route
+// touches UsedAt on every part.
+func findExactCache(db *bolthold.Store, repo, key, version string, complete bool) (*Cache, error) {
+	sortBy := "UsedAt"
+	if complete {
+		sortBy = "CreatedAt"
+	}
+	cache := &Cache{}
+	err := db.FindOne(cache,
+		bolthold.Where("Repo").Eq(repo).
+			And("Key").Eq(key).
+			And("Version").Eq(version).
+			And("Complete").Eq(complete).
+			SortBy(sortBy).Reverse())
+	if errors.Is(err, bolthold.ErrNotFound) {
+		return nil, nil //nolint:nilnil // absence is not an error here
+	}
+	if err != nil {
+		return nil, fmt.Errorf("find cache: %w", err)
+	}
+	return cache, nil
+}
+
 func insertCache(db *bolthold.Store, cache *Cache) error {
 	if err := db.Insert(bolthold.NextSequence(), cache); err != nil {
 		return fmt.Errorf("insert cache: %w", err)
@@ -713,18 +766,30 @@ func insertCache(db *bolthold.Store, cache *Cache) error {
 	return nil
 }
 
-func (h *Handler) useCache(id int64) {
+// touchCache stamps UsedAt so gcCache does not reap an entry mid-upload. With requireIncomplete
+// it also refuses an entry that is already complete, which is what the v2 blob route needs: its
+// upload URL outlives the finalize call, and overwriting a finished entry would leave the blob
+// other jobs restore no longer matching its recorded size. An entry missing from the store is
+// accepted, since the signature proves the id was handed out.
+func (h *Handler) touchCache(id uint64, requireIncomplete bool) error {
 	db, err := h.openDB()
 	if err != nil {
-		return
+		return err
 	}
 	defer db.Close()
+
 	cache := &Cache{}
 	if err := db.Get(id, cache); err != nil {
-		return
+		if errors.Is(err, bolthold.ErrNotFound) {
+			return nil
+		}
+		return err
+	}
+	if requireIncomplete && cache.Complete {
+		return fmt.Errorf("cache %d: already complete", id)
 	}
 	cache.UsedAt = time.Now().Unix()
-	_ = db.Update(cache.ID, cache)
+	return db.Update(cache.ID, cache)
 }
 
 const (

act/artifactcache/handler_test.go

@@ -445,13 +445,6 @@ func TestHandler(t *testing.T) {
 		require.Equal(t, 404, resp.StatusCode)
 	})
 
-	t.Run("get with not exist id", func(t *testing.T) {
-		resp, err := testClient.Get(signArtifactURL(handler, 100))
-		require.NoError(t, err)
-		defer resp.Body.Close()
-		require.Equal(t, 404, resp.StatusCode)
-	})
-
 	t.Run("get with multiple keys", func(t *testing.T) {
 		version := "c19da02a2bd7e77277f1ac29ab45c09b7d46a4ee758284e26bb3045ad11d9d20"
 		key := strings.ToLower(t.Name())
@@ -469,7 +462,8 @@ func TestHandler(t *testing.T) {
 			_, err := rand.Read(contents[i])
 			require.NoError(t, err)
 			uploadCacheNormally(t, base, keys[i], version, contents[i])
-			time.Sleep(time.Second) // ensure CreatedAt of caches are different
+			// ensure CreatedAt of caches are different, in upload order
+			backdateCache(t, handler, keys[i], time.Duration(len(contents)-i)*time.Second)
 		}
 
 		reqKeys := strings.Join([]string{
@@ -554,7 +548,8 @@ func TestHandler(t *testing.T) {
 			_, err := rand.Read(contents[i])
 			require.NoError(t, err)
 			uploadCacheNormally(t, base, keys[i], version, contents[i])
-			time.Sleep(time.Second) // ensure CreatedAt of caches are different
+			// ensure CreatedAt of caches are different, in upload order
+			backdateCache(t, handler, keys[i], time.Duration(len(contents)-i)*time.Second)
 		}
 
 		reqKeys := strings.Join([]string{
@@ -607,7 +602,8 @@ func TestHandler(t *testing.T) {
 			_, err := rand.Read(contents[i])
 			require.NoError(t, err)
 			uploadCacheNormally(t, base, keys[i], version, contents[i])
-			time.Sleep(time.Second) // ensure CreatedAt of caches are different
+			// ensure CreatedAt of caches are different, in upload order
+			backdateCache(t, handler, keys[i], time.Duration(len(contents)-i)*time.Second)
 		}
 
 		reqKeys := strings.Join([]string{
@@ -646,6 +642,20 @@ func TestHandler(t *testing.T) {
 	})
 }
 
+// backdateCache rewrites a cache's CreatedAt. It has one-second resolution, so age-ordering
+// tests set it directly instead of sleeping a second between uploads.
+func backdateCache(t *testing.T, handler *Handler, key string, age time.Duration) {
+	db, err := handler.openDB()
+	require.NoError(t, err)
+	defer db.Close()
+
+	var caches []*Cache
+	require.NoError(t, db.Find(&caches, bolthold.Where("Key").Eq(key)))
+	require.Len(t, caches, 1)
+	caches[0].CreatedAt = time.Now().Add(-age).Unix()
+	require.NoError(t, db.Update(caches[0].ID, caches[0]))
+}
+
 func uploadCacheNormally(t *testing.T, base, key, version string, content []byte) { //nolint:unparam // pre-existing issue from nektos/act
 	var id uint64
 	{
@@ -1031,14 +1041,14 @@ func TestHandler_SecretPersistsAcrossRestarts(t *testing.T) {
 	first, err := StartHandler(dir, "127.0.0.1", 0, "", nil)
 	require.NoError(t, err)
 	exp := time.Now().Add(artifactURLTTL).Unix()
-	sig := first.computeSignature(42, exp)
+	sig := first.computeSignature("", 42, exp)
 	require.NoError(t, first.Close())
 
 	second, err := StartHandler(dir, "127.0.0.1", 0, "", nil)
 	require.NoError(t, err)
 	defer second.Close()
 
-	assert.Equal(t, sig, second.computeSignature(42, exp))
+	assert.Equal(t, sig, second.computeSignature("", 42, exp))
 }
 
 // TestHandler_ArtifactSignatureDownload is a happy-path round trip that

act/artifactcache/handler_v2.go

@@ -0,0 +1,268 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifactcache
+
+import (
+	"cmp"
+	"encoding/json"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/julienschmidt/httprouter"
+)
+
+// The cache service v2 API. A client on this version talks twirp to
+// `github.actions.results.api.v1.CacheService` instead of the /_apis/artifactcache
+// endpoints, and uploads the archive to the returned URL with the Azure blob protocol.
+// Both API versions are served from the same store, so a repository keeps its cache
+// when a workflow moves between action versions.
+const (
+	cacheServiceV2Path = "/twirp/github.actions.results.api.v1.CacheService"
+
+	// blobPath authenticates by signature, because the client uploads without an
+	// Authorization header. Downloads are handed the v1 artifact URL instead.
+	blobPath = apiPath + "/blobs"
+
+	// blobUploadPurpose keeps an upload URL from being replayed to read an entry.
+	blobUploadPurpose = "upload:"
+
+	blobUploadURLTTL = time.Hour
+
+	// twirpInternal is the only error code that is not the client's fault.
+	twirpInternal = "internal"
+)
+
+func (h *Handler) registerV2Routes(router *httprouter.Router) {
+	router.POST(cacheServiceV2Path+"/CreateCacheEntry", h.bearerAuth(h.v2CreateCacheEntry))
+	router.POST(cacheServiceV2Path+"/FinalizeCacheEntryUpload", h.bearerAuth(h.v2FinalizeCacheEntryUpload))
+	router.POST(cacheServiceV2Path+"/GetCacheEntryDownloadURL", h.bearerAuth(h.v2GetCacheEntryDownloadURL))
+	router.PUT(blobPath+"/:id", h.signedAuth(blobUploadPurpose, h.v2UploadBlob))
+}
+
+// An entry that already exists is reported as not ok, which is how the client learns to skip
+// the upload.
+func (h *Handler) v2CreateCacheEntry(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
+	cred := credFromContext(r.Context())
+	req, err := decodeTwirpRequest[v2CreateRequest](r)
+	if err != nil {
+		h.twirpError(w, r, "malformed_request", err)
+		return
+	}
+	if req.Key == "" || req.Version == "" {
+		h.twirpError(w, r, "invalid_argument", errors.New("key and version are required"))
+		return
+	}
+
+	db, err := h.openDB()
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	defer db.Close()
+
+	// An exact (key, version) match means the entry is already cached; the client then skips
+	// the upload. A prefix match must not count here, or a shorter key would be reported as
+	// existing and silently never saved.
+	if existing, err := findExactCache(db, cred.Repo, req.Key, req.Version, true); err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	} else if existing != nil {
+		h.twirpNotOK(w, r)
+		return
+	}
+
+	now := time.Now().Unix()
+	cache := &Cache{
+		Repo:      cred.Repo,
+		Key:       req.Key,
+		Version:   req.Version,
+		Size:      -1, // the size is only known at finalize time
+		CreatedAt: now,
+		UsedAt:    now,
+	}
+	if err := insertCache(db, cache); err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+
+	h.responseJSON(w, r, http.StatusOK, map[string]any{
+		"ok":              true,
+		"signedUploadUrl": h.signedURL(blobPath, blobUploadPurpose, cache.ID, time.Now().Add(blobUploadURLTTL)),
+	})
+}
+
+func (h *Handler) v2FinalizeCacheEntryUpload(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
+	cred := credFromContext(r.Context())
+	req, err := decodeTwirpRequest[v2FinalizeRequest](r)
+	if err != nil {
+		h.twirpError(w, r, "malformed_request", err)
+		return
+	}
+
+	db, err := h.openDB()
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	defer db.Close()
+
+	cache, err := findExactCache(db, cred.Repo, req.Key, req.Version, false)
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	if cache == nil {
+		h.twirpNotOK(w, r)
+		return
+	}
+	db.Close() // commitCache needs the store closed
+
+	cache.Size, _ = cmp.Or(req.SizeBytes, req.SizeBytesCamel).Int64()
+	if err := h.commitCache(cache); err != nil {
+		h.logger.Errorf("finalize cache %d (%s): %v", cache.ID, cache.Key, err)
+		h.twirpNotOK(w, r)
+		return
+	}
+
+	h.responseJSON(w, r, http.StatusOK, map[string]any{
+		"ok": true,
+		// int64 fields travel as strings in the proto JSON mapping.
+		"entryId": strconv.FormatUint(cache.ID, 10),
+	})
+}
+
+func (h *Handler) v2GetCacheEntryDownloadURL(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
+	cred := credFromContext(r.Context())
+	req, err := decodeTwirpRequest[v2DownloadRequest](r)
+	if err != nil {
+		h.twirpError(w, r, "malformed_request", err)
+		return
+	}
+
+	db, err := h.openDB()
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	defer db.Close()
+
+	cache, err := h.lookupCache(db, cred.Repo, req.keys(), req.Version)
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	if cache == nil {
+		h.twirpNotOK(w, r)
+		return
+	}
+
+	h.responseJSON(w, r, http.StatusOK, map[string]any{
+		"ok":                true,
+		"signedDownloadUrl": h.signedArtifactURL(cache.ID, time.Now().Add(artifactURLTTL)),
+		"matchedKey":        cache.Key,
+	})
+}
+
+// The archive arrives over the subset of the Azure blob API the toolkit uses: a small
+// cache is a single PUT, a large one is staged as blocks that a final block list puts
+// in order.
+func (h *Handler) v2UploadBlob(w http.ResponseWriter, r *http.Request, params httprouter.Params) {
+	id, err := strconv.ParseUint(params.ByName("id"), 10, 64)
+	if err != nil {
+		h.responseJSON(w, r, http.StatusBadRequest, err)
+		return
+	}
+
+	if err := h.touchCache(id, true); err != nil {
+		h.responseJSON(w, r, http.StatusBadRequest, err)
+		return
+	}
+
+	query := r.URL.Query()
+	switch strings.ToLower(query.Get("comp")) {
+	case "block":
+		blockID := query.Get("blockid")
+		if blockID == "" {
+			h.responseJSON(w, r, http.StatusBadRequest, errors.New("missing blockid"))
+			return
+		}
+		err = h.storage.WriteBlock(id, blockID, r.Body)
+	case "blocklist":
+		var list struct{ Latest []string }
+		if err := xml.NewDecoder(io.LimitReader(r.Body, 8<<20)).Decode(&list); err != nil {
+			h.responseJSON(w, r, http.StatusBadRequest, fmt.Errorf("malformed block list: %w", err))
+			return
+		}
+		err = h.storage.OrderBlocks(id, list.Latest)
+	default:
+		err = h.storage.Write(id, 0, r.Body)
+	}
+	if err != nil {
+		h.responseJSON(w, r, http.StatusInternalServerError, err)
+		return
+	}
+
+	w.WriteHeader(http.StatusCreated)
+}
+
+// twirpNotOK is the negative answer all three endpoints share: no such entry to restore, no
+// reservation to finalize, or an entry that already exists and need not be uploaded again.
+func (h *Handler) twirpNotOK(w http.ResponseWriter, r *http.Request) {
+	h.responseJSON(w, r, http.StatusOK, map[string]any{"ok": false})
+}
+
+// twirpError reports in the shape a twirp client expects, so the toolkit surfaces the message
+// instead of a parse error.
+func (h *Handler) twirpError(w http.ResponseWriter, r *http.Request, code string, err error) {
+	h.logger.Debugf("%s %s: %v", r.Method, r.URL.Path, err)
+	status := http.StatusBadRequest
+	if code == twirpInternal {
+		status = http.StatusInternalServerError
+	}
+	h.responseJSON(w, r, status, map[string]any{"code": code, "msg": err.Error()})
+}
+
+// The twirp request bodies. The toolkit's client serialises with useProtoFieldName, so the proto
+// names are what arrive; the camelCase spellings of the same mapping are accepted too, as are
+// int64s sent as a bare number rather than the string the mapping prescribes.
+type (
+	v2CreateRequest struct {
+		Key     string `json:"key"`
+		Version string `json:"version"`
+	}
+
+	v2FinalizeRequest struct {
+		Key            string      `json:"key"`
+		Version        string      `json:"version"`
+		SizeBytes      json.Number `json:"size_bytes"`
+		SizeBytesCamel json.Number `json:"sizeBytes"`
+	}
+
+	v2DownloadRequest struct {
+		Key              string   `json:"key"`
+		Version          string   `json:"version"`
+		RestoreKeys      []string `json:"restore_keys"`
+		RestoreKeysCamel []string `json:"restoreKeys"`
+	}
+)
+
+func (d v2DownloadRequest) keys() []string {
+	restoreKeys := d.RestoreKeys
+	if len(restoreKeys) == 0 {
+		restoreKeys = d.RestoreKeysCamel
+	}
+	return append([]string{d.Key}, restoreKeys...)
+}
+
+func decodeTwirpRequest[T any](r *http.Request) (T, error) {
+	var req T
+	err := json.NewDecoder(io.LimitReader(r.Body, 1<<20)).Decode(&req)
+	return req, err
+}

act/artifactcache/handler_v2_test.go

@@ -0,0 +1,236 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifactcache
+
+import (
+	"bytes"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"path/filepath"
+	"strconv"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// v2Call posts a twirp request to the cache service and returns the decoded response.
+// Field names are the proto ones, which is what the toolkit's client sends.
+func v2Call(t *testing.T, handler *Handler, client *http.Client, method string, request any) map[string]any {
+	t.Helper()
+
+	body, err := json.Marshal(request)
+	require.NoError(t, err)
+
+	resp, err := client.Post(handler.ExternalURL()+cacheServiceV2Path+"/"+method, "application/json", bytes.NewReader(body))
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	got := map[string]any{}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+	return got
+}
+
+// putBlob uploads to a signed URL and returns the status, so a test can assert a refusal.
+func putBlob(t *testing.T, url string, content []byte) int {
+	t.Helper()
+
+	req, err := http.NewRequestWithContext(t.Context(), http.MethodPut, url, bytes.NewReader(content))
+	require.NoError(t, err)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	return resp.StatusCode
+}
+
+func getURL(t *testing.T, url string) []byte {
+	t.Helper()
+
+	req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, url, nil)
+	require.NoError(t, err)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	return body
+}
+
+func startTestHandler(t *testing.T) *Handler {
+	t.Helper()
+
+	handler, err := StartHandler(filepath.Join(t.TempDir(), "artifactcache"), "127.0.0.1", 0, "", nil)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = handler.Close() })
+	handler.RegisterJob(testToken, testRepo)
+	return handler
+}
+
+// saveV2 runs the reserve/upload/finalize sequence and returns the finalize response along
+// with the upload URL it used.
+func saveV2(t *testing.T, handler *Handler, key, version string, content []byte) (finalized map[string]any, uploadURL string) {
+	t.Helper()
+
+	created := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": key, "version": version})
+	require.Equal(t, true, created["ok"])
+	uploadURL, _ = created["signedUploadUrl"].(string)
+	require.NotEmpty(t, uploadURL)
+	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL, content))
+
+	return v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+		"key": key, "version": version,
+		"size_bytes": strconv.Itoa(len(content)),
+	}), uploadURL
+}
+
+// The whole round trip an actions/cache v2 client makes, plus the guarantees on the signed
+// URLs it is handed: unsigned requests are refused, an upload URL cannot be replayed to read
+// or to replace a finalized entry.
+func TestCacheServiceV2RoundTrip(t *testing.T) {
+	handler := startTestHandler(t)
+	content := []byte("the cached archive")
+
+	unsigned := fmt.Sprintf("%s%s/1", handler.ExternalURL(), blobPath)
+	assert.Equal(t, http.StatusUnauthorized, putBlob(t, unsigned, content))
+
+	finalized, uploadURL := saveV2(t, handler, "deps-v1", "abc123", content)
+	require.Equal(t, true, finalized["ok"])
+	assert.NotEmpty(t, finalized["entryId"])
+
+	// The upload URL outlives the finalize call, so replaying it must not poison the entry,
+	// and it is an upload URL only: nothing reads a blob back through it.
+	assert.Equal(t, http.StatusBadRequest, putBlob(t, uploadURL, []byte("poisoned")))
+	resp, err := http.Get(uploadURL) //nolint:noctx // the URL is the server under test
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	assert.Equal(t, http.StatusMethodNotAllowed, resp.StatusCode)
+
+	got := v2Call(t, handler, testClient, "GetCacheEntryDownloadURL", map[string]any{"key": "deps-v1", "version": "abc123"})
+	require.Equal(t, true, got["ok"])
+	assert.Equal(t, "deps-v1", got["matchedKey"])
+	downloadURL, _ := got["signedDownloadUrl"].(string)
+	require.NotEmpty(t, downloadURL)
+	assert.Equal(t, content, getURL(t, downloadURL))
+}
+
+// A large archive is staged as blocks and only put in order by the final block list, so
+// blocks that arrive out of order must still be assembled the way the client asked.
+func TestCacheServiceV2BlockUpload(t *testing.T) {
+	handler := startTestHandler(t)
+
+	created := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "blocks", "version": "v1"})
+	uploadURL, _ := created["signedUploadUrl"].(string)
+	require.NotEmpty(t, uploadURL)
+
+	blocks := map[string][]byte{}
+	var order []string
+	for i, part := range []string{"hello ", "world", "!"} {
+		blockID := base64.StdEncoding.EncodeToString(fmt.Appendf(nil, "block-%d", i))
+		blocks[blockID] = []byte(part)
+		order = append(order, blockID)
+	}
+	// Upload in an order that is not the block list order.
+	for _, blockID := range []string{order[2], order[0], order[1]} {
+		require.Equal(t, http.StatusCreated, putBlob(t, uploadURL+"&comp=block&blockid="+blockID, blocks[blockID]))
+	}
+
+	var list bytes.Buffer
+	list.WriteString(`<?xml version="1.0" encoding="utf-8"?><BlockList>`)
+	for _, blockID := range order {
+		fmt.Fprintf(&list, "<Latest>%s</Latest>", blockID)
+	}
+	list.WriteString(`</BlockList>`)
+	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL+"&comp=blocklist", list.Bytes()))
+
+	finalized := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+		"key": "blocks", "version": "v1", "size_bytes": len("hello world!"),
+	})
+	require.Equal(t, true, finalized["ok"])
+
+	got := v2Call(t, handler, testClient, "GetCacheEntryDownloadURL", map[string]any{"key": "blocks", "version": "v1"})
+	require.Equal(t, true, got["ok"])
+	assert.Equal(t, "hello world!", string(getURL(t, got["signedDownloadUrl"].(string))))
+}
+
+func TestCacheServiceV2Lookups(t *testing.T) {
+	handler := startTestHandler(t)
+	saved, _ := saveV2(t, handler, "deps-abc", "v1", []byte("x"))
+	require.Equal(t, true, saved["ok"])
+
+	t.Run("reports a miss for an unknown key", func(t *testing.T) {
+		got := v2Call(t, handler, testClient, "GetCacheEntryDownloadURL", map[string]any{"key": "nothing", "version": "v1"})
+		assert.Equal(t, false, got["ok"])
+	})
+
+	// The toolkit serialises with the proto field names; the camelCase spellings of the same
+	// proto JSON mapping are accepted alongside them.
+	for _, field := range []string{"restore_keys", "restoreKeys"} {
+		t.Run("restore keys match by prefix, spelled "+field, func(t *testing.T) {
+			got := v2Call(t, handler, testClient, "GetCacheEntryDownloadURL", map[string]any{
+				"key": "deps-zzz", field: []string{"deps-"}, "version": "v1",
+			})
+			require.Equal(t, true, got["ok"])
+			assert.Equal(t, "deps-abc", got["matchedKey"])
+		})
+	}
+
+	t.Run("an existing entry is not reserved twice", func(t *testing.T) {
+		again := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "deps-abc", "version": "v1"})
+		assert.Equal(t, false, again["ok"])
+	})
+
+	// A key that is only a prefix of an existing one is a different entry, so the
+	// reservation check must be exact and not a restore-key prefix match, or the shorter
+	// key would be reported as existing and silently never saved.
+	t.Run("a prefix of an existing key is still reserved", func(t *testing.T) {
+		reserved := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "deps", "version": "v1"})
+		require.Equal(t, true, reserved["ok"])
+		assert.NotEmpty(t, reserved["signedUploadUrl"])
+	})
+
+	t.Run("finalizing without a reservation is not ok", func(t *testing.T) {
+		got := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+			"key": "never-reserved", "version": "v1", "size_bytes": 1,
+		})
+		assert.Equal(t, false, got["ok"])
+	})
+
+	// The size the client declares is what Commit validates the assembled archive against.
+	t.Run("finalizing with the wrong size is not ok", func(t *testing.T) {
+		created := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "wrong-size", "version": "v1"})
+		require.Equal(t, http.StatusCreated, putBlob(t, created["signedUploadUrl"].(string), []byte("four")))
+
+		got := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+			"key": "wrong-size", "version": "v1", "size_bytes": 99,
+		})
+		assert.Equal(t, false, got["ok"])
+	})
+
+	// Both API versions are served from one store, so an entry written through v2 is a hit for
+	// a v1 client asking for the same key and version.
+	t.Run("a v1 client sees an entry written through v2", func(t *testing.T) {
+		resp, err := testClient.Get(fmt.Sprintf("%s%s/cache?keys=deps-abc&version=v1", handler.ExternalURL(), apiPath))
+		require.NoError(t, err)
+		defer resp.Body.Close()
+		require.Equal(t, http.StatusOK, resp.StatusCode)
+
+		got := map[string]any{}
+		require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+		assert.Equal(t, "deps-abc", got["cacheKey"])
+		assert.NotEmpty(t, got["archiveLocation"])
+	})
+
+	// The cache of one repository must stay invisible to another, as it does for the v1 API.
+	t.Run("another repository sees nothing", func(t *testing.T) {
+		handler.RegisterJob("other-runtime-token", "other/repo")
+		otherClient := &http.Client{Transport: &bearerTransport{token: "other-runtime-token"}}
+
+		got := v2Call(t, handler, otherClient, "GetCacheEntryDownloadURL", map[string]any{"key": "deps-abc", "version": "v1"})
+		assert.Equal(t, false, got["ok"])
+	})
+}

act/artifactcache/storage.go

@@ -5,12 +5,15 @@
 package artifactcache
 
 import (
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
 	"io"
 	"net/http"
 	"os"
 	"path/filepath"
 	"strconv"
+	"strings"
 )
 
 type Storage struct {
@@ -37,7 +40,10 @@ func (s *Storage) Exist(id uint64) (bool, error) {
 }
 
 func (s *Storage) Write(id uint64, offset int64, reader io.Reader) error {
-	name := s.tempName(id, offset)
+	return s.writeFile(s.tempName(id, offset), reader)
+}
+
+func (s *Storage) writeFile(name string, reader io.Reader) error {
 	if err := os.MkdirAll(filepath.Dir(name), 0o755); err != nil {
 		return err
 	}
@@ -51,6 +57,26 @@ func (s *Storage) Write(id uint64, offset int64, reader io.Reader) error {
 	return err
 }
 
+func (s *Storage) WriteBlock(id uint64, blockID string, reader io.Reader) error {
+	return s.writeFile(s.blockName(id, blockID), reader)
+}
+
+// OrderBlocks renames the staged blocks into the order the block list gives. A block the list
+// does not name keeps its staged name, which is how Commit leaves it out, as Azure drops it. One
+// rename pass is safe because a staged name always carries blockFilePrefix and a target name
+// never does, so no rename can collide with a block not yet moved.
+func (s *Storage) OrderBlocks(id uint64, blockIDs []string) error {
+	for i, blockID := range blockIDs {
+		if err := os.Rename(s.blockName(id, blockID), s.tempName(id, int64(i))); err != nil {
+			if os.IsNotExist(err) {
+				return fmt.Errorf("block %q of cache %d was never uploaded: %w", blockID, id, err)
+			}
+			return err
+		}
+	}
+	return nil
+}
+
 func (s *Storage) Commit(id uint64, size int64) (int64, error) {
 	defer func() {
 		_ = os.RemoveAll(s.tempDir(id))
@@ -65,6 +91,31 @@ func (s *Storage) Commit(id uint64, size int64) (int64, error) {
 	if err := os.MkdirAll(filepath.Dir(name), 0o755); err != nil {
 		return 0, err
 	}
+	written, err := assemble(name, tempNames)
+	if err != nil {
+		return 0, err
+	}
+	// If size is less than 0, it means the size is unknown.
+	// We can't check the size of the file, just skip the check.
+	// It happens when the request comes from old versions of actions, like `actions/cache@v2`.
+	if size >= 0 && written != size {
+		_ = os.Remove(name)
+		return 0, fmt.Errorf("broken file: %v != %v", written, size)
+	}
+	return written, nil
+}
+
+// assemble concatenates the uploaded parts into name. A single part, which is what the v2 API
+// produces below the client's block threshold, is already the whole archive and is moved.
+func assemble(name string, tempNames []string) (int64, error) {
+	if len(tempNames) == 1 {
+		info, err := os.Stat(tempNames[0])
+		if err != nil {
+			return 0, err
+		}
+		return info.Size(), os.Rename(tempNames[0], name)
+	}
+
 	file, err := os.Create(name)
 	if err != nil {
 		return 0, err
@@ -84,16 +135,6 @@ func (s *Storage) Commit(id uint64, size int64) (int64, error) {
 		}
 		written += n
 	}
-
-	// If size is less than 0, it means the size is unknown.
-	// We can't check the size of the file, just skip the check.
-	// It happens when the request comes from old versions of actions, like `actions/cache@v2`.
-	if size >= 0 && written != size {
-		_ = file.Close()
-		_ = os.Remove(name)
-		return 0, fmt.Errorf("broken file: %v != %v", written, size)
-	}
-
 	return written, nil
 }
 
@@ -119,6 +160,17 @@ func (s *Storage) tempName(id uint64, offset int64) string {
 	return filepath.Join(s.tempDir(id), fmt.Sprintf("%016x", offset))
 }
 
+// blockFilePrefix marks a staged, not yet ordered block, so that tempNames can keep it out of
+// Commit's name-ordered concatenation.
+const blockFilePrefix = "block-"
+
+func (s *Storage) blockName(id uint64, blockID string) string {
+	// The block id is client-chosen (base64), so it is hashed rather than trusted as a
+	// path element.
+	sum := sha256.Sum256([]byte(blockID))
+	return filepath.Join(s.tempDir(id), blockFilePrefix+hex.EncodeToString(sum[:]))
+}
+
 func (s *Storage) tempNames(id uint64) ([]string, error) {
 	dir := s.tempDir(id)
 	files, err := os.ReadDir(dir)
@@ -127,7 +179,7 @@ func (s *Storage) tempNames(id uint64) ([]string, error) {
 	}
 	var names []string
 	for _, v := range files {
-		if !v.IsDir() {
+		if !v.IsDir() && !strings.HasPrefix(v.Name(), blockFilePrefix) {
 			names = append(names, filepath.Join(dir, v.Name()))
 		}
 	}

act/common/executor_max_parallel_test.go

@@ -1,89 +0,0 @@
-// Copyright 2026 The Gitea Authors. All rights reserved.
-// SPDX-License-Identifier: MIT
-
-package common
-
-import (
-	"context"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-)
-
-// Simple fast test that verifies max-parallel: 2 limits concurrency
-func TestMaxParallel2Quick(t *testing.T) {
-	ctx := context.Background()
-
-	var currentRunning atomic.Int32
-	var maxSimultaneous atomic.Int32
-
-	executors := make([]Executor, 4)
-	for i := range 4 {
-		executors[i] = func(ctx context.Context) error {
-			current := currentRunning.Add(1)
-
-			// Update max if needed
-			for {
-				maxValue := maxSimultaneous.Load()
-				if current <= maxValue || maxSimultaneous.CompareAndSwap(maxValue, current) {
-					break
-				}
-			}
-
-			time.Sleep(10 * time.Millisecond)
-			currentRunning.Add(-1)
-			return nil
-		}
-	}
-
-	err := NewParallelExecutor(2, executors...)(ctx)
-
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.LessOrEqual(t, maxSimultaneous.Load(), int32(2),
-		"Should not exceed max-parallel: 2")
-}
-
-// Test that verifies max-parallel: 1 enforces sequential execution
-func TestMaxParallel1Sequential(t *testing.T) {
-	ctx := context.Background()
-
-	var currentRunning atomic.Int32
-	var maxSimultaneous atomic.Int32
-	var executionOrder []int
-	var orderMutex sync.Mutex
-
-	executors := make([]Executor, 5)
-	for i := range 5 {
-		taskID := i
-		executors[i] = func(ctx context.Context) error {
-			current := currentRunning.Add(1)
-
-			// Track execution order
-			orderMutex.Lock()
-			executionOrder = append(executionOrder, taskID)
-			orderMutex.Unlock()
-
-			// Update max if needed
-			for {
-				maxValue := maxSimultaneous.Load()
-				if current <= maxValue || maxSimultaneous.CompareAndSwap(maxValue, current) {
-					break
-				}
-			}
-
-			time.Sleep(20 * time.Millisecond)
-			currentRunning.Add(-1)
-			return nil
-		}
-	}
-
-	err := NewParallelExecutor(1, executors...)(ctx)
-
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, int32(1), maxSimultaneous.Load(),
-		"max-parallel: 1 should only run 1 task at a time")
-	assert.Len(t, executionOrder, 5, "All 5 tasks should have executed")
-}

act/common/executor_parallel_advanced_test.go

@@ -1,221 +0,0 @@
-// Copyright 2026 The Gitea Authors. All rights reserved.
-// SPDX-License-Identifier: MIT
-
-package common
-
-import (
-	"context"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-)
-
-// TestMaxParallelJobExecution tests actual job execution with max-parallel
-func TestMaxParallelJobExecution(t *testing.T) {
-	t.Run("MaxParallel=1 Sequential", func(t *testing.T) {
-		var currentRunning atomic.Int32
-		var maxConcurrent int32
-		var executionOrder []int
-		var mu sync.Mutex
-
-		executors := make([]Executor, 5)
-		for i := range 5 {
-			taskID := i
-			executors[i] = func(ctx context.Context) error {
-				current := currentRunning.Add(1)
-
-				// Track max concurrent
-				for {
-					maxValue := atomic.LoadInt32(&maxConcurrent)
-					if current <= maxValue || atomic.CompareAndSwapInt32(&maxConcurrent, maxValue, current) {
-						break
-					}
-				}
-
-				mu.Lock()
-				executionOrder = append(executionOrder, taskID)
-				mu.Unlock()
-
-				time.Sleep(10 * time.Millisecond)
-				currentRunning.Add(-1)
-				return nil
-			}
-		}
-
-		ctx := context.Background()
-		err := NewParallelExecutor(1, executors...)(ctx)
-		assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-
-		assert.Equal(t, int32(1), maxConcurrent, "Should never exceed 1 concurrent execution")
-		assert.Len(t, executionOrder, 5, "All tasks should execute")
-	})
-
-	t.Run("MaxParallel=3 Limited", func(t *testing.T) {
-		var currentRunning atomic.Int32
-		var maxConcurrent int32
-
-		executors := make([]Executor, 10)
-		for i := range 10 {
-			executors[i] = func(ctx context.Context) error {
-				current := currentRunning.Add(1)
-
-				for {
-					maxValue := atomic.LoadInt32(&maxConcurrent)
-					if current <= maxValue || atomic.CompareAndSwapInt32(&maxConcurrent, maxValue, current) {
-						break
-					}
-				}
-
-				time.Sleep(20 * time.Millisecond)
-				currentRunning.Add(-1)
-				return nil
-			}
-		}
-
-		ctx := context.Background()
-		err := NewParallelExecutor(3, executors...)(ctx)
-		assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-
-		assert.LessOrEqual(t, int(maxConcurrent), 3, "Should never exceed 3 concurrent executions")
-		assert.GreaterOrEqual(t, int(maxConcurrent), 1, "Should have at least 1 concurrent execution")
-	})
-
-	t.Run("MaxParallel=0 Uses1Worker", func(t *testing.T) {
-		var maxConcurrent int32
-		var currentRunning atomic.Int32
-
-		executors := make([]Executor, 5)
-		for i := range 5 {
-			executors[i] = func(ctx context.Context) error {
-				current := currentRunning.Add(1)
-
-				for {
-					maxValue := atomic.LoadInt32(&maxConcurrent)
-					if current <= maxValue || atomic.CompareAndSwapInt32(&maxConcurrent, maxValue, current) {
-						break
-					}
-				}
-
-				time.Sleep(10 * time.Millisecond)
-				currentRunning.Add(-1)
-				return nil
-			}
-		}
-
-		ctx := context.Background()
-		// When maxParallel is 0 or negative, it defaults to 1
-		err := NewParallelExecutor(0, executors...)(ctx)
-		assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-
-		assert.Equal(t, int32(1), maxConcurrent, "Should use 1 worker when max-parallel is 0")
-	})
-}
-
-// TestMaxParallelWithErrors tests error handling with max-parallel
-func TestMaxParallelWithErrors(t *testing.T) {
-	t.Run("OneTaskFailsOthersContinue", func(t *testing.T) {
-		var successCount int32
-
-		executors := make([]Executor, 5)
-		for i := range 5 {
-			taskID := i
-			executors[i] = func(ctx context.Context) error {
-				if taskID == 2 {
-					return assert.AnError
-				}
-				atomic.AddInt32(&successCount, 1)
-				return nil
-			}
-		}
-
-		ctx := context.Background()
-		err := NewParallelExecutor(2, executors...)(ctx)
-
-		// Should return the error from task 2
-		assert.Error(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-
-		// Other tasks should still execute
-		assert.Equal(t, int32(4), successCount, "4 tasks should succeed")
-	})
-
-	t.Run("ContextCancellation", func(t *testing.T) {
-		ctx, cancel := context.WithCancel(context.Background())
-
-		var startedCount int32
-		executors := make([]Executor, 10)
-		for i := range 10 {
-			executors[i] = func(ctx context.Context) error {
-				atomic.AddInt32(&startedCount, 1)
-				time.Sleep(100 * time.Millisecond)
-				return nil
-			}
-		}
-
-		// Cancel after a short delay
-		go func() {
-			time.Sleep(30 * time.Millisecond)
-			cancel()
-		}()
-
-		err := NewParallelExecutor(3, executors...)(ctx)
-		assert.Error(t, err)                     //nolint:testifylint // pre-existing issue from nektos/act
-		assert.ErrorIs(t, err, context.Canceled) //nolint:testifylint // pre-existing issue from nektos/act
-
-		// Not all tasks should start due to cancellation (but timing may vary)
-		// Just verify cancellation occurred
-		t.Logf("Started %d tasks before cancellation", startedCount)
-	})
-}
-
-// TestMaxParallelResourceSharing tests resource sharing scenarios
-func TestMaxParallelResourceSharing(t *testing.T) {
-	t.Run("SharedResourceWithMutex", func(t *testing.T) {
-		var sharedCounter int
-		var mu sync.Mutex
-
-		executors := make([]Executor, 100)
-		for i := range 100 {
-			executors[i] = func(ctx context.Context) error {
-				mu.Lock()
-				sharedCounter++
-				mu.Unlock()
-				return nil
-			}
-		}
-
-		ctx := context.Background()
-		err := NewParallelExecutor(10, executors...)(ctx)
-		assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-
-		assert.Equal(t, 100, sharedCounter, "All tasks should increment counter")
-	})
-
-	t.Run("ChannelCommunication", func(t *testing.T) {
-		resultChan := make(chan int, 50)
-
-		executors := make([]Executor, 50)
-		for i := range 50 {
-			taskID := i
-			executors[i] = func(ctx context.Context) error {
-				resultChan <- taskID
-				return nil
-			}
-		}
-
-		ctx := context.Background()
-		err := NewParallelExecutor(5, executors...)(ctx)
-		assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-
-		close(resultChan)
-
-		results := make(map[int]bool)
-		for result := range resultChan {
-			results[result] = true
-		}
-
-		assert.Len(t, results, 50, "All task IDs should be received")
-	})
-}

act/common/executor_test.go

@@ -9,9 +9,9 @@ import (
 	"errors"
 	"reflect"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"testing"
-	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -82,44 +82,45 @@ func TestNewConditionalExecutor(t *testing.T) {
 	assert.Equal(1, falseCount)
 }
 
-func TestNewParallelExecutor(t *testing.T) {
-	assert := assert.New(t)
+// 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{})
 
-	ctx := context.Background()
-
-	var count, activeCount, maxCount atomic.Int32
-	emptyWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
-		count.Add(1)
-
-		active := activeCount.Add(1)
+	return func(ctx context.Context) error {
+		counted.Add(1)
+		running := active.Add(1)
 		for {
-			m := maxCount.Load()
-			if active <= m || maxCount.CompareAndSwap(m, active) {
+			seen := peak.Load()
+			if running <= seen || peak.CompareAndSwap(seen, running) {
 				break
 			}
 		}
-		time.Sleep(2 * time.Second)
-		activeCount.Add(-1)
-
+		if running >= wantActive {
+			once.Do(func() { close(reached) })
+		}
+		<-reached
+		active.Add(-1)
 		return nil
-	})
+	}, &counted, &peak
+}
 
-	err := NewParallelExecutor(2, emptyWorkflow, emptyWorkflow, emptyWorkflow)(ctx)
+func TestNewParallelExecutor(t *testing.T) {
+	ctx := context.Background()
 
-	assert.Equal(int32(3), count.Load(), "should run all 3 executors")
-	assert.Equal(int32(2), maxCount.Load(), "should run at most 2 executors in parallel")
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	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")
 
-	// Reset to test running the executor with 0 parallelism
-	count.Store(0)
-	activeCount.Store(0)
-	maxCount.Store(0)
-
-	errSingle := NewParallelExecutor(0, emptyWorkflow, emptyWorkflow, emptyWorkflow)(ctx)
-
-	assert.Equal(int32(3), count.Load(), "should run all 3 executors")
-	assert.Equal(int32(1), maxCount.Load(), "should run at most 1 executors in parallel")
-	assert.NoError(errSingle)
+	// 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) {
@@ -173,6 +174,23 @@ func TestNewParallelExecutorCanceled(t *testing.T) {
 	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

act/common/git/git.go

@@ -16,6 +16,7 @@ import (
 	"sync"
 
 	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/internal/pkg/lock"
 
 	"github.com/go-git/go-git/v5"
 	"github.com/go-git/go-git/v5/config"
@@ -32,7 +33,7 @@ var (
 	githubHTTPRegex     = regexp.MustCompile(`^https?://.*github.com.*/(.+)/(.+?)(?:.git)?$`)
 	githubSSHRegex      = regexp.MustCompile(`github.com[:/](.+)/(.+?)(?:.git)?$`)
 
-	cloneLocks sync.Map // key: clone target directory; value: *sync.Mutex
+	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")
@@ -43,10 +44,7 @@ var (
 // 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() {
-	v, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
-	mu := v.(*sync.Mutex)
-	mu.Lock()
-	return mu.Unlock
+	return cloneLocks.Lock(dir)
 }
 
 type Error struct {

act/common/git/git_test.go

@@ -12,7 +12,6 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
-	"sync"
 	"syscall"
 	"testing"
 	"time"
@@ -610,12 +609,4 @@ func TestAcquireCloneLock(t *testing.T) {
 			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/common/outbound_ip.go

@@ -19,7 +19,9 @@ func GetOutboundIP() net.IP {
 	conn, err := net.Dial("udp", "8.8.8.8:80")
 	if err == nil {
 		defer conn.Close()
-		return conn.LocalAddr().(*net.UDPAddr).IP
+		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.

act/container/container_types.go

@@ -82,12 +82,14 @@ type NewDockerBuildExecutorInput struct {
 	BuildContext io.Reader
 	ImageTag     string
 	Platform     string
+	BuildArgs    map[string]*string
 }
 
 // NewDockerNetworkCreateExecutorInput the input for the NewDockerNetworkCreateExecutor function
 type NewDockerNetworkCreateExecutorInput struct {
 	EnableIPv4 *bool
 	EnableIPv6 *bool
+	RunnerUUID string
 }
 
 // NewDockerPullExecutorInput the input for the NewDockerPullExecutor function

act/container/docker_build.go

@@ -49,6 +49,7 @@ func NewDockerBuildExecutor(input NewDockerBuildExecutorInput) common.Executor {
 			Remove:      true,
 			AuthConfigs: LoadDockerAuthConfigs(ctx),
 			Dockerfile:  input.Dockerfile,
+			BuildArgs:   input.BuildArgs,
 		}
 		platform, err := parsePlatform(input.Platform)
 		if err != nil {

act/container/docker_create_flags_test.go

@@ -51,7 +51,8 @@ func TestCreateFlagsValidate(t *testing.T) {
 
 func TestNewContainerAppliesCreateFlags(t *testing.T) {
 	input := &NewContainerInput{Platform: "linux/amd64", Options: "--platform linux/arm64 --pull never"}
-	cr := NewContainer(input).(*containerReference)
+	cr, ok := NewContainer(input).(*containerReference)
+	require.True(t, ok)
 	assert.Equal(t, "linux/arm64", input.Platform)
 	assert.Equal(t, pullPolicyNever, cr.pullPolicy)
 

act/container/docker_logger.go

@@ -57,7 +57,7 @@ func logDockerResponse(logger logrus.FieldLogger, dockerResponse io.ReadCloser,
 
 		if msg.ErrorDetail.Message != "" {
 			writeLog(logger, isError, "%s", msg.ErrorDetail.Message)
-			return errors.New(msg.Error)
+			return errors.New(msg.ErrorDetail.Message)
 		}
 
 		if msg.Status != "" {

act/container/docker_network.go

@@ -8,12 +8,69 @@ package container
 
 import (
 	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
 	"github.com/moby/moby/client"
 )
 
+const (
+	networkCreateAttempts   = 3
+	networkCreateRetryDelay = time.Second
+
+	// marks the networks a runner creates for its jobs, so it can tell its own leftovers from
+	// those of another runner sharing the daemon
+	runnerUUIDLabel = "com.gitea.runner.uuid"
+)
+
+// RemoveOrphanNetworks removes the networks this runner created for jobs whose teardown did
+// not get to them: the runner died with the job, the teardown timed out, or the network still
+// had an endpoint on it at the time. Each one holds a subnet of the daemon's address pool
+// until it is removed. Networks created after createdBefore are left alone, so a job starting
+// while this runs cannot lose the network it has created but not yet attached a container to.
+func RemoveOrphanNetworks(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
+	cli, err := GetDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to connect to the docker daemon: %w", err)
+	}
+	defer cli.Close()
+
+	return removeOrphanNetworks(ctx, cli, runnerUUID, createdBefore)
+}
+
+func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID string, createdBefore time.Time) error {
+	networks, err := cli.NetworkList(ctx, client.NetworkListOptions{
+		Filters: make(client.Filters).Add("label", runnerUUIDLabel+"="+runnerUUID),
+	})
+	if err != nil {
+		return err
+	}
+
+	var errs []error
+	for _, n := range networks.Items {
+		result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
+		if err != nil {
+			errs = append(errs, fmt.Errorf("failed to inspect network %s: %w", n.Name, err))
+			continue
+		}
+		// the emptiness check, not the label, is what keeps a live job of another process
+		// sharing this registration safe
+		if len(result.Network.Containers) != 0 || result.Network.Created.After(createdBefore) {
+			continue
+		}
+		if _, err := cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); err != nil {
+			errs = append(errs, fmt.Errorf("failed to remove network %s: %w", n.Name, err))
+			continue
+		}
+		common.Logger(ctx).Infof("removed docker network %s left behind by an earlier job", n.Name)
+	}
+	return errors.Join(errs...)
+}
+
 func NewDockerNetworkCreateExecutor(name string, opts NewDockerNetworkCreateExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
 		cli, err := GetDockerClient(ctx)
@@ -36,18 +93,45 @@ func NewDockerNetworkCreateExecutor(name string, opts NewDockerNetworkCreateExec
 			}
 		}
 
-		_, err = cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{
-			Driver:     "bridge",
-			Scope:      "local",
-			EnableIPv4: opts.EnableIPv4,
-			EnableIPv6: opts.EnableIPv6,
-		})
-		if err != nil {
-			return err
+		for i := range networkCreateAttempts {
+			if i > 0 {
+				common.Logger(ctx).Infof("Waiting for a free docker address pool to create network %s", name)
+				select {
+				case <-ctx.Done():
+					return ctx.Err()
+				case <-time.After(time.Duration(i) * networkCreateRetryDelay):
+				}
+			}
+			if _, err = cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{
+				Driver:     "bridge",
+				Scope:      "local",
+				EnableIPv4: opts.EnableIPv4,
+				EnableIPv6: opts.EnableIPv6,
+				Labels:     runnerLabels(opts.RunnerUUID),
+			}); err == nil {
+				return nil
+			}
+			if !isAddressPoolExhausted(err) {
+				return err
+			}
 		}
+		return fmt.Errorf("docker has no address pool left for this job's network, lower runner.capacity or widen default-address-pools in the docker daemon config: %w", err)
+	}
+}
 
+func runnerLabels(runnerUUID string) map[string]string {
+	if runnerUUID == "" {
 		return nil
 	}
+	return map[string]string{runnerUUIDLabel: runnerUUID}
+}
+
+// The daemon reports this as a plain invalid-parameter error, the same kind it uses for every
+// malformed request, so the message is the only discriminator.
+func isAddressPoolExhausted(err error) bool {
+	msg := err.Error()
+	return strings.Contains(msg, "all predefined address pools have been fully subnetted") ||
+		strings.Contains(msg, "could not find an available, non-overlapping IPv4 address pool among the defaults") // docker 24 and older
 }
 
 func NewDockerNetworkRemoveExecutor(name string) common.Executor {
@@ -66,6 +150,7 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 		}
 		// For Gitea, reduce log noise
 		// common.Logger(ctx).Debugf("%v", networks)
+		var errs []error
 		for _, n := range networks.Items {
 			if n.Name == name {
 				result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
@@ -73,16 +158,17 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 					return err
 				}
 
-				if len(result.Network.Containers) == 0 {
-					if _, err = cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); err != nil {
-						common.Logger(ctx).Debugf("%v", err)
-					}
-				} else {
-					common.Logger(ctx).Debugf("Refusing to remove network %v because it still has active endpoints", name)
+				// it holds a subnet out of the daemon's pool until something reclaims it
+				if len(result.Network.Containers) != 0 {
+					common.Logger(ctx).Warnf("Refusing to remove network %s because it still has active endpoints, the idle cleanup reclaims it once they are gone", name)
+					continue
+				}
+				if _, err = cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); err != nil {
+					errs = append(errs, fmt.Errorf("failed to remove network %s: %w", name, err))
 				}
 			}
 		}
 
-		return err
+		return errors.Join(errs...)
 	}
 }

act/container/docker_network_test.go

@@ -0,0 +1,50 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package container
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/types/network"
+	mobyclient "github.com/moby/moby/client"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestIsAddressPoolExhausted(t *testing.T) {
+	assert.True(t, isAddressPoolExhausted(cerrdefs.ErrInvalidArgument.WithMessage("Error response from daemon: all predefined address pools have been fully subnetted")))
+	assert.True(t, isAddressPoolExhausted(errors.New("could not find an available, non-overlapping IPv4 address pool among the defaults to assign to the network")))
+	assert.False(t, isAddressPoolExhausted(cerrdefs.ErrInvalidArgument.WithMessage("invalid subnet 10.0.0.0/8: it overlaps with an existing network")))
+}
+
+// Of this runner's networks, only the ones nothing is attached to and old enough to predate
+// any job now starting are the runner's to reclaim. An unexpected NetworkRemove fails the
+// test on its own, since testify has no expectation to match it against.
+func TestRemoveOrphanNetworks(t *testing.T) {
+	ctx := context.Background()
+	cutoff := time.Date(2026, time.April, 29, 20, 0, 0, 0, time.UTC)
+	client := &mockDockerClient{}
+	client.On("NetworkList", ctx, mobyclient.NetworkListOptions{
+		Filters: make(mobyclient.Filters).Add("label", runnerUUIDLabel+"=runner-1"),
+	}).Return(mobyclient.NetworkListResult{Items: []network.Summary{
+		{Network: network.Network{ID: "orphan"}},
+		{Network: network.Network{ID: "busy"}},
+		{Network: network.Network{ID: "starting"}},
+	}}, nil)
+	client.On("NetworkInspect", ctx, "orphan", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{}, nil)
+	client.On("NetworkInspect", ctx, "busy", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Containers: map[string]network.EndpointResource{"c": {}}}}, nil)
+	client.On("NetworkInspect", ctx, "starting", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Network: network.Network{Created: cutoff.Add(time.Second)}}}, nil)
+	client.On("NetworkRemove", ctx, "orphan", mobyclient.NetworkRemoveOptions{}).
+		Return(mobyclient.NetworkRemoveResult{}, nil)
+
+	require.NoError(t, removeOrphanNetworks(ctx, client, "runner-1", cutoff))
+	client.AssertExpectations(t)
+}

act/container/docker_pull.go

@@ -30,23 +30,19 @@ func NewDockerPullExecutor(input NewDockerPullExecutorInput) common.Executor {
 			return nil
 		}
 
-		pull := input.ForcePull
-		if !pull {
+		// skip the pull when the image is already here: either none was forced, or a digest
+		// pins the content so a forced pull could only fetch the same bytes again
+		if !input.ForcePull || isPinnedImage(input.Image) {
 			imageExists, err := ImageExistsLocally(ctx, input.Image, input.Platform)
 			logger.Debugf("Image exists? %v", imageExists)
 			if err != nil {
 				return fmt.Errorf("unable to determine if image already exists for image '%s' (%s): %w", input.Image, input.Platform, err)
 			}
-
-			if !imageExists {
-				pull = true
+			if imageExists {
+				return nil
 			}
 		}
 
-		if !pull {
-			return nil
-		}
-
 		imageRef := cleanImage(ctx, input.Image)
 		logger.Debugf("pulling image '%v' (%s)", imageRef, input.Platform)
 
@@ -61,22 +57,32 @@ func NewDockerPullExecutor(input NewDockerPullExecutorInput) common.Executor {
 			return err
 		}
 
-		reader, err := cli.ImagePull(ctx, imageRef, imagePullOptions)
-
-		_ = logDockerResponse(logger, reader, err != nil)
-		if err != nil {
-			if imagePullOptions.RegistryAuth != "" && strings.Contains(err.Error(), "unauthorized") {
-				logger.Errorf("pulling image '%v' (%s) failed with credentials %s retrying without them, please check for stale docker config files", imageRef, input.Platform, err.Error())
-				imagePullOptions.RegistryAuth = ""
-				reader, err = cli.ImagePull(ctx, imageRef, imagePullOptions)
-
-				_ = logDockerResponse(logger, reader, err != nil)
-			}
+		// the daemon reports a failure that happens after the first progress line in the
+		// stream rather than on the call itself, so both have to be checked
+		pullOnce := func(opts client.ImagePullOptions) error {
+			reader, err := cli.ImagePull(ctx, imageRef, opts)
+			streamErr := logDockerResponse(logger, reader, err != nil)
 			if err != nil {
-				return fmt.Errorf("failed to pull image '%s' (%s): %w", imageRef, input.Platform, err)
+				return err
 			}
+			return streamErr
 		}
-		return nil
+
+		err = pullOnce(imagePullOptions)
+		if err != nil && imagePullOptions.RegistryAuth != "" && strings.Contains(err.Error(), "unauthorized") {
+			logger.Errorf("pulling image '%v' (%s) failed with credentials %s retrying without them, please check for stale docker config files", imageRef, input.Platform, err.Error())
+			imagePullOptions.RegistryAuth = ""
+			err = pullOnce(imagePullOptions)
+		}
+		if err == nil {
+			return nil
+		}
+		// a registry that is down should not fail a job whose image is already here
+		if exists, existsErr := ImageExistsLocally(ctx, input.Image, input.Platform); existsErr == nil && exists {
+			logger.Warnf("could not update image '%s' (%s), continuing with the local copy: %v", imageRef, input.Platform, err)
+			return nil
+		}
+		return fmt.Errorf("failed to pull image '%s' (%s): %w", imageRef, input.Platform, err)
 	}
 }
 
@@ -122,6 +128,15 @@ func getImagePullOptions(ctx context.Context, input NewDockerPullExecutorInput)
 	return imagePullOptions, nil
 }
 
+func isPinnedImage(image string) bool {
+	ref, err := reference.ParseAnyReference(image)
+	if err != nil {
+		return false
+	}
+	_, pinned := ref.(reference.Canonical)
+	return pinned
+}
+
 func cleanImage(ctx context.Context, imageName string) string {
 	ref, err := reference.ParseAnyReference(imageName)
 	if err != nil {

act/container/docker_pull_test.go

@@ -6,11 +6,15 @@ package container
 
 import (
 	"context"
+	"io"
+	"strings"
 	"testing"
 
 	"github.com/docker/cli/cli/config"
 	log "github.com/sirupsen/logrus"
+	"github.com/sirupsen/logrus/hooks/test"
 	assert "github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func init() {
@@ -65,3 +69,21 @@ func TestGetImagePullOptions(t *testing.T) {
 	assert.NoError(t, err, "Failed to create ImagePullOptions") //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, "eyJ1c2VybmFtZSI6InVzZXJuYW1lIiwicGFzc3dvcmQiOiJwYXNzd29yZFxuIiwic2VydmVyYWRkcmVzcyI6Imh0dHBzOi8vaW5kZXguZG9ja2VyLmlvL3YxLyJ9", options.RegistryAuth, "RegistryAuth should be taken from local docker config")
 }
+
+// A digest-pinned image is immutable, so its local copy is always current.
+func TestIsPinnedImage(t *testing.T) {
+	assert.True(t, isPinnedImage("alpine@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b"))
+	assert.False(t, isPinnedImage("alpine:latest"))
+}
+
+// The pull path reports a failure the daemon sent mid-stream, so it must carry the reason
+// whichever of the two shapes the daemon used.
+func TestLogDockerResponseError(t *testing.T) {
+	logger, _ := test.NewNullLogger()
+	streamErr := func(line string) error {
+		return logDockerResponse(logger, io.NopCloser(strings.NewReader(line)), false)
+	}
+	require.EqualError(t, streamErr(`{"error":"toomanyrequests: rate limit exceeded"}`), "toomanyrequests: rate limit exceeded")
+	require.EqualError(t, streamErr(`{"errorDetail":{"message":"unexpected EOF"}}`), "unexpected EOF")
+	require.NoError(t, streamErr(`{"status":"Downloading"}`))
+}

act/container/docker_run.go

@@ -14,6 +14,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path"
 	"path/filepath"
 	"regexp"
 	"runtime"
@@ -42,6 +43,7 @@ import (
 	"github.com/moby/moby/api/types/system"
 	"github.com/moby/moby/client"
 	specs "github.com/opencontainers/image-spec/specs-go/v1"
+	"github.com/sirupsen/logrus"
 )
 
 // drainGracePeriod bounds how long we wait for an output-copy goroutine to
@@ -386,32 +388,71 @@ func (cr *containerReference) find() common.Executor {
 	}
 }
 
-// isContainerGone reports whether a failed remove still left the container gone (NotFound or Conflict).
-func isContainerGone(err error) bool {
-	return cerrdefs.IsNotFound(err) || cerrdefs.IsConflict(err)
-}
-
 func (cr *containerReference) remove() common.Executor {
 	return func(ctx context.Context) error {
-		if cr.id == "" {
+		idOrName := cr.id
+		if idOrName == "" && cr.input != nil {
+			idOrName = cr.input.Name
+		}
+		if idOrName == "" {
 			return nil
 		}
 
 		logger := common.Logger(ctx)
-		_, err := cr.cli.ContainerRemove(ctx, cr.id, client.ContainerRemoveOptions{
+		// Kill first so removal never waits out a daemon's stop timeout: Docker kills outright
+		// on a forced remove, Podman sends SIGTERM and waits. Only worth it for a container
+		// this started, and removal can still deal with one it could not kill.
+		if cr.id != "" {
+			_, err := cr.cli.ContainerKill(ctx, cr.id, client.ContainerKillOptions{Signal: "SIGKILL"})
+			if err != nil && !cerrdefs.IsConflict(err) && !cerrdefs.IsNotFound(err) {
+				logger.Debugf("Container %s could not be killed: %v", cr.id, err)
+			}
+		}
+		_, err := cr.cli.ContainerRemove(ctx, idOrName, client.ContainerRemoveOptions{
 			RemoveVolumes: true,
 			Force:         true,
 		})
-		if err != nil && !isContainerGone(err) {
-			logger.Error(fmt.Errorf("failed to remove container: %w", err))
+		switch {
+		case cerrdefs.IsConflict(err):
+			// the daemon's own AutoRemove teardown is running, and it releases the volume
+			// references and the network endpoint only once it finishes
+			cr.waitForRemoval(ctx, idOrName)
+		case err != nil && !cerrdefs.IsNotFound(err):
+			logger.Error(fmt.Errorf("failed to remove container %s: %w", idOrName, err))
+			return nil // keep the id, the container is still there for a later Remove()
 		}
 
-		logger.Debugf("Removed container: %v", cr.id)
+		logger.Debugf("Removed container: %v", idOrName)
 		cr.id = ""
 		return nil
 	}
 }
 
+func (cr *containerReference) waitForRemoval(ctx context.Context, idOrName string) {
+	// per container, against the one minute the post-job executor allows for the whole
+	// cleanup, so a job with several services can spend most of that budget here
+	ctx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	defer cancel()
+
+	waitResult := cr.cli.ContainerWait(ctx, idOrName, client.ContainerWaitOptions{
+		Condition: container.WaitConditionRemoved,
+	})
+	select {
+	case <-waitResult.Result:
+	case <-waitResult.Error:
+	case <-ctx.Done():
+		// the client delivers the result over an unbuffered channel, so leave a receiver
+		// behind or its goroutine parks on the send for the lifetime of the process
+		go func() {
+			select {
+			case <-waitResult.Result:
+			case <-waitResult.Error:
+			}
+		}()
+		common.Logger(ctx).Warnf("Timed out waiting for the daemon to remove container %s, its volumes and network may be left behind", idOrName)
+	}
+}
+
 func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config *container.Config, hostConfig *container.HostConfig) (*container.Config, *container.HostConfig, error) {
 	logger := common.Logger(ctx)
 	input := cr.input
@@ -461,6 +502,16 @@ func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config
 		return nil, nil, fmt.Errorf("Cannot process container options: '%s': '%w'", input.Options, err)
 	}
 
+	// For Gitea
+	// When privileged mode is disabled, container.options is workflow-controlled
+	// untrusted input. Strip the HostConfig fields that would let a workflow break
+	// out of the container (host namespaces, capability expansion, security profile
+	// overrides, device and runtime access). Otherwise these survive into the final
+	// HostConfig even though --privileged is forced off.
+	if !hostConfig.Privileged {
+		sanitizeOptionsHostConfig(logger, containerConfig.HostConfig)
+	}
+
 	logger.Debugf("Custom container.Config from options ==> %+v", containerConfig.Config)
 
 	err = mergo.Merge(config, containerConfig.Config, mergo.WithOverride, mergo.WithAppendSlice)
@@ -471,8 +522,7 @@ func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config
 
 	logger.Debugf("Custom container.HostConfig from options ==> %+v", containerConfig.HostConfig)
 
-	hostConfig.Binds = append(hostConfig.Binds, containerConfig.HostConfig.Binds...)
-	hostConfig.Mounts = append(hostConfig.Mounts, containerConfig.HostConfig.Mounts...)
+	overlayVolumes(hostConfig, containerConfig.HostConfig)
 	binds := hostConfig.Binds
 	mounts := hostConfig.Mounts
 	networkMode := hostConfig.NetworkMode
@@ -815,23 +865,59 @@ func (cr *containerReference) waitForCommand(ctx context.Context, isTerminal boo
 	}
 }
 
+// mkdirInContainer creates containerPath and returns it with the symlinked components
+// replaced by the targets the daemon reports for them. Docker 29.7 rejects tar entries
+// traversing a symlink to an absolute target, like the "/var/run" of most images, with
+// "path escapes from parent", and not every daemon creates the implied parents of a
+// directory entry, so one entry per missing component is extracted at the deepest
+// existing ancestor.
+// WORKAROUND: https://github.com/moby/moby/issues/53258
+func (cr *containerReference) mkdirInContainer(ctx context.Context, containerPath string) (string, error) {
+	parts := strings.Split(strings.Trim(path.Clean(containerPath), "/"), "/")
+	existing := "/"
+	for i, part := range parts {
+		if part == "" {
+			return existing, nil
+		}
+		stat, err := cr.cli.ContainerStatPath(ctx, cr.id, client.ContainerStatPathOptions{Path: path.Join(existing, part)})
+		if err != nil {
+			// nothing below exists either, so create the remaining components
+			return path.Join(existing, path.Join(parts[i:]...)), cr.mkdirEntries(ctx, existing, parts[i:])
+		}
+		existing = path.Join(existing, part)
+		if target := stat.Stat.LinkTarget; target != "" {
+			if !path.IsAbs(target) {
+				target = path.Join(path.Dir(existing), target)
+			}
+			existing = target
+		}
+	}
+	return existing, nil
+}
+
+func (cr *containerReference) mkdirEntries(ctx context.Context, destPath string, missing []string) error {
+	buf := &bytes.Buffer{}
+	tw := tar.NewWriter(buf)
+	for i := range missing {
+		_ = tw.WriteHeader(&tar.Header{
+			Name:     path.Join(missing[:i+1]...),
+			Mode:     0o777,
+			Typeflag: tar.TypeDir,
+		})
+	}
+	tw.Close()
+	_, err := cr.cli.CopyToContainer(ctx, cr.id, client.CopyToContainerOptions{
+		DestinationPath: destPath,
+		Content:         buf,
+	})
+	return err
+}
+
 func (cr *containerReference) CopyTarStream(ctx context.Context, destPath string, tarStream io.Reader) error {
 	if cr.id == "" {
 		return cr.missingContainerError("copy to %s", destPath)
 	}
-	// Mkdir
-	buf := &bytes.Buffer{}
-	tw := tar.NewWriter(buf)
-	_ = tw.WriteHeader(&tar.Header{
-		Name:     destPath,
-		Mode:     0o777,
-		Typeflag: tar.TypeDir,
-	})
-	tw.Close()
-	_, err := cr.cli.CopyToContainer(ctx, cr.id, client.CopyToContainerOptions{
-		DestinationPath: "/",
-		Content:         buf,
-	})
+	destPath, err := cr.mkdirInContainer(ctx, destPath)
 	if err != nil {
 		return fmt.Errorf("failed to mkdir to copy content to container: %w", err)
 	}
@@ -856,6 +942,10 @@ func (cr *containerReference) copyDir(dstPath, srcPath string, useGitIgnore bool
 			return cr.missingContainerError("copy directory to %s", dstPath)
 		}
 		logger := common.Logger(ctx)
+		dstPath, err := cr.mkdirInContainer(ctx, dstPath)
+		if err != nil {
+			return fmt.Errorf("failed to mkdir to copy directory to container: %w", err)
+		}
 		tarFile, err := os.CreateTemp("", "act")
 		if err != nil {
 			return err
@@ -1063,6 +1153,77 @@ func (cr *containerReference) wait() common.Executor {
 	}
 }
 
+// For Gitea
+// sanitizeOptionsHostConfig clears the HostConfig fields parsed from a
+// workflow-controlled container.options string that could be used to escape the
+// container when privileged mode is disabled. It must only be called when the
+// runner has privileged mode turned off; with privileged mode enabled the
+// administrator has already opted into host access.
+func sanitizeOptionsHostConfig(logger logrus.FieldLogger, hostConfig *container.HostConfig) {
+	warn := func(option string) {
+		logger.Warnf("container option %q is not allowed when privileged mode is disabled and will be ignored", option)
+	}
+
+	if hostConfig.PidMode != "" {
+		warn("--pid")
+		hostConfig.PidMode = ""
+	}
+	if hostConfig.IpcMode != "" {
+		warn("--ipc")
+		hostConfig.IpcMode = ""
+	}
+	if hostConfig.UTSMode != "" {
+		warn("--uts")
+		hostConfig.UTSMode = ""
+	}
+	if hostConfig.CgroupnsMode != "" {
+		warn("--cgroupns")
+		hostConfig.CgroupnsMode = ""
+	}
+	// UsernsMode is set from the runner-controlled input; never let options
+	// override it (e.g. --userns=host disables user namespace remapping).
+	if hostConfig.UsernsMode != "" {
+		warn("--userns")
+		hostConfig.UsernsMode = ""
+	}
+	if len(hostConfig.CapAdd) > 0 {
+		warn("--cap-add")
+		hostConfig.CapAdd = nil
+	}
+	if len(hostConfig.SecurityOpt) > 0 {
+		warn("--security-opt")
+		hostConfig.SecurityOpt = nil
+	}
+	if len(hostConfig.Devices) > 0 {
+		warn("--device")
+		hostConfig.Devices = nil
+	}
+	if len(hostConfig.DeviceCgroupRules) > 0 {
+		warn("--device-cgroup-rule")
+		hostConfig.DeviceCgroupRules = nil
+	}
+	if len(hostConfig.DeviceRequests) > 0 {
+		warn("--gpus")
+		hostConfig.DeviceRequests = nil
+	}
+	if len(hostConfig.VolumesFrom) > 0 {
+		warn("--volumes-from")
+		hostConfig.VolumesFrom = nil
+	}
+	if hostConfig.Runtime != "" {
+		warn("--runtime")
+		hostConfig.Runtime = ""
+	}
+	if hostConfig.CgroupParent != "" {
+		warn("--cgroup-parent")
+		hostConfig.CgroupParent = ""
+	}
+	if len(hostConfig.Sysctls) > 0 {
+		warn("--sysctl")
+		hostConfig.Sysctls = nil
+	}
+}
+
 // For Gitea
 // sanitizeConfig remove the invalid configurations from `config` and `hostConfig`
 func (cr *containerReference) sanitizeConfig(ctx context.Context, config *container.Config, hostConfig *container.HostConfig) (*container.Config, *container.HostConfig) {
@@ -1108,6 +1269,34 @@ func (cr *containerReference) sanitizeConfig(ctx context.Context, config *contai
 	return config, hostConfig
 }
 
+// bindTarget returns the container path a bind mounts onto, empty if it cannot be parsed.
+func bindTarget(bind string) string {
+	parsed, err := loader.ParseVolume(bind)
+	if err != nil {
+		return ""
+	}
+	return parsed.Target
+}
+
+// overlayVolumes appends src's volumes to dst, dropping the dst ones they mount over. Docker
+// rejects two mounts on one target, so the volumes declared last have to win.
+func overlayVolumes(dst, src *container.HostConfig) {
+	claimed := map[string]bool{}
+	for _, bind := range src.Binds {
+		if target := bindTarget(bind); target != "" {
+			claimed[target] = true
+		}
+	}
+	for _, mt := range src.Mounts {
+		claimed[mt.Target] = true
+	}
+
+	dst.Binds = append(slices.DeleteFunc(slices.Clone(dst.Binds),
+		func(bind string) bool { return claimed[bindTarget(bind)] }), src.Binds...)
+	dst.Mounts = append(slices.DeleteFunc(slices.Clone(dst.Mounts),
+		func(mt mount.Mount) bool { return claimed[mt.Target] }), src.Mounts...)
+}
+
 type validVolumeMatcher struct {
 	allowAll bool
 	named    []glob.Glob

act/container/docker_run_test.go

@@ -5,6 +5,7 @@
 package container
 
 import (
+	"archive/tar"
 	"bufio"
 	"bytes"
 	"context"
@@ -23,6 +24,7 @@ import (
 	cerrdefs "github.com/containerd/errdefs"
 	"github.com/moby/moby/api/pkg/stdcopy"
 	"github.com/moby/moby/api/types/container"
+	"github.com/moby/moby/api/types/mount"
 	mobyclient "github.com/moby/moby/client"
 	"github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
@@ -91,6 +93,11 @@ func (m *mockDockerClient) ExecInspect(ctx context.Context, execID string, opts
 	return args.Get(0).(mobyclient.ExecInspectResult), args.Error(1)
 }
 
+func (m *mockDockerClient) ContainerStatPath(ctx context.Context, containerID string, opts mobyclient.ContainerStatPathOptions) (mobyclient.ContainerStatPathResult, error) {
+	args := m.Called(ctx, containerID, opts)
+	return args.Get(0).(mobyclient.ContainerStatPathResult), args.Error(1)
+}
+
 func (m *mockDockerClient) ContainerAttach(ctx context.Context, containerID string, opts mobyclient.ContainerAttachOptions) (mobyclient.ContainerAttachResult, error) {
 	args := m.Called(ctx, containerID, opts)
 	return args.Get(0).(mobyclient.ContainerAttachResult), args.Error(1)
@@ -121,6 +128,26 @@ func (m *mockDockerClient) ContainerRemove(ctx context.Context, id string, opts
 	return args.Get(0).(mobyclient.ContainerRemoveResult), args.Error(1)
 }
 
+func (m *mockDockerClient) ContainerKill(ctx context.Context, id string, opts mobyclient.ContainerKillOptions) (mobyclient.ContainerKillResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.ContainerKillResult), args.Error(1)
+}
+
+func (m *mockDockerClient) NetworkList(ctx context.Context, opts mobyclient.NetworkListOptions) (mobyclient.NetworkListResult, error) {
+	args := m.Called(ctx, opts)
+	return args.Get(0).(mobyclient.NetworkListResult), args.Error(1)
+}
+
+func (m *mockDockerClient) NetworkInspect(ctx context.Context, id string, opts mobyclient.NetworkInspectOptions) (mobyclient.NetworkInspectResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.NetworkInspectResult), args.Error(1)
+}
+
+func (m *mockDockerClient) NetworkRemove(ctx context.Context, id string, opts mobyclient.NetworkRemoveOptions) (mobyclient.NetworkRemoveResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.NetworkRemoveResult), args.Error(1)
+}
+
 type endlessReader struct {
 	io.Reader
 }
@@ -314,15 +341,37 @@ func TestDockerWaitFailure(t *testing.T) {
 	client.AssertExpectations(t)
 }
 
+// stubStatPath answers path resolution: the given paths exist, mapped to their target
+// when they are a symlink, everything else does not exist.
+func stubStatPath(client *mockDockerClient, existing map[string]string) {
+	for containerPath, target := range existing {
+		client.On("ContainerStatPath", mock.Anything, "123", mobyclient.ContainerStatPathOptions{Path: containerPath}).
+			Return(mobyclient.ContainerStatPathResult{Stat: container.PathStat{LinkTarget: target}}, nil).Maybe()
+	}
+	client.On("ContainerStatPath", mock.Anything, "123", mock.Anything).
+		Return(mobyclient.ContainerStatPathResult{}, cerrdefs.ErrNotFound).Maybe()
+}
+
+// The mkdir tarball is extracted at the deepest existing ancestor, with entries relative
+// to it that never traverse the "/var/run" symlink, see moby/moby#53258.
 func TestDockerCopyTarStream(t *testing.T) {
 	ctx := context.Background()
 
+	var mkdirNames []string
 	client := &mockDockerClient{}
+	stubStatPath(client, map[string]string{"/var": "", "/var/run": "/run", "/run": ""})
 	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/" && opts.Content != nil
+		if opts.DestinationPath != "/run" || opts.Content == nil {
+			return false
+		}
+		tr := tar.NewReader(opts.Content)
+		for hdr, err := tr.Next(); err == nil; hdr, err = tr.Next() {
+			mkdirNames = append(mkdirNames, hdr.Name)
+		}
+		return true
 	})).Return(mobyclient.CopyToContainerResult{}, nil)
 	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/var/run/act" && opts.Content != nil
+		return opts.DestinationPath == "/run/act" && opts.Content != nil
 	})).Return(mobyclient.CopyToContainerResult{}, nil)
 	cr := &containerReference{
 		id:  "123",
@@ -332,87 +381,85 @@ func TestDockerCopyTarStream(t *testing.T) {
 		},
 	}
 
-	_ = cr.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{})
+	require.NoError(t, cr.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{}))
+	assert.Equal(t, []string{"act"}, mkdirNames)
 
 	client.AssertExpectations(t)
 }
 
-func TestDockerCopyTarStreamErrorInCopyFiles(t *testing.T) {
-	ctx := context.Background()
-
+func TestDockerCopyTarStreamErrors(t *testing.T) {
 	merr := errors.New("Failure")
+	for _, testCase := range []struct {
+		name     string
+		mkdirErr error
+		copyErr  error
+	}{
+		{"mkdir", merr, nil},
+		{"copy content", nil, merr},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			ctx := context.Background()
 
-	client := &mockDockerClient{}
-	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/" && opts.Content != nil
-	})).Return(mobyclient.CopyToContainerResult{}, merr)
-	cr := &containerReference{
-		id:  "123",
-		cli: client,
-		input: &NewContainerInput{
-			Image: "image",
-		},
+			client := &mockDockerClient{}
+			stubStatPath(client, map[string]string{"/var": "", "/var/run": ""})
+			client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
+				return opts.DestinationPath == "/var/run" && opts.Content != nil
+			})).Return(mobyclient.CopyToContainerResult{}, testCase.mkdirErr)
+			client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
+				return opts.DestinationPath == "/var/run/act" && opts.Content != nil
+			})).Return(mobyclient.CopyToContainerResult{}, testCase.copyErr).Maybe()
+			cr := &containerReference{
+				id:  "123",
+				cli: client,
+				input: &NewContainerInput{
+					Image: "image",
+				},
+			}
+
+			require.ErrorIs(t, cr.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{}), merr)
+
+			client.AssertExpectations(t)
+		})
 	}
-
-	err := cr.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{})
-	assert.ErrorIs(t, err, merr) //nolint:testifylint // pre-existing issue from nektos/act
-
-	client.AssertExpectations(t)
-}
-
-func TestDockerCopyTarStreamErrorInMkdir(t *testing.T) {
-	ctx := context.Background()
-
-	merr := errors.New("Failure")
-
-	client := &mockDockerClient{}
-	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/" && opts.Content != nil
-	})).Return(mobyclient.CopyToContainerResult{}, nil)
-	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/var/run/act" && opts.Content != nil
-	})).Return(mobyclient.CopyToContainerResult{}, merr)
-	cr := &containerReference{
-		id:  "123",
-		cli: client,
-		input: &NewContainerInput{
-			Image: "image",
-		},
-	}
-
-	err := cr.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{})
-	assert.ErrorIs(t, err, merr) //nolint:testifylint // pre-existing issue from nektos/act
-
-	client.AssertExpectations(t)
 }
 
 // A remove that raced the daemon's AutoRemove teardown is not a failure and must not
 // be logged as one.
 func TestRemoveIgnoresAutoRemoveRace(t *testing.T) {
 	removeOpts := mobyclient.ContainerRemoveOptions{RemoveVolumes: true, Force: true}
+	killOpts := mobyclient.ContainerKillOptions{Signal: "SIGKILL"}
 	for _, tc := range []struct {
-		name     string
-		err      error
-		wantLogs bool
+		name        string
+		err         error
+		wantWait    bool
+		wantFailure bool
 	}{
-		{name: "removal in progress", err: cerrdefs.ErrConflict.WithMessage("removal of container abc is already in progress")},
+		{name: "removal in progress", err: cerrdefs.ErrConflict.WithMessage("removal of container abc is already in progress"), wantWait: true},
 		{name: "already removed", err: cerrdefs.ErrNotFound.WithMessage("No such container: abc")},
 		{name: "removed cleanly", err: nil},
-		{name: "real failure", err: errors.New("driver failed to remove root filesystem"), wantLogs: true},
+		{name: "real failure", err: errors.New("driver failed to remove root filesystem"), wantFailure: true},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			logger, hook := test.NewNullLogger()
 			ctx := common.WithLogger(context.Background(), logger)
 			client := &mockDockerClient{}
+			client.On("ContainerKill", ctx, "abc", killOpts).Return(mobyclient.ContainerKillResult{}, nil)
 			client.On("ContainerRemove", ctx, "abc", removeOpts).Return(mobyclient.ContainerRemoveResult{}, tc.err)
+			if tc.wantWait {
+				removed := make(chan container.WaitResponse, 1)
+				removed <- container.WaitResponse{}
+				client.On("ContainerWait", mock.Anything, "abc", mobyclient.ContainerWaitOptions{Condition: container.WaitConditionRemoved}).
+					Return(mobyclient.ContainerWaitResult{Result: removed})
+			}
 			cr := &containerReference{id: "abc", cli: client}
 
 			require.NoError(t, cr.remove()(ctx))
-			assert.Empty(t, cr.id)
-
-			if tc.wantLogs {
+			// a failure keeps the id, so a later Remove() can retry it
+			if tc.wantFailure {
+				assert.Equal(t, "abc", cr.id)
 				assert.Len(t, hook.AllEntries(), 1)
 			} else {
+				assert.Empty(t, cr.id)
 				assert.Empty(t, hook.AllEntries())
 			}
 			client.AssertExpectations(t)
@@ -420,6 +467,20 @@ func TestRemoveIgnoresAutoRemoveRace(t *testing.T) {
 	}
 }
 
+// A container whose id was never learned, because find() could not reach the daemon or
+// create() lost its reply, must still be removed rather than leaking with its network. It
+// was never started here, so it is not worth a kill of its own.
+func TestRemoveWithoutIDUsesName(t *testing.T) {
+	ctx := context.Background()
+	client := &mockDockerClient{}
+	client.On("ContainerRemove", ctx, "job-1", mobyclient.ContainerRemoveOptions{RemoveVolumes: true, Force: true}).
+		Return(mobyclient.ContainerRemoveResult{}, nil)
+	cr := &containerReference{cli: client, input: &NewContainerInput{Name: "job-1"}}
+
+	require.NoError(t, cr.remove()(ctx))
+	client.AssertExpectations(t)
+}
+
 // find() must drop a stale cached id so later Copy/Exec don't hit the
 // daemon with a torn-down container.
 func TestFindRevalidatesStaleID(t *testing.T) {
@@ -541,9 +602,8 @@ func TestDockerCopyToSymlinkPath(t *testing.T) {
 		_ = rc.Close()(ctx)
 	})
 
-	// CopyTarStream first creates the destination directory by extracting a tar at "/",
-	// which makes the daemon mkdir var, then var/run (the symlink), then act — the exact
-	// step that fails on the broken daemon.
+	// CopyTarStream resolves the var/run symlink and creates act below its target, the
+	// exact step that fails on a broken daemon.
 	err := rc.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{})
 	require.NoError(t, err)
 }
@@ -624,6 +684,110 @@ func TestCheckVolumes(t *testing.T) {
 	}
 }
 
+func TestSanitizeOptionsHostConfig(t *testing.T) {
+	logger, _ := test.NewNullLogger()
+
+	dangerous := func() *container.HostConfig {
+		return &container.HostConfig{
+			PidMode:      "host",
+			IpcMode:      "host",
+			UTSMode:      "host",
+			CgroupnsMode: "host",
+			UsernsMode:   "host",
+			CapAdd:       []string{"ALL"},
+			SecurityOpt:  []string{"seccomp=unconfined", "apparmor=unconfined"},
+			VolumesFrom:  []string{"other"},
+			Runtime:      "runc",
+			Resources: container.Resources{
+				CgroupParent:      "/custom",
+				Devices:           []container.DeviceMapping{{PathOnHost: "/dev/sda", PathInContainer: "/dev/sda", CgroupPermissions: "rwm"}},
+				DeviceCgroupRules: []string{"a *:* rwm"},
+			},
+			Sysctls: map[string]string{"net.ipv4.ip_forward": "1"},
+		}
+	}
+
+	hostConfig := dangerous()
+	sanitizeOptionsHostConfig(logger, hostConfig)
+
+	assert.Empty(t, string(hostConfig.PidMode))
+	assert.Empty(t, string(hostConfig.IpcMode))
+	assert.Empty(t, string(hostConfig.UTSMode))
+	assert.Empty(t, string(hostConfig.CgroupnsMode))
+	assert.Empty(t, string(hostConfig.UsernsMode))
+	assert.Empty(t, hostConfig.CapAdd)
+	assert.Empty(t, hostConfig.SecurityOpt)
+	assert.Empty(t, hostConfig.Devices)
+	assert.Empty(t, hostConfig.DeviceCgroupRules)
+	assert.Empty(t, hostConfig.VolumesFrom)
+	assert.Empty(t, hostConfig.Runtime)
+	assert.Empty(t, hostConfig.CgroupParent)
+	assert.Empty(t, hostConfig.Sysctls)
+}
+
+func TestMergeContainerConfigsStripsDangerousOptionsWhenUnprivileged(t *testing.T) {
+	// OS-independent options only: --device parsing requires a linux/windows
+	// server OS, which is not guaranteed for the test host.
+	const dangerousOptions = "--pid=host --ipc=host --uts=host --cgroupns=host " +
+		"--userns=host --cap-add=ALL --security-opt seccomp=unconfined " +
+		"--security-opt apparmor=unconfined --volumes-from other " +
+		"--runtime runc --cgroup-parent /custom --sysctl net.ipv4.ip_forward=1"
+
+	t.Run("unprivileged strips host-escape options", func(t *testing.T) {
+		logger, _ := test.NewNullLogger()
+		ctx := common.WithLogger(context.Background(), logger)
+		cr := &containerReference{
+			input: &NewContainerInput{
+				Options:     dangerousOptions,
+				NetworkMode: "bridge",
+				UsernsMode:  "private",
+			},
+		}
+
+		_, hostConfig, err := cr.mergeContainerConfigs(ctx, &container.Config{}, &container.HostConfig{
+			Privileged:  false,
+			UsernsMode:  container.UsernsMode("private"),
+			NetworkMode: container.NetworkMode("bridge"),
+		})
+		require.NoError(t, err)
+
+		assert.False(t, hostConfig.Privileged)
+		assert.Empty(t, string(hostConfig.PidMode))
+		assert.Empty(t, string(hostConfig.IpcMode))
+		assert.Empty(t, string(hostConfig.UTSMode))
+		assert.Empty(t, string(hostConfig.CgroupnsMode))
+		// UsernsMode must keep the runner-controlled value, not the one from options.
+		assert.Equal(t, "private", string(hostConfig.UsernsMode))
+		assert.Empty(t, hostConfig.CapAdd)
+		assert.Empty(t, hostConfig.SecurityOpt)
+		assert.Empty(t, hostConfig.VolumesFrom)
+		assert.Empty(t, hostConfig.Runtime)
+		assert.Empty(t, hostConfig.CgroupParent)
+		assert.Empty(t, hostConfig.Sysctls)
+	})
+
+	t.Run("privileged preserves options", func(t *testing.T) {
+		logger, _ := test.NewNullLogger()
+		ctx := common.WithLogger(context.Background(), logger)
+		cr := &containerReference{
+			input: &NewContainerInput{
+				Options:     "--pid=host --cap-add=ALL --security-opt seccomp=unconfined",
+				NetworkMode: "bridge",
+			},
+		}
+
+		_, hostConfig, err := cr.mergeContainerConfigs(ctx, &container.Config{}, &container.HostConfig{
+			Privileged:  true,
+			NetworkMode: container.NetworkMode("bridge"),
+		})
+		require.NoError(t, err)
+
+		assert.Equal(t, "host", string(hostConfig.PidMode))
+		assert.Equal(t, []string{"ALL"}, hostConfig.CapAdd)
+		assert.Equal(t, []string{"seccomp=unconfined"}, hostConfig.SecurityOpt)
+	})
+}
+
 func TestCheckVolumesRejectsEscapingHostPaths(t *testing.T) {
 	logger, _ := test.NewNullLogger()
 	ctx := common.WithLogger(context.Background(), logger)
@@ -660,3 +824,22 @@ func TestCheckVolumesRejectsEscapingHostPaths(t *testing.T) {
 	})
 	assert.Empty(t, hostConf.Binds)
 }
+
+func TestMergeContainerConfigsVolumesReplaceRunnerMounts(t *testing.T) {
+	logger, _ := test.NewNullLogger()
+	ctx := common.WithLogger(context.Background(), logger)
+	cr := &containerReference{
+		input: &NewContainerInput{
+			NetworkMode: "bridge",
+			Options:     "--volume /host/tools:/opt/hostedtoolcache",
+		},
+	}
+
+	_, hostConf, err := cr.mergeContainerConfigs(ctx, &container.Config{}, &container.HostConfig{
+		Binds:  []string{"/var/run/docker.sock:/var/run/docker.sock"},
+		Mounts: []mount.Mount{{Type: mount.TypeVolume, Source: "act-toolcache", Target: "/opt/hostedtoolcache"}},
+	})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"/var/run/docker.sock:/var/run/docker.sock", "/host/tools:/opt/hostedtoolcache"}, hostConf.Binds)
+	assert.Empty(t, hostConf.Mounts)
+}

act/container/docker_stub.go

@@ -9,6 +9,7 @@ package container
 import (
 	"context"
 	"runtime"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
@@ -72,3 +73,7 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 		return nil
 	}
 }
+
+func RemoveOrphanNetworks(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
+	return nil
+}

act/container/host_environment.go

@@ -330,6 +330,10 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 	} else {
 		wd = e.Path
 	}
+	// Flush any buffered, not-yet-newline-terminated trailing line, as the docker backend
+	// does in waitForCommand, so the final line of a command's output is not lost.
+	defer common.FlushWriter(e.StdOut)
+
 	f, err := lookupPathHost(command[0], env, e.StdOut)
 	if err != nil {
 		return err

act/container/linux_container_environment_extensions.go

@@ -66,12 +66,15 @@ func (*LinuxContainerEnvironmentExtensions) JoinPathVariable(paths ...string) st
 	return strings.Join(paths, ":")
 }
 
+// DefaultToolCache is where the runner mounts the tool cache inside job containers.
+const DefaultToolCache = "/opt/hostedtoolcache"
+
 func (*LinuxContainerEnvironmentExtensions) GetRunnerContext(ctx context.Context) map[string]any {
 	return map[string]any{
 		"os":         "Linux",
 		"arch":       RunnerArch(ctx),
 		"temp":       "/tmp",
-		"tool_cache": "/opt/hostedtoolcache",
+		"tool_cache": DefaultToolCache,
 	}
 }
 

act/exprparser/interpreter_test.go

@@ -11,6 +11,7 @@ import (
 	"gitea.com/gitea/runner/act/model"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestLiterals(t *testing.T) {
@@ -523,7 +524,9 @@ func TestOperatorsBooleanEvaluation(t *testing.T) {
 			assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 
 			if expected, ok := tt.expected.(float64); ok && math.IsNaN(expected) {
-				assert.True(t, math.IsNaN(output.(float64)))
+				number, ok := output.(float64)
+				require.True(t, ok, "want a number, got %T", output)
+				assert.True(t, math.IsNaN(number))
 			} else {
 				assert.Equal(t, tt.expected, output)
 			}

act/model/workflow.go

@@ -86,11 +86,12 @@ func (w *Workflow) OnSchedule() []string {
 	case []any:
 		allSchedules := []string{}
 		for _, v := range val {
-			for k, cron := range v.(map[string]any) {
-				if k != "cron" {
-					continue
-				}
-				allSchedules = append(allSchedules, cron.(string))
+			entry, ok := v.(map[string]any)
+			if !ok {
+				continue
+			}
+			if cron, ok := entry["cron"].(string); ok {
+				allSchedules = append(allSchedules, cron)
 			}
 		}
 		return allSchedules
@@ -443,9 +444,9 @@ func normalizeMatrixValue(key string, val any) ([]any, error) {
 // Scalar values are wrapped into single-element arrays automatically.
 // Template expressions are resolved by EvaluateYamlNode before this method is
 // called; if unresolved, the literal string is wrapped as a one-element fallback.
-func (j *Job) Matrix() map[string][]any {
+func (j *Job) Matrix() (map[string][]any, error) {
 	if j.Strategy == nil || j.Strategy.RawMatrix.Kind != yaml.MappingNode {
-		return nil
+		return map[string][]any{}, nil
 	}
 
 	// Decode to flexible map first so that scalar values don't cause a type error.
@@ -455,9 +456,9 @@ func (j *Job) Matrix() map[string][]any {
 		// Fall back to the strict array-only format for backward compatibility.
 		var val map[string][]any
 		if !decodeNode(j.Strategy.RawMatrix, &val) {
-			return nil
+			return map[string][]any{}, nil
 		}
-		return val
+		return val, nil
 	}
 
 	// Convert flexible format to expected format with validation
@@ -465,12 +466,11 @@ func (j *Job) Matrix() map[string][]any {
 	for k, v := range flexVal {
 		normalized, err := normalizeMatrixValue(k, v)
 		if err != nil {
-			log.Errorf("matrix validation error: %v", err)
-			return nil
+			return nil, err
 		}
 		val[k] = normalized
 	}
-	return val
+	return val, nil
 }
 
 // GetMatrixes returns the matrix cross product
@@ -482,38 +482,38 @@ func (j *Job) GetMatrixes() ([]map[string]any, error) {
 		j.Strategy.FailFast = j.Strategy.GetFailFast()
 		j.Strategy.MaxParallel = j.Strategy.GetMaxParallel()
 
-		if m := j.Matrix(); m != nil {
+		m, err := j.Matrix()
+		if err != nil {
+			return nil, err
+		}
+		if len(m) > 0 {
 			includes := make([]map[string]any, 0)
 			extraIncludes := make([]map[string]any, 0)
+			addInclude := func(raw any) error {
+				include, ok := raw.(map[string]any)
+				if !ok {
+					return fmt.Errorf("the workflow is not valid. Matrix include %v is not a map of matrix keys to values", raw)
+				}
+				for k := range include {
+					if _, ok := m[k]; ok {
+						includes = append(includes, include)
+						return nil
+					}
+				}
+				extraIncludes = append(extraIncludes, include)
+				return nil
+			}
 			for _, v := range m["include"] {
 				switch t := v.(type) {
 				case []any:
 					for _, i := range t {
-						i := i.(map[string]any)
-						extraInclude := true
-						for k := range i {
-							if _, ok := m[k]; ok {
-								includes = append(includes, i)
-								extraInclude = false
-								break
-							}
-						}
-						if extraInclude {
-							extraIncludes = append(extraIncludes, i)
+						if err := addInclude(i); err != nil {
+							return nil, err
 						}
 					}
 				case any:
-					v := v.(map[string]any)
-					extraInclude := true
-					for k := range v {
-						if _, ok := m[k]; ok {
-							includes = append(includes, v)
-							extraInclude = false
-							break
-						}
-					}
-					if extraInclude {
-						extraIncludes = append(extraIncludes, v)
+					if err := addInclude(t); err != nil {
+						return nil, err
 					}
 				}
 			}
@@ -521,10 +521,13 @@ func (j *Job) GetMatrixes() ([]map[string]any, error) {
 
 			excludes := make([]map[string]any, 0)
 			for _, e := range m["exclude"] {
-				e := e.(map[string]any)
-				for k := range e {
+				exclude, ok := e.(map[string]any)
+				if !ok {
+					return nil, fmt.Errorf("the workflow is not valid. Matrix exclude %v is not a map of matrix keys to values", e)
+				}
+				for k := range exclude {
 					if _, ok := m[k]; ok {
-						excludes = append(excludes, e)
+						excludes = append(excludes, exclude)
 					} else {
 						// We fail completely here because that's what GitHub does for non-existing matrix keys, fail on exclude, silent skip on include
 						return nil, fmt.Errorf("the workflow is not valid. Matrix exclude key %q does not match any key within the matrix", k)

act/model/workflow_test.go

@@ -667,7 +667,9 @@ func TestReadWorkflow_Strategy(t *testing.T) {
 	matrixes, err := job.GetMatrixes()
 	assert.NoError(t, err)                          //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, matrixes, []map[string]any{{}}) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, job.Matrix(), map[string][]any(nil))
+	matrix, err := job.Matrix()
+	require.NoError(t, err)
+	assert.Empty(t, matrix)
 	assert.Equal(t, job.Strategy.MaxParallel, 2) //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, job.Strategy.FailFast, true) //nolint:testifylint // pre-existing issue from nektos/act
 
@@ -675,7 +677,9 @@ func TestReadWorkflow_Strategy(t *testing.T) {
 	matrixes, err = job.GetMatrixes()
 	assert.NoError(t, err)                          //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, matrixes, []map[string]any{{}}) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, job.Matrix(), map[string][]any(nil))
+	matrix, err = job.Matrix()
+	require.NoError(t, err)
+	assert.Empty(t, matrix)
 	assert.Equal(t, job.Strategy.MaxParallel, 4)  //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, job.Strategy.FailFast, false) //nolint:testifylint // pre-existing issue from nektos/act
 
@@ -683,7 +687,9 @@ func TestReadWorkflow_Strategy(t *testing.T) {
 	matrixes, err = job.GetMatrixes()
 	assert.NoError(t, err)                          //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, matrixes, []map[string]any{{}}) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, job.Matrix(), map[string][]any(nil))
+	matrix, err = job.Matrix()
+	require.NoError(t, err)
+	assert.Empty(t, matrix)
 	assert.Equal(t, job.Strategy.MaxParallel, 2)  //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, job.Strategy.FailFast, false) //nolint:testifylint // pre-existing issue from nektos/act
 
@@ -700,7 +706,9 @@ func TestReadWorkflow_Strategy(t *testing.T) {
 			{"datacenter": "site-b", "node-version": "12.x", "site": "dev"},
 		},
 	)
-	assert.Equal(t, job.Matrix(), //nolint:testifylint // pre-existing issue from nektos/act
+	matrix, err = job.Matrix()
+	require.NoError(t, err)
+	assert.Equal(t, matrix, //nolint:testifylint // pre-existing issue from nektos/act
 		map[string][]any{
 			"datacenter": {"site-c", "site-d"},
 			"exclude": {
@@ -1092,13 +1100,15 @@ jobs:
 				t.Fatal("job not found")
 			}
 
-			matrix := job.Matrix()
+			matrix, err := job.Matrix()
 
 			if tt.wantErr {
+				require.Error(t, err)
 				assert.Nil(t, matrix, "matrix should be nil on error")
 			} else {
+				require.NoError(t, err)
 				if tt.wantLen == 0 {
-					assert.Nil(t, matrix, "matrix should be nil for jobs without strategy")
+					assert.Empty(t, matrix, "no matrix for jobs without strategy")
 				} else {
 					assert.NotNil(t, matrix, "matrix should not be nil")
 					assert.Len(t, matrix, tt.wantLen, "matrix should have expected number of keys")
@@ -1130,11 +1140,9 @@ func TestJobMatrixValidation(t *testing.T) {
 			},
 		}
 
-		// Attempt to get matrix
-		matrix := job.Matrix()
-
-		// Should return nil due to validation error
-		assert.Nil(t, matrix, "matrix with nested map should return nil")
+		matrix, err := job.Matrix()
+		require.ErrorContains(t, err, `matrix key "config" has invalid nested object value`)
+		assert.Nil(t, matrix)
 	})
 }
 

act/runner/action.go

@@ -129,6 +129,16 @@ func readActionImpl(ctx context.Context, step *model.Step, actionDir, actionPath
 	return action, err
 }
 
+// cachedActionTar returns the action's tree from the action cache, which only a remote action
+// has an entry in.
+func cachedActionTar(ctx context.Context, step actionStep, name, includePrefix string) (io.ReadCloser, error) {
+	remote, ok := step.(*stepActionRemote)
+	if !ok {
+		return nil, fmt.Errorf("action %q is a remote action but runs as %T", name, step)
+	}
+	return step.getRunContext().Config.ActionCache.GetTarArchive(ctx, remote.cacheDir, remote.resolvedSha, includePrefix)
+}
+
 func maybeCopyToActionDir(ctx context.Context, step actionStep, actionDir, actionPath, containerActionDir string) error {
 	logger := common.Logger(ctx)
 	rc := step.getRunContext()
@@ -147,8 +157,7 @@ func maybeCopyToActionDir(ctx context.Context, step actionStep, actionDir, actio
 	}
 
 	if rc.Config != nil && rc.Config.ActionCache != nil {
-		raction := step.(*stepActionRemote)
-		ta, err := rc.Config.ActionCache.GetTarArchive(ctx, raction.cacheDir, raction.resolvedSha, "")
+		ta, err := cachedActionTar(ctx, step, stepModel.Uses, "")
 		if err != nil {
 			return err
 		}
@@ -351,8 +360,7 @@ func execAsDocker(ctx context.Context, step actionStep, actionName, actionDir, b
 				}
 				defer buildContext.Close()
 			} else if rc.Config.ActionCache != nil {
-				rstep := step.(*stepActionRemote)
-				buildContext, err = rc.Config.ActionCache.GetTarArchive(ctx, rstep.cacheDir, rstep.resolvedSha, contextDir)
+				buildContext, err = cachedActionTar(ctx, step, actionName, contextDir)
 				if err != nil {
 					return err
 				}
@@ -364,6 +372,7 @@ func execAsDocker(ctx context.Context, step actionStep, actionName, actionDir, b
 				ImageTag:     image,
 				BuildContext: buildContext,
 				Platform:     rc.Config.ContainerArchitecture,
+				BuildArgs:    rc.proxyBuildArgs(),
 			})
 			if buildContext == nil {
 				// Held across the whole build: the daemon drains contextDir lazily.
@@ -472,10 +481,7 @@ func newStepContainer(ctx context.Context, step step, image string, cmd, entrypo
 		envList = append(envList, fmt.Sprintf("%s=%s", k, v))
 	}
 
-	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_TOOL_CACHE", "/opt/hostedtoolcache"))
-	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_OS", "Linux"))
-	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_ARCH", container.RunnerArch(ctx)))
-	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_TEMP", "/tmp"))
+	envList = append(envList, rc.runnerEnv(ctx)...)
 
 	binds, mounts := rc.GetBindsAndMounts()
 	networkMode := "container:" + rc.jobContainerName()
@@ -589,8 +595,8 @@ func actionStagePaths(step actionStep) (actionDir, actionPath, actionName, conta
 	rc := step.getRunContext()
 	stepModel := step.getStepModel()
 
-	if _, ok := step.(*stepActionRemote); ok {
-		actionDir = fmt.Sprintf("%s/%s", rc.ActionCacheDir(), stepModel.UsesHash())
+	if sar, ok := step.(*stepActionRemote); ok {
+		actionDir = sar.actionDir()
 		actionPath = newRemoteAction(stepModel.Uses).Path
 	} else {
 		actionDir = filepath.Join(rc.Config.Workdir, stepModel.Uses)

act/runner/helpers_test.go

@@ -5,11 +5,9 @@ package runner
 
 import (
 	"context"
-	"net"
 	"os/exec"
 	"runtime"
 	"testing"
-	"time"
 
 	"gitea.com/gitea/runner/act/container"
 
@@ -42,18 +40,6 @@ func requireDocker(t *testing.T) {
 	}
 }
 
-// requireNetwork skips the test unless github.com is reachable. A few tests exercise behaviour
-// that inherently needs the network (force-pulling an image, resolving a remote short-sha ref);
-// gating lets the rest of the suite run offline without these failing.
-func requireNetwork(t *testing.T) {
-	t.Helper()
-	conn, err := net.DialTimeout("tcp", "github.com:443", 3*time.Second)
-	if err != nil {
-		t.Skipf("skipping: network unavailable: %v", err)
-	}
-	_ = conn.Close()
-}
-
 // requireHostTools skips the test unless every named executable is on PATH. Used by the
 // self-hosted (host environment) suite, which runs steps directly on the host.
 func requireHostTools(t *testing.T, tools ...string) {

act/runner/job_executor.go

@@ -226,11 +226,16 @@ func newJobExecutor(info jobInfo, sf stepFactory, rc *RunContext) common.Executo
 		}
 	}
 
-	// The setup section of the job log: download the actions, run the pre steps, then name the job.
+	// The setup section of the job log. The started hook goes first, so what it sets up is
+	// in place for the first action download and the first step.
+	preSteps = append(preSteps, rc.runJobStartedHook)
 	preSteps = append(preSteps, printPrepareActions(rc, preparers))
 	preSteps = append(preSteps, stepPreSteps...)
 	preSteps = append(preSteps, printCompleteJobName(rc))
 
+	// Ahead of the teardown below, while the job environment is still up.
+	postExecutor = postExecutor.Finally(rc.runJobCompletedHook)
+
 	postExecutor = postExecutor.Finally(func(ctx context.Context) error {
 		jobError := common.JobError(ctx)
 		var err error

act/runner/job_executor_test.go

@@ -33,6 +33,7 @@ import (
 )
 
 func TestJobExecutor(t *testing.T) {
+	t.Parallel()
 	// Dryrun only checks syntax/planning; all cases resolve locally, so this runs offline.
 	tables := []TestJobFileInfo{
 		{workdir, "uses-and-run-in-one-step", "push", "Invalid run/uses syntax for job:test step:Test", platforms, secrets},
@@ -46,6 +47,7 @@ func TestJobExecutor(t *testing.T) {
 	ctx := common.WithDryrun(context.Background(), true)
 	for _, table := range tables {
 		t.Run(table.workflowPath, func(t *testing.T) {
+			t.Parallel()
 			table.runTest(ctx, t, &Config{})
 		})
 	}

act/runner/job_hooks.go

@@ -0,0 +1,115 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package runner
+
+import (
+	"cmp"
+	"context"
+	"fmt"
+	"maps"
+	"path"
+	"strings"
+
+	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/container"
+)
+
+// GitHub's job-hook variables, read as a fallback when the settings are unset.
+const (
+	jobStartedHookEnv   = "ACTIONS_RUNNER_HOOK_JOB_STARTED"
+	jobCompletedHookEnv = "ACTIONS_RUNNER_HOOK_JOB_COMPLETED"
+)
+
+// Kept apart from the per-step file-command files, which are truncated on every step.
+const (
+	hookEnvFileCommand  = "workflow/hook-envs.txt"
+	hookPathFileCommand = "workflow/hook-path.txt"
+)
+
+func (rc *RunContext) runJobStartedHook(ctx context.Context) error {
+	return rc.runJobHook(ctx, cmp.Or(rc.Config.JobStartedHook, rc.Config.Env[jobStartedHookEnv]), "job started")
+}
+
+func (rc *RunContext) runJobCompletedHook(ctx context.Context) error {
+	return rc.runJobHook(ctx, cmp.Or(rc.Config.JobCompletedHook, rc.Config.Env[jobCompletedHookEnv]), "job completed")
+}
+
+// runJobHook runs one hook in the job environment. Either hook failing fails the job, as
+// on GitHub, where the operator is responsible for the hook's own resilience.
+func (rc *RunContext) runJobHook(ctx context.Context, hookPath, name string) error {
+	if hookPath == "" {
+		return nil
+	}
+
+	cmd, shell := hookCommand(hookPath)
+	rawLogger := common.Logger(ctx).WithField(rawOutputField, true)
+	defer rawLogger.Infof("::endgroup::")
+	rawLogger.Infof("::group::Run '%s'", escapeCommandData(hookPath))
+	rawLogger.Infof("A %s hook has been configured by the runner administrator", name)
+	if shell != "" {
+		rawLogger.Infof("shell: %s", shell)
+	}
+
+	env := maps.Clone(rc.GetEnv())
+	if jobContainer := rc.Run.Job().Container(); jobContainer != nil {
+		maps.Copy(env, jobContainer.Env)
+	}
+	rc.withGithubEnv(ctx, rc.getGithubContext(ctx), env)
+	rc.ApplyExtraPath(ctx, &env)
+
+	err := rc.setupHookFileCommands(ctx, env)
+	if err == nil {
+		err = rc.JobContainer.Exec(cmd, env, "", "")(ctx)
+	}
+	// Processed even on failure, so a hook that exports what it managed to set up before
+	// failing still hands it to the job.
+	err = cmp.Or(err, rc.processHookFileCommands(ctx))
+	if err == nil {
+		return nil
+	}
+
+	err = fmt.Errorf("the %s hook %q failed: %w", name, hookPath, err)
+	// Flip the job status the way a failing pre step does, so success()-default main steps
+	// skip and the task is reported failed.
+	reportStepError(ctx, rc, err)
+	return err
+}
+
+// setupHookFileCommands points the hook at its GITHUB_ENV and GITHUB_PATH files, so it can
+// export to the job's steps, and truncates them so the second hook does not re-read what
+// the first one wrote.
+func (rc *RunContext) setupHookFileCommands(ctx context.Context, env map[string]string) error {
+	actPath := rc.JobContainer.GetActPath()
+	env["GITHUB_ENV"] = path.Join(actPath, hookEnvFileCommand)
+	env["GITHUB_PATH"] = path.Join(actPath, hookPathFileCommand)
+	env["GITEA_ENV"] = env["GITHUB_ENV"]
+	env["GITEA_PATH"] = env["GITHUB_PATH"]
+
+	return rc.JobContainer.Copy(actPath,
+		&container.FileEntry{Name: hookEnvFileCommand, Mode: 0o666},
+		&container.FileEntry{Name: hookPathFileCommand, Mode: 0o666},
+	)(ctx)
+}
+
+func (rc *RunContext) processHookFileCommands(ctx context.Context) error {
+	if err := processRunnerEnvFileCommand(ctx, hookEnvFileCommand, rc, rc.setEnv); err != nil {
+		return err
+	}
+	return rc.UpdateExtraPath(ctx, path.Join(rc.JobContainer.GetActPath(), hookPathFileCommand))
+}
+
+// hookCommand mirrors actions/runner, which deliberately does not apply the shell flags it
+// gives `run:` steps — a hook sets its own. See docs/adrs/1751-runner-job-hooks.md there.
+// The second return value is how the invocation is shown in the log, empty when the file is
+// executed directly.
+func hookCommand(hookPath string) (cmd []string, shell string) {
+	switch strings.ToLower(path.Ext(hookPath)) {
+	case ".sh":
+		return []string{"bash", "-e", hookPath}, "bash -e {0}"
+	case ".ps1":
+		return []string{"pwsh", "-command", ". '" + hookPath + "'"}, `pwsh -command ". '{0}'"`
+	default:
+		return []string{hookPath}, ""
+	}
+}

act/runner/job_hooks_test.go

@@ -0,0 +1,162 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package runner
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"maps"
+	"testing"
+
+	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/model"
+
+	"github.com/sirupsen/logrus/hooks/test"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hookContainer records the command a hook was run with and answers with what the hook
+// wrote to its GITHUB_ENV and GITHUB_PATH files.
+type hookContainer struct {
+	fakeContainer
+	cmd     []string
+	env     map[string]string
+	err     error
+	envFile map[string]string
+	pathTar []byte
+}
+
+func (c *hookContainer) ToContainerPath(path string) string { return path }
+func (c *hookContainer) IsEnvironmentCaseInsensitive() bool { return false }
+
+func (c *hookContainer) GetRunnerContext(context.Context) map[string]any {
+	return map[string]any{"os": "Linux"}
+}
+
+func (c *hookContainer) Exec(command []string, env map[string]string, _, _ string) common.Executor {
+	return func(context.Context) error {
+		c.cmd, c.env = command, env
+		return c.err
+	}
+}
+
+func (c *hookContainer) UpdateFromEnv(_ string, env *map[string]string) common.Executor {
+	return func(context.Context) error {
+		maps.Copy(*env, c.envFile)
+		return nil
+	}
+}
+
+func (c *hookContainer) GetContainerArchive(context.Context, string) (io.ReadCloser, error) {
+	return io.NopCloser(bytes.NewReader(c.pathTar)), nil
+}
+
+// newHookRunContext returns a RunContext and the context to run a hook with, whose logger is
+// silenced so the hook's job-log output does not reach the test output.
+func newHookRunContext(jobContainer *hookContainer, config *Config) (*RunContext, context.Context) {
+	// Env is left nil so that it is built from the config, as it is for a real job.
+	rc := &RunContext{
+		Config:       config,
+		Run:          &model.Run{JobID: "job", Workflow: &model.Workflow{Jobs: map[string]*model.Job{"job": {}}}},
+		JobContainer: jobContainer,
+	}
+	logger, _ := test.NewNullLogger()
+	ctx := common.WithJobErrorContainer(common.WithLogger(context.Background(), logger.WithField("test", true)))
+	rc.ExprEval = rc.NewExpressionEvaluator(ctx)
+	return rc, ctx
+}
+
+func TestRunJobHook(t *testing.T) {
+	t.Run("runs the hook with the job environment", func(t *testing.T) {
+		jobContainer := &hookContainer{}
+		rc, ctx := newHookRunContext(jobContainer, &Config{
+			JobStartedHook: "/hooks/started.sh",
+			Env:            map[string]string{"A_VAR": "value", jobStartedHookEnv: "/from/env.sh"},
+		})
+
+		require.NoError(t, rc.runJobStartedHook(ctx))
+
+		// The setting wins over the environment variable.
+		assert.Equal(t, []string{"bash", "-e", "/hooks/started.sh"}, jobContainer.cmd)
+		assert.Equal(t, "value", jobContainer.env["A_VAR"])
+		// The github environment is there too, so a hook can tell which job it runs for.
+		assert.Equal(t, "job", jobContainer.env["GITHUB_JOB"])
+		assert.Equal(t, "/var/run/act/workflow/hook-envs.txt", jobContainer.env["GITHUB_ENV"])
+		assert.Equal(t, "/var/run/act/workflow/hook-path.txt", jobContainer.env["GITHUB_PATH"])
+	})
+
+	// Each hook reads its own variable, so a swapped constant cannot pass.
+	t.Run("falls back to the GitHub environment variables", func(t *testing.T) {
+		for name, hook := range map[string]struct {
+			env string
+			run func(*RunContext, context.Context) error
+		}{
+			"started":   {jobStartedHookEnv, (*RunContext).runJobStartedHook},
+			"completed": {jobCompletedHookEnv, (*RunContext).runJobCompletedHook},
+		} {
+			t.Run(name, func(t *testing.T) {
+				jobContainer := &hookContainer{}
+				rc, ctx := newHookRunContext(jobContainer, &Config{Env: map[string]string{hook.env: "/from/env.sh"}})
+
+				require.NoError(t, hook.run(rc, ctx))
+				assert.Equal(t, []string{"bash", "-e", "/from/env.sh"}, jobContainer.cmd)
+			})
+		}
+	})
+
+	t.Run("exports what the hook wrote to GITHUB_ENV and GITHUB_PATH", func(t *testing.T) {
+		jobContainer := &hookContainer{
+			envFile: map[string]string{"FROM_HOOK": "1"},
+			pathTar: tarArchive(t, tarEntry{name: "hook-path.txt", body: "/opt/tool/bin\n"}),
+		}
+		rc, ctx := newHookRunContext(jobContainer, &Config{JobStartedHook: "/hooks/started.sh"})
+
+		require.NoError(t, rc.runJobStartedHook(ctx))
+
+		assert.Equal(t, "1", rc.Env["FROM_HOOK"])
+		assert.Equal(t, []string{"/opt/tool/bin"}, rc.ExtraPath)
+	})
+
+	t.Run("a failing hook fails the job", func(t *testing.T) {
+		rc, ctx := newHookRunContext(&hookContainer{err: errors.New("boom")}, &Config{JobStartedHook: "/hooks/started.sh"})
+
+		err := rc.runJobStartedHook(ctx)
+
+		require.ErrorContains(t, err, `the job started hook "/hooks/started.sh" failed`)
+		require.ErrorContains(t, err, "boom")
+		// The failure has to flip the job status, or success()-default steps would still
+		// run and the task would be reported successful despite the missing setup.
+		assert.Equal(t, "failure", rc.getJobContext().Status)
+		require.ErrorContains(t, common.JobError(ctx), "boom")
+	})
+
+	t.Run("is a no-op without a hook", func(t *testing.T) {
+		jobContainer := &hookContainer{}
+		rc, ctx := newHookRunContext(jobContainer, &Config{})
+
+		require.NoError(t, rc.runJobStartedHook(ctx))
+		require.NoError(t, rc.runJobCompletedHook(ctx))
+		assert.Nil(t, jobContainer.cmd)
+	})
+}
+
+// actions/runner deliberately runs a hook without the flags it gives `run:` steps, and an
+// executable without a known extension speaks for itself through its shebang.
+func TestHookCommand(t *testing.T) {
+	for hookPath, want := range map[string]struct {
+		cmd   []string
+		shell string
+	}{
+		"/hooks/started.sh":  {[]string{"bash", "-e", "/hooks/started.sh"}, "bash -e {0}"},
+		"/hooks/started.PS1": {[]string{"pwsh", "-command", ". '/hooks/started.PS1'"}, `pwsh -command ". '{0}'"`},
+		"/hooks/started":     {[]string{"/hooks/started"}, ""},
+	} {
+		cmd, shell := hookCommand(hookPath)
+		assert.Equal(t, want.cmd, cmd, hookPath)
+		assert.Equal(t, want.shell, shell, hookPath)
+	}
+}

act/runner/logger.go

@@ -7,8 +7,11 @@ package runner
 import (
 	"bytes"
 	"context"
+	"encoding/base64"
+	"encoding/json"
 	"fmt"
 	"io"
+	"net/url"
 	"os"
 	"slices"
 	"strings"
@@ -167,6 +170,76 @@ func withStepLogger(ctx context.Context, stepNumber int, stepID, stepName, stage
 
 type entryProcessor func(entry *logrus.Entry) *logrus.Entry
 
+// secretValueEncoders are the shapes a secret takes on its way into a log: a base64
+// payload, a JSON string, or a URL component. An action that serializes a secret leaks
+// it in one of these forms, which a mask of the verbatim value alone does not catch, so
+// every form is masked as well. This mirrors the value encoders of GitHub's runner.
+var secretValueEncoders = []func(string) string{
+	func(v string) string { return base64.StdEncoding.EncodeToString([]byte(v)) },
+	base64ShiftEncoder(1),
+	base64ShiftEncoder(2),
+	jsonStringEscape,
+	jsonStringEscapeNoHTML,
+	url.QueryEscape,
+	url.PathEscape,
+}
+
+// minShiftedBase64Len is the shortest shifted base64 fragment worth masking. A shorter
+// one carries too few bytes of the secret to identify it and would mask unrelated output.
+const minShiftedBase64Len = 8
+
+// base64ShiftEncoder returns the part of a secret's base64 form that survives when the
+// secret does not start on a 3-byte boundary of the payload it is embedded in. base64
+// encodes three bytes at a time, so `Authorization: Basic base64("user:token")` contains
+// the base64 of the token alone only when the prefix length happens to be a multiple of
+// three; at the other two alignments the encoding of the whole value differs. Encoding
+// the secret behind shift filler bytes reproduces those alignments, which is what the
+// Base64StringEscapeShift1/2 encoders of GitHub's runner do.
+//
+// The leading group (filler mixed with the secret's first bytes) and the trailing group
+// (padded here, but continuing into whatever follows the secret) are dropped, leaving the
+// group-aligned middle that does appear verbatim in the log.
+func base64ShiftEncoder(shift int) func(string) string {
+	return func(v string) string {
+		buf := make([]byte, shift+len(v))
+		copy(buf[shift:], v)
+		encoded := base64.StdEncoding.EncodeToString(buf)
+		// Keep only the aligned middle, and only when enough of it is left to be a
+		// distinctive pattern rather than a fragment that matches unrelated output.
+		if len(encoded) < 8+minShiftedBase64Len {
+			return ""
+		}
+		return encoded[4 : len(encoded)-4]
+	}
+}
+
+// jsonStringEscape returns v as it appears inside a JSON string, without the quotes,
+// which is what `toJSON(secrets)` or any action logging a JSON body produces. Go's encoder
+// escapes <, >, & (as act's own toJSON does); the non-HTML variant below covers the runtimes
+// that do not. When v has none of those characters both forms are equal and deduplicated.
+func jsonStringEscape(v string) string {
+	encoded, err := json.Marshal(v)
+	if err != nil {
+		return v
+	}
+	return string(encoded[1 : len(encoded)-1])
+}
+
+// jsonStringEscapeNoHTML is jsonStringEscape without HTML escaping, matching the JSON a
+// JavaScript (JSON.stringify) or .NET action emits, so a secret containing < > or & is
+// masked in that form too.
+func jsonStringEscapeNoHTML(v string) string {
+	var buf bytes.Buffer
+	enc := json.NewEncoder(&buf)
+	enc.SetEscapeHTML(false)
+	if err := enc.Encode(v); err != nil {
+		return v
+	}
+	// Encode appends a newline; drop it along with the surrounding quotes.
+	encoded := strings.TrimRight(buf.String(), "\n")
+	return encoded[1 : len(encoded)-1]
+}
+
 func AppendSecretMasker(oldnew []string, v string) []string {
 	ret := oldnew
 
@@ -182,6 +255,21 @@ func AppendSecretMasker(oldnew []string, v string) []string {
 		}
 	}
 
+	// The encoded forms are derived from the whole value: a multi-line secret is
+	// encoded as one string, not line by line.
+	trimmed := strings.TrimSpace(v)
+	if len(trimmed) <= 1 {
+		return ret
+	}
+	for _, encode := range secretValueEncoders {
+		encoded := encode(trimmed)
+		// An encoding that leaves the value unchanged is already masked above.
+		if encoded == trimmed || len(encoded) <= 1 || slices.Contains(ret, encoded) {
+			continue
+		}
+		ret = append(ret, encoded, "***")
+	}
+
 	return ret
 }
 
@@ -194,6 +282,18 @@ func valueMasker(insecureSecrets bool, secrets map[string]string) entryProcessor
 	}
 	oldnew = slices.Clip(oldnew)
 	defReplacer := strings.NewReplacer(oldnew...)
+
+	// A ::add-mask:: only ever appends to the job's mask slice, so the replacer built for
+	// it stays valid until the slice grows. Cache it, keyed by the slice itself and its
+	// length, instead of encoding every secret and mask again for each log line.
+	var (
+		mu       sync.Mutex
+		masksRef *[]string
+		pairs    []string
+		masked   int
+		replacer *strings.Replacer
+	)
+
 	return func(entry *logrus.Entry) *logrus.Entry {
 		if insecureSecrets {
 			return entry
@@ -203,16 +303,27 @@ func valueMasker(insecureSecrets bool, secrets map[string]string) entryProcessor
 
 		if len(*masks) == 0 {
 			entry.Message = defReplacer.Replace(entry.Message)
-		} else {
-			cmasker := oldnew
-
-			for _, v := range *masks {
-				cmasker = AppendSecretMasker(cmasker, v)
-			}
-
-			entry.Message = strings.NewReplacer(cmasker...).Replace(entry.Message)
+			return entry
 		}
 
+		mu.Lock()
+		// A composite action logs through the same masker with its own mask slice, so a
+		// different slice starts the cache over.
+		if masksRef != masks {
+			masksRef, pairs, masked, replacer = masks, oldnew, 0, nil
+		}
+		if replacer == nil || masked != len(*masks) {
+			for _, v := range (*masks)[masked:] {
+				pairs = AppendSecretMasker(pairs, v)
+			}
+			masked = len(*masks)
+			replacer = strings.NewReplacer(pairs...)
+		}
+		cmasker := replacer
+		mu.Unlock()
+
+		entry.Message = cmasker.Replace(entry.Message)
+
 		return entry
 	}
 }

act/runner/logger_test.go

@@ -4,7 +4,9 @@
 package runner
 
 import (
+	"encoding/base64"
 	"io"
+	"net/url"
 	"strings"
 	"testing"
 
@@ -59,6 +61,136 @@ func TestValueMasker(t *testing.T) {
 	}
 }
 
+// A secret that reaches the log through an encoding — a base64 payload, a JSON body, a
+// URL — must be masked as well: masking only the verbatim value leaks it.
+func TestValueMaskerEncodedSecrets(t *testing.T) {
+	secret := `p@ss w"rd/1`
+	masker := valueMasker(false, map[string]string{"TOKEN": secret})
+
+	for _, tc := range []struct {
+		name string
+		line string
+	}{
+		{"verbatim", "the token is " + secret},
+		{"base64", "Authorization: Basic " + base64.StdEncoding.EncodeToString([]byte(secret))},
+		{"json", `{"token":"` + jsonStringEscape(secret) + `"}`},
+		{"query escaped", "https://example.com/?token=" + url.QueryEscape(secret)},
+		{"path escaped", "https://example.com/" + url.PathEscape(secret) + "/x"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			entry := masker(&logrus.Entry{Context: t.Context(), Message: tc.line})
+
+			assert.Contains(t, entry.Message, "***")
+			assert.NotContains(t, entry.Message, secret)
+			assert.NotContains(t, entry.Message, base64.StdEncoding.EncodeToString([]byte(secret)))
+			assert.NotContains(t, entry.Message, url.QueryEscape(secret))
+		})
+	}
+}
+
+// A secret containing " together with <, > or & serializes to JSON differently depending
+// on the runtime: act's own toJSON (and Go) HTML-escape <>&, while a JavaScript
+// (JSON.stringify) or .NET action leaves them literal. The secret must be masked in either
+// form, so a JS-serialized JSON body does not leak it.
+func TestValueMaskerJSONEscapesBothWays(t *testing.T) {
+	secret := `a"<b>&c`
+	masker := valueMasker(false, map[string]string{"TOKEN": secret})
+
+	for _, tc := range []struct {
+		name string
+		form string
+	}{
+		{"html escaped (act toJSON / Go)", jsonStringEscape(secret)},
+		{"literal (JS JSON.stringify / .NET)", jsonStringEscapeNoHTML(secret)},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			entry := masker(&logrus.Entry{Context: t.Context(), Message: `{"t":"` + tc.form + `"}`})
+
+			assert.Contains(t, entry.Message, "***")
+			assert.NotContains(t, entry.Message, tc.form)
+		})
+	}
+}
+
+// ::add-mask:: values go through the same masker, so they get the same treatment.
+func TestValueMaskerEncodedMasks(t *testing.T) {
+	masks := []string{"s3cr3t value"}
+	masker := valueMasker(false, nil)
+
+	entry := masker(&logrus.Entry{
+		Context: WithMasks(t.Context(), &masks),
+		Message: "encoded: " + base64.StdEncoding.EncodeToString([]byte("s3cr3t value")),
+	})
+
+	assert.Equal(t, "encoded: ***", entry.Message)
+}
+
+// A token in a Basic auth header is base64'd together with the user name, so the token's
+// own base64 only appears when the prefix length is a multiple of three. The other two
+// alignments must be masked as well, or `Authorization: Basic base64("user:token")` leaks
+// the token to anyone who can decode the log.
+func TestValueMaskerBase64Alignments(t *testing.T) {
+	secret := "s3cr3t-token-value"
+	masker := valueMasker(false, map[string]string{"TOKEN": secret})
+
+	// One prefix per alignment: len%3 of 0, 1 and 2.
+	for _, prefix := range []string{"x-access-token:", "user:", "ab:"} {
+		t.Run(prefix, func(t *testing.T) {
+			encoded := base64.StdEncoding.EncodeToString([]byte(prefix + secret))
+			entry := masker(&logrus.Entry{Context: t.Context(), Message: "Authorization: Basic " + encoded})
+
+			assert.Contains(t, entry.Message, "***")
+			// The aligned middle of the secret must be gone, so the payload can no longer be
+			// decoded back into the token.
+			assert.NotEqual(t, "Authorization: Basic "+encoded, entry.Message)
+			decodable := strings.TrimPrefix(entry.Message, "Authorization: Basic ")
+			decoded, err := base64.StdEncoding.DecodeString(decodable)
+			if err == nil {
+				assert.NotContains(t, string(decoded), secret)
+			}
+		})
+	}
+}
+
+// The masker caches its replacer, so it has to notice both a mask appended to the same
+// slice and a composite action logging with a slice of its own.
+func TestValueMaskerCachedReplacerSeesNewMasks(t *testing.T) {
+	masker := valueMasker(false, map[string]string{"TOKEN": "secret-token"})
+	mask := func(masks *[]string, message string) string {
+		return masker(&logrus.Entry{Context: WithMasks(t.Context(), masks), Message: message}).Message
+	}
+
+	job := []string{"first mask"}
+	assert.Equal(t, "a *** and ***", mask(&job, "a first mask and secret-token"))
+
+	// ::add-mask:: appends to the same slice
+	job = append(job, "second mask")
+	assert.Equal(t, "*** and ***", mask(&job, "first mask and second mask"))
+
+	// a composite action brings its own slice
+	composite := []string{"composite mask"}
+	assert.Equal(t, "*** but first mask", mask(&composite, "composite mask but first mask"))
+
+	// and the job's masks still apply once it is back
+	assert.Equal(t, "*** and *** but composite mask", mask(&job, "first mask and second mask but composite mask"))
+}
+
+func TestAppendSecretMaskerSkipsUselessEncodings(t *testing.T) {
+	// A token with no character an escape would touch only gains its base64 forms:
+	// JSON, query and path escaping all leave it unchanged.
+	pairs := AppendSecretMasker(nil, "plaintoken")
+	assert.Equal(t, []string{
+		"plaintoken", "***",
+		base64.StdEncoding.EncodeToString([]byte("plaintoken")), "***",
+		// The two shifted alignments, each without its leading and trailing group.
+		"YWludG9r", "***",
+		"bGFpbnRv", "***",
+	}, pairs)
+
+	// Too short to mask.
+	assert.Empty(t, AppendSecretMasker(nil, "x"))
+}
+
 func TestJobLogFormatterDecodesCommandData(t *testing.T) {
 	logger := logrus.New()
 	logger.Out = io.Discard

act/runner/run_context.go

@@ -22,15 +22,17 @@ import (
 	"runtime"
 	"slices"
 	"strings"
-	"sync"
 	"time"
 
 	"gitea.com/gitea/runner/act/common"
 	"gitea.com/gitea/runner/act/container"
 	"gitea.com/gitea/runner/act/exprparser"
 	"gitea.com/gitea/runner/act/model"
+	"gitea.com/gitea/runner/internal/pkg/lock"
 
+	"github.com/docker/cli/cli/compose/loader"
 	"github.com/docker/go-connections/nat"
+	"github.com/moby/moby/api/types/mount"
 	"github.com/opencontainers/selinux/go-selinux"
 )
 
@@ -204,52 +206,93 @@ func (rc *RunContext) validVolumes() []string {
 		getDockerDaemonSocketMountPath(rc.containerDaemonSocket()))
 }
 
+// toolCache returns the tool cache path the job sees, relocatable through RUNNER_TOOL_CACHE.
+func (rc *RunContext) toolCache(fallback string) string {
+	if path := rc.GetEnv()["RUNNER_TOOL_CACHE"]; path != "" {
+		return path
+	}
+	return fallback
+}
+
+// runnerEnv returns a container's RUNNER_* variables, derived from the values runner.tool_cache
+// and friends report so the two cannot drift apart.
+func (rc *RunContext) runnerEnv(ctx context.Context) []string {
+	ext := container.LinuxContainerEnvironmentExtensions{}
+	runnerContext := ext.GetRunnerContext(ctx)
+	runnerContext["tool_cache"] = rc.toolCache(container.DefaultToolCache)
+
+	env := make([]string, 0, len(runnerContext))
+	for key, value := range runnerContext {
+		env = append(env, fmt.Sprintf("RUNNER_%s=%s", strings.ToUpper(key), value))
+	}
+	slices.Sort(env)
+	return env
+}
+
+// splitVolumes routes volume specs into binds and a source:target mount map, and returns the
+// container paths they mount onto. Only a plain source:target volume fits the map, everything
+// else (anonymous volumes, host binds, mount options) stays a bind.
+func splitVolumes(specs []string) ([]string, map[string]string, map[string]bool) {
+	binds := []string{}
+	mounts := map[string]string{}
+	targets := map[string]bool{}
+
+	for _, spec := range specs {
+		parsed, err := loader.ParseVolume(spec)
+		if err != nil {
+			binds = append(binds, spec) // let Docker report the malformed spec
+			continue
+		}
+		targets[parsed.Target] = true
+		if parsed.Type == string(mount.TypeVolume) && parsed.Source != "" && !parsed.ReadOnly {
+			mounts[parsed.Source] = parsed.Target
+		} else {
+			binds = append(binds, spec)
+		}
+	}
+	return binds, mounts, targets
+}
+
 // Returns the binds and mounts for the container, resolving paths as appopriate
 func (rc *RunContext) GetBindsAndMounts() ([]string, map[string]string) {
 	name := rc.jobContainerName()
-
-	binds := []string{}
-	if daemonSocket := rc.containerDaemonSocket(); daemonSocket != "-" {
-		daemonPath := getDockerDaemonSocketMountPath(daemonSocket)
-		binds = append(binds, fmt.Sprintf("%s:%s", daemonPath, "/var/run/docker.sock"))
-	}
-
 	ext := container.LinuxContainerEnvironmentExtensions{}
 
-	mounts := map[string]string{
-		"act-toolcache": "/opt/hostedtoolcache",
-		name + "-env":   ext.GetActPath(),
-	}
-
+	var volumes []string
 	if job := rc.Run.Job(); job != nil {
 		if container := job.Container(); container != nil {
 			for _, v := range container.Volumes {
 				if rc.ExprEval != nil {
 					v = rc.ExprEval.Interpolate(context.Background(), v)
 				}
-				if !strings.Contains(v, ":") || filepath.IsAbs(v) {
-					// Bind anonymous volume or host file.
-					binds = append(binds, v)
-				} else {
-					// Mount existing volume.
-					paths := strings.SplitN(v, ":", 2)
-					mounts[paths[0]] = paths[1]
-				}
+				volumes = append(volumes, v)
 			}
 		}
 	}
+	// the runner's own mounts below yield to the targets the job claims
+	binds, mounts, claimed := splitVolumes(volumes)
 
-	if rc.Config.BindWorkdir {
-		bindModifiers := ""
-		if runtime.GOOS == "darwin" {
-			bindModifiers = ":delegated"
+	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
+	}
+	mounts[name+"-env"] = ext.GetActPath() // runner-internal, never overridable
+
+	if workdir := ext.ToContainerPath(rc.Config.Workdir); !claimed[workdir] {
+		if rc.Config.BindWorkdir {
+			bindModifiers := ""
+			if runtime.GOOS == "darwin" {
+				bindModifiers = ":delegated"
+			}
+			if selinux.GetEnabled() {
+				bindModifiers = ":z"
+			}
+			binds = append(binds, fmt.Sprintf("%s:%s%s", rc.Config.Workdir, workdir, bindModifiers))
+		} else {
+			mounts[name] = workdir
 		}
-		if selinux.GetEnabled() {
-			bindModifiers = ":z"
-		}
-		binds = append(binds, fmt.Sprintf("%s:%s%s", rc.Config.Workdir, ext.ToContainerPath(rc.Config.Workdir), bindModifiers))
-	} else {
-		mounts[name] = ext.ToContainerPath(rc.Config.Workdir)
 	}
 
 	return binds, mounts
@@ -283,7 +326,10 @@ func (rc *RunContext) startHostEnvironment() common.Executor {
 		if err := os.MkdirAll(runnerTmp, 0o777); err != nil {
 			return err
 		}
-		toolCache := filepath.Join(cacheDir, "tool_cache")
+		toolCache := rc.toolCache(filepath.Join(cacheDir, "tool_cache"))
+		if err := os.MkdirAll(toolCache, 0o777); err != nil {
+			return err
+		}
 		rc.JobContainer = &container.HostEnvironment{
 			Path:         path,
 			TmpDir:       runnerTmp,
@@ -368,10 +414,7 @@ func (rc *RunContext) startJobContainer() common.Executor {
 
 		envList := make([]string, 0)
 
-		envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_TOOL_CACHE", "/opt/hostedtoolcache"))
-		envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_OS", "Linux"))
-		envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_ARCH", container.RunnerArch(ctx)))
-		envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_TEMP", "/tmp"))
+		envList = append(envList, rc.runnerEnv(ctx)...)
 		envList = append(envList, fmt.Sprintf("%s=%s", "LANG", "C.UTF-8")) // Use same locale as GitHub Actions
 
 		ext := container.LinuxContainerEnvironmentExtensions{}
@@ -392,7 +435,9 @@ func (rc *RunContext) startJobContainer() common.Executor {
 				continue
 			}
 			// interpolate env
-			interpolatedEnvs := make(map[string]string, len(spec.Env))
+			interpolatedEnvs := make(map[string]string, len(spec.Env)+len(rc.Config.ProxyEnv))
+			// a service reaches the internet the way the job does; its own env still wins
+			maps0.Copy(interpolatedEnvs, rc.Config.ProxyEnv)
 			for k, v := range spec.Env {
 				interpolatedEnvs[k] = rc.ExprEval.Interpolate(ctx, v)
 			}
@@ -672,13 +717,10 @@ func (rc *RunContext) ActionCacheDir() string {
 // jobMutexes serializes per-job result/output aggregation across the matrix combinations that
 // share one *model.Job and run in parallel. Keyed by the shared *model.Job (mirrors the
 // per-directory AcquireCloneLock pattern).
-var jobMutexes sync.Map // key: *model.Job; value: *sync.Mutex
+var jobMutexes lock.Keyed[*model.Job]
 
 func lockJob(job *model.Job) func() {
-	v, _ := jobMutexes.LoadOrStore(job, &sync.Mutex{})
-	mu := v.(*sync.Mutex)
-	mu.Lock()
-	return mu.Unlock
+	return jobMutexes.Lock(job)
 }
 
 func (rc *RunContext) interpolateOutputs() common.Executor {
@@ -929,6 +971,20 @@ func (rc *RunContext) isEnabled(ctx context.Context) (bool, error) {
 	return true, nil
 }
 
+// proxyBuildArgs returns the job's proxy variables as docker build args. The docker CLI
+// pre-populates these from its own client configuration, but act builds through the API,
+// so without them a Dockerfile action's RUN steps have no network behind a proxy.
+func (rc *RunContext) proxyBuildArgs() map[string]*string {
+	if len(rc.Config.ProxyEnv) == 0 {
+		return nil
+	}
+	args := make(map[string]*string, len(rc.Config.ProxyEnv))
+	for name, value := range rc.Config.ProxyEnv {
+		args[name] = &value
+	}
+	return args
+}
+
 func mergeMaps(maps ...map[string]string) map[string]string {
 	rtnMap := make(map[string]string)
 	for _, m := range maps {
@@ -992,6 +1048,8 @@ func (rc *RunContext) getRunnerContext(ctx context.Context) map[string]any {
 	runnerContext := map[string]any{}
 	if rc.JobContainer != nil {
 		maps0.Copy(runnerContext, rc.JobContainer.GetRunnerContext(ctx))
+		defaultToolCache, _ := runnerContext["tool_cache"].(string)
+		runnerContext["tool_cache"] = rc.toolCache(defaultToolCache)
 	}
 	runnerContext["name"] = rc.Config.RunnerName
 	runnerContext["environment"] = "self-hosted"
@@ -1363,24 +1421,9 @@ func (rc *RunContext) handleServiceCredentials(ctx context.Context, creds map[st
 
 // GetServiceBindsAndMounts returns the binds and mounts for the service container, resolving paths as appopriate
 func (rc *RunContext) GetServiceBindsAndMounts(svcVolumes []string) ([]string, map[string]string) {
-	binds := []string{}
-	if daemonSocket := rc.containerDaemonSocket(); daemonSocket != "-" {
-		daemonPath := getDockerDaemonSocketMountPath(daemonSocket)
-		binds = append(binds, fmt.Sprintf("%s:%s", daemonPath, "/var/run/docker.sock"))
+	binds, mounts, claimed := splitVolumes(svcVolumes)
+	if daemonSocket := rc.containerDaemonSocket(); daemonSocket != "-" && !claimed["/var/run/docker.sock"] {
+		binds = append(binds, getDockerDaemonSocketMountPath(daemonSocket)+":/var/run/docker.sock")
 	}
-
-	mounts := map[string]string{}
-
-	for _, v := range svcVolumes {
-		if !strings.Contains(v, ":") || filepath.IsAbs(v) {
-			// Bind anonymous volume or host file.
-			binds = append(binds, v)
-		} else {
-			// Mount existing volume.
-			paths := strings.SplitN(v, ":", 2)
-			mounts[paths[0]] = paths[1]
-		}
-	}
-
 	return binds, mounts
 }

act/runner/run_context_test.go

@@ -19,6 +19,7 @@ import (
 	"gitea.com/gitea/runner/act/exprparser"
 	"gitea.com/gitea/runner/act/model"
 
+	"github.com/docker/cli/cli/compose/loader"
 	log "github.com/sirupsen/logrus"
 	assert "github.com/stretchr/testify/assert"
 	require "github.com/stretchr/testify/require"
@@ -291,6 +292,83 @@ jobs:
 	require.Equal(t, [2]string{"", ""}, credentials["redis:latest"])
 }
 
+// A service container reaches the internet the same way the job does, so it inherits the
+// job's proxy; a service that sets the variable itself keeps its own value.
+func TestStartJobContainerGivesServicesTheJobProxy(t *testing.T) {
+	workflow, err := model.ReadWorkflow(strings.NewReader(`
+name: test
+on: push
+jobs:
+  job:
+    runs-on: ubuntu-latest
+    container:
+      image: registry.example/job:latest
+    services:
+      redis:
+        image: redis:latest
+      db:
+        image: postgres:latest
+        env:
+          no_proxy: db-only.example
+    steps: []
+`))
+	require.NoError(t, err)
+
+	var inputs []*container.NewContainerInput
+	origNewContainer := newContainer
+	newContainer = func(input *container.NewContainerInput) container.ExecutionsEnvironment {
+		inputs = append(inputs, input)
+		return fakeContainer{}
+	}
+	t.Cleanup(func() { newContainer = origNewContainer })
+
+	rc := &RunContext{
+		Name: "test",
+		Config: &Config{
+			Workdir:              "/tmp",
+			ContainerNetworkMode: "host",
+			ReuseContainers:      true,
+			Env:                  map[string]string{},
+			ProxyEnv:             map[string]string{"http_proxy": "http://proxy:3128", "no_proxy": "internal.example"},
+			Secrets:              map[string]string{},
+		},
+		Env: map[string]string{},
+		Run: &model.Run{
+			JobID:    "job",
+			Workflow: workflow,
+		},
+	}
+	rc.ExprEval = rc.NewExpressionEvaluator(t.Context())
+
+	require.NoError(t, rc.startJobContainer()(t.Context()))
+
+	env := map[string][]string{}
+	for _, in := range inputs {
+		env[in.Image] = in.Env
+	}
+
+	require.Contains(t, env["redis:latest"], "http_proxy=http://proxy:3128")
+	require.Contains(t, env["redis:latest"], "no_proxy=internal.example")
+	// the service's own env wins over what the runner injected, without dropping the rest
+	require.Contains(t, env["postgres:latest"], "no_proxy=db-only.example")
+	require.NotContains(t, env["postgres:latest"], "no_proxy=internal.example")
+	require.Contains(t, env["postgres:latest"], "http_proxy=http://proxy:3128")
+}
+
+// act builds Dockerfile actions through the API, which does not pre-populate the proxy
+// build args the docker CLI would, so the RUN steps would have no network behind a proxy.
+func TestProxyBuildArgs(t *testing.T) {
+	rc := &RunContext{Config: &Config{ProxyEnv: map[string]string{"http_proxy": "http://proxy:3128"}}}
+
+	args := rc.proxyBuildArgs()
+
+	require.Len(t, args, 1)
+	require.Equal(t, "http://proxy:3128", *args["http_proxy"])
+
+	// a job without a proxy builds exactly as it does today
+	require.Nil(t, (&RunContext{Config: &Config{}}).proxyBuildArgs())
+}
+
 func TestRunContext_GetBindsAndMounts(t *testing.T) {
 	rctemplate := &RunContext{
 		Name: "TestRCName",
@@ -363,6 +441,10 @@ func TestRunContext_GetBindsAndMounts(t *testing.T) {
 			{"BindAnonymousVolume", []string{"/volume"}, "/volume", map[string]string{}},
 			{"BindHostFile", []string{"/path/to/file/on/host:/volume"}, "/path/to/file/on/host:/volume", map[string]string{}},
 			{"MountExistingVolume", []string{"volume-id:/volume"}, "", map[string]string{"volume-id": "/volume"}},
+			{"MountExistingVolumeReadOnly", []string{"volume-id:/volume:ro"}, "volume-id:/volume:ro", map[string]string{}},
+			{"BindRelativeHostPath", []string{"./relative:/volume"}, "./relative:/volume", map[string]string{}},
+			{"OverridesToolCache", []string{"/host/tools:/opt/hostedtoolcache"}, "/host/tools:/opt/hostedtoolcache", map[string]string{}},
+			{"OverridesDockerSocket", []string{"/host/docker.sock:/var/run/docker.sock"}, "/host/docker.sock:/var/run/docker.sock", map[string]string{}},
 		}
 
 		t.Run("InterpolatedContainerVolumes", func(t *testing.T) {
@@ -418,15 +500,37 @@ func TestRunContext_GetBindsAndMounts(t *testing.T) {
 				rc.Run.JobID = "job1"
 				rc.Run.Workflow.Jobs = map[string]*model.Job{"job1": job}
 
-				gotbind, gotmount := rc.GetBindsAndMounts()
+				jobBinds, jobMounts := rc.GetBindsAndMounts()
+				svcBinds, svcMounts := rc.GetServiceBindsAndMounts(testcase.volumes)
+				// job and service containers classify volumes alike, only their own mounts differ
+				for _, got := range []struct {
+					binds  []string
+					mounts map[string]string
+				}{{jobBinds, jobMounts}, {svcBinds, svcMounts}} {
+					gotbind, gotmount := got.binds, got.mounts
 
-				if len(testcase.wantbind) > 0 {
-					assert.Contains(t, gotbind, testcase.wantbind)
-				}
+					if len(testcase.wantbind) > 0 {
+						assert.Contains(t, gotbind, testcase.wantbind)
+					}
 
-				for k, v := range testcase.wantmount {
-					assert.Contains(t, gotmount, k)
-					assert.Equal(t, gotmount[k], v)
+					for k, v := range testcase.wantmount {
+						assert.Contains(t, gotmount, k)
+						assert.Equal(t, gotmount[k], v)
+					}
+
+					// Docker rejects a container with two mounts on one target, so the job's own
+					// volumes must displace the runner's rather than pile up next to them.
+					targets := map[string]bool{}
+					for _, bind := range gotbind {
+						parsed, err := loader.ParseVolume(bind)
+						require.NoError(t, err)
+						assert.NotContains(t, targets, parsed.Target, "%s mounts an already mounted target", bind)
+						targets[parsed.Target] = true
+					}
+					for source, target := range gotmount {
+						assert.NotContains(t, targets, target, "%s mounts an already mounted target", source)
+						targets[target] = true
+					}
 				}
 			})
 		}

act/runner/runner.go

@@ -73,6 +73,7 @@ type Config struct {
 	ContainerNetworkMode               docker_container.NetworkMode                  // the network mode of job containers (the value of --network)
 	ContainerNetworkCreateOptions      container.NewDockerNetworkCreateExecutorInput // the default network create options
 	ActionCache                        ActionCache                                   // Use a custom ActionCache Implementation
+	ProxyEnv                           map[string]string                             // the proxy variables the job runs with, also given to service containers and image builds
 
 	PresetGitHubContext   *model.GithubContext // the preset github context, overrides some fields like DefaultBranch, Env, Secrets etc.
 	EventJSON             string               // the content of JSON file to use for event.json in containers, overrides EventPath
@@ -93,6 +94,8 @@ type Config struct {
 	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
 	RunnerName                        string                       // name this runner registered with, reported as `runner.name`, defaults to the hostname
+	JobStartedHook                    string                       // script run inside the job environment before the job's first step; ACTIONS_RUNNER_HOOK_JOB_STARTED is read from Env when empty
+	JobCompletedHook                  string                       // script run inside the job environment after the job's last step; ACTIONS_RUNNER_HOOK_JOB_COMPLETED is read from Env when empty
 }
 
 // RunnerDebug reports whether debug logging is on, exposed as `runner.debug` and

act/runner/runner_max_parallel_test.go

@@ -1,109 +0,0 @@
-// Copyright 2026 The Gitea Authors. All rights reserved.
-// SPDX-License-Identifier: MIT
-
-package runner
-
-import (
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-)
-
-// TestMaxParallelConfig tests that MaxParallel config is properly set
-func TestMaxParallelConfig(t *testing.T) {
-	t.Run("MaxParallel set to 2", func(t *testing.T) {
-		config := &Config{
-			Workdir:     "testdata",
-			MaxParallel: 2,
-		}
-
-		runner, err := New(config)
-		assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-		assert.NotNil(t, runner)
-
-		// Verify config is properly stored
-		runnerImpl, ok := runner.(*runnerImpl)
-		assert.True(t, ok)
-		assert.Equal(t, 2, runnerImpl.config.MaxParallel)
-	})
-
-	t.Run("MaxParallel set to 0 (no limit)", func(t *testing.T) {
-		config := &Config{
-			Workdir:     "testdata",
-			MaxParallel: 0,
-		}
-
-		runner, err := New(config)
-		assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-		assert.NotNil(t, runner)
-
-		runnerImpl, ok := runner.(*runnerImpl)
-		assert.True(t, ok)
-		assert.Equal(t, 0, runnerImpl.config.MaxParallel)
-	})
-
-	t.Run("MaxParallel not set (defaults to 0)", func(t *testing.T) {
-		config := &Config{
-			Workdir: "testdata",
-		}
-
-		runner, err := New(config)
-		assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-		assert.NotNil(t, runner)
-
-		runnerImpl, ok := runner.(*runnerImpl)
-		assert.True(t, ok)
-		assert.Equal(t, 0, runnerImpl.config.MaxParallel)
-	})
-}
-
-// TestMaxParallelConcurrencyTracking tests that max-parallel actually limits concurrent execution
-func TestMaxParallelConcurrencyTracking(t *testing.T) {
-	// This is a unit test for the parallel executor logic
-	// We test that when MaxParallel is set, it limits the number of workers
-
-	var mu sync.Mutex
-	var maxConcurrent int
-	var currentConcurrent int
-
-	// Create a function that tracks concurrent execution
-	trackingFunc := func() {
-		mu.Lock()
-		currentConcurrent++
-		if currentConcurrent > maxConcurrent {
-			maxConcurrent = currentConcurrent
-		}
-		mu.Unlock()
-
-		// Simulate work
-		time.Sleep(50 * time.Millisecond)
-
-		mu.Lock()
-		currentConcurrent--
-		mu.Unlock()
-	}
-
-	// Run multiple tasks with limited parallelism
-	maxConcurrent = 0
-	currentConcurrent = 0
-
-	// This simulates what NewParallelExecutor does with a semaphore
-	var wg sync.WaitGroup
-	semaphore := make(chan struct{}, 2) // Limit to 2 concurrent
-
-	for range 6 {
-		wg.Go(func() {
-			semaphore <- struct{}{}        // Acquire
-			defer func() { <-semaphore }() // Release
-			trackingFunc()
-		})
-	}
-
-	wg.Wait()
-
-	// With a semaphore of 2, max concurrent should be <= 2
-	assert.LessOrEqual(t, maxConcurrent, 2, "Maximum concurrent executions should not exceed limit")
-	assert.GreaterOrEqual(t, maxConcurrent, 1, "Should have at least 1 concurrent execution")
-}

act/runner/runner_test.go

@@ -13,6 +13,7 @@ import (
 	"path"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strings"
 	"testing"
 	"time"
@@ -163,6 +164,12 @@ func TestGraphEvent(t *testing.T) {
 	assert.Empty(t, plan.Stages)
 }
 
+// these two build the same action Dockerfiles into one image tag, so they cannot overlap
+var sharedImageWorkflows = []string{"local-action-dockerfile", "local-action-via-composite-dockerfile"}
+
+// bounds concurrent plans: each job holds a network, and the daemon's address pool is finite
+var planSlots = make(chan struct{}, 4)
+
 type TestJobFileInfo struct {
 	workdir      string
 	workflowPath string
@@ -182,12 +189,19 @@ func (j *TestJobFileInfo) runTest(ctx context.Context, t *testing.T, cfg *Config
 
 	fullWorkflowPath := filepath.Join(workdir, j.workflowPath)
 	runnerConfig := &Config{
-		Workdir:               workdir,
-		BindWorkdir:           false,
-		EventName:             j.eventName,
-		EventPath:             cfg.EventPath,
-		Platforms:             j.platforms,
-		ReuseContainers:       false,
+		Workdir:     workdir,
+		BindWorkdir: false,
+		EventName:   j.eventName,
+		EventPath:   cfg.EventPath,
+		Platforms:   j.platforms,
+		// fixtures reuse workflow and job names, so parallel tests would collide without this
+		ContainerNamePrefix: strings.ReplaceAll(t.Name(), "/", "-"),
+		ReuseContainers:     false,
+		// as the shipped runner does, else a fixture asserting a job failure keeps its
+		// container, and its network, on the daemon forever
+		AutoRemove: true,
+		// 0 would run jobs runtime.NumCPU()-wide, making the network peak machine-dependent
+		MaxParallel:           2,
 		ForceRebuild:          true,
 		Env:                   cfg.Env,
 		Secrets:               cfg.Secrets,
@@ -210,7 +224,11 @@ func (j *TestJobFileInfo) runTest(ctx context.Context, t *testing.T, cfg *Config
 	plan, err := planner.PlanEvent(j.eventName)
 	assert.True(t, (err == nil) != (plan == nil), "PlanEvent should return either a plan or an error") //nolint:testifylint // pre-existing issue from nektos/act
 	if err == nil && plan != nil {
-		err = runner.NewPlanExecutor(plan)(ctx)
+		err = func() error {
+			planSlots <- struct{}{}
+			defer func() { <-planSlots }()
+			return runner.NewPlanExecutor(plan)(ctx)
+		}()
 		if j.errorMessage == "" {
 			assert.NoError(t, err, fullWorkflowPath) //nolint:testifylint // pre-existing issue from nektos/act
 		} else {
@@ -227,6 +245,7 @@ type TestConfig struct {
 
 func TestRunEvent(t *testing.T) {
 	requireDocker(t)
+	t.Parallel()
 
 	ctx := context.Background()
 
@@ -315,6 +334,9 @@ func TestRunEvent(t *testing.T) {
 				// host /proc bind mounts are Linux-Docker-only
 				requireLinuxDocker(t)
 			}
+			if !slices.Contains(sharedImageWorkflows, table.workflowPath) {
+				t.Parallel()
+			}
 
 			config := &Config{
 				Secrets: table.secrets,
@@ -445,6 +467,7 @@ func TestRunEventHostEnvironment(t *testing.T) {
 }
 
 func TestDryrunEvent(t *testing.T) {
+	t.Parallel()
 	// Dryrun plans without containers or network (shells and local actions only).
 	ctx := common.WithDryrun(context.Background(), true)
 
@@ -464,6 +487,7 @@ func TestDryrunEvent(t *testing.T) {
 
 	for _, table := range tables {
 		t.Run(table.workflowPath, func(t *testing.T) {
+			t.Parallel()
 			table.runTest(ctx, t, &Config{})
 		})
 	}
@@ -474,33 +498,11 @@ func TestDryrunEvent(t *testing.T) {
 // workflow's outputs via `needs`).
 func TestReusableWorkflowCaller(t *testing.T) {
 	requireDocker(t)
+	t.Parallel()
 	table := TestJobFileInfo{workdir, "uses-workflow", "push", "", platforms, map[string]string{"secret": "keep_it_private"}}
 	table.runTest(context.Background(), t, &Config{Secrets: table.secrets})
 }
 
-func TestDockerActionForcePullForceRebuild(t *testing.T) {
-	requireDocker(t)
-	requireNetwork(t) // force-pulls a docker action image
-
-	ctx := context.Background()
-
-	config := &Config{
-		ForcePull:    true,
-		ForceRebuild: true,
-	}
-
-	tables := []TestJobFileInfo{
-		{workdir, "local-action-dockerfile", "push", "", platforms, secrets},
-		{workdir, "local-action-via-composite-dockerfile", "push", "", platforms, secrets},
-	}
-
-	for _, table := range tables {
-		t.Run(table.workflowPath, func(t *testing.T) {
-			table.runTest(ctx, t, config)
-		})
-	}
-}
-
 type maskJobLoggerFactory struct {
 	Output bytes.Buffer
 }
@@ -513,6 +515,7 @@ func (f *maskJobLoggerFactory) WithJobLogger() *log.Logger {
 }
 
 func TestMaskValues(t *testing.T) {
+	t.Parallel()
 	assertNoSecret := func(text, secret string) { //nolint:unparam // pre-existing issue from nektos/act
 		found := strings.Contains(text, "composite secret")
 		if found {
@@ -543,6 +546,7 @@ func TestMaskValues(t *testing.T) {
 
 func TestRunEventSecrets(t *testing.T) {
 	requireDocker(t)
+	t.Parallel()
 	workflowPath := "secrets"
 
 	tjfi := TestJobFileInfo{
@@ -598,6 +602,7 @@ func TestRunWithService(t *testing.T) {
 }
 
 func TestRunActionInputs(t *testing.T) {
+	t.Parallel()
 	requireDocker(t)
 	workflowPath := "input-from-cli"
 
@@ -617,6 +622,7 @@ func TestRunActionInputs(t *testing.T) {
 }
 
 func TestRunEventPullRequest(t *testing.T) {
+	t.Parallel()
 	requireDocker(t)
 
 	workflowPath := "pull-request"
@@ -633,6 +639,7 @@ func TestRunEventPullRequest(t *testing.T) {
 }
 
 func TestRunMatrixWithUserDefinedInclusions(t *testing.T) {
+	t.Parallel()
 	requireDocker(t)
 	workflowPath := "matrix-with-user-inclusions"
 

act/runner/step_action_remote.go

@@ -69,6 +69,8 @@ func (sar *stepActionRemote) prepareActionExecutor() common.Executor {
 				github.Token = sar.RunContext.Config.ReplaceGheActionTokenWithGithubCom
 			}
 		}
+		// Actions served from the action cache are read out of a git object store rather than a
+		// directory, so they never reach the bundle patch below and keep to the v1 cache API.
 		if sar.RunContext.Config.ActionCache != nil {
 			cache := sar.RunContext.Config.ActionCache
 
@@ -112,7 +114,7 @@ func (sar *stepActionRemote) prepareActionExecutor() common.Executor {
 			return err
 		}
 
-		actionDir := fmt.Sprintf("%s/%s", sar.RunContext.ActionCacheDir(), sar.Step.UsesHash())
+		actionDir := sar.actionDir()
 		defaultActionURL := sar.RunContext.Config.DefaultActionURL()
 		// For Gitea
 		// A composite RunContext nils Config.Secrets, so getGitCloneToken would yield an
@@ -138,9 +140,10 @@ func (sar *stepActionRemote) prepareActionExecutor() common.Executor {
 		})
 		var ntErr common.Executor
 		if err := gitClone(ctx); err != nil {
-			if errors.Is(err, git.ErrShortRef) {
+			var refErr *git.Error
+			if errors.As(err, &refErr) && errors.Is(err, git.ErrShortRef) {
 				return fmt.Errorf("Unable to resolve action `%s`, the provided ref `%s` is the shortened version of a commit SHA, which is not supported. Please use the full commit SHA `%s` instead",
-					sar.Step.Uses, sar.remoteAction.Ref, err.(*git.Error).Commit())
+					sar.Step.Uses, sar.remoteAction.Ref, refErr.Commit())
 			} else if errors.Is(err, gogit.ErrForceNeeded) { // TODO: figure out if it will be easy to shadow/alias go-git err's
 				ntErr = common.NewInfoExecutor("Non-terminating error while running 'git clone': %v", err)
 			} else {
@@ -170,6 +173,9 @@ func (sar *stepActionRemote) prepareActionExecutor() common.Executor {
 				sar.action = actionModel
 				return err
 			},
+			// A stage of its own: it takes the same clone lock, and it has to land before
+			// runAction copies the action into the job container.
+			sar.patchActionToolkit,
 		)(ctx)
 	}
 }
@@ -188,7 +194,7 @@ func (sar *stepActionRemote) pre() common.Executor {
 
 	return common.NewPipelineExecutor(
 		sar.prepareActionExecutor(),
-		runStepExecutor(sar, stepStagePre, runPreStep(sar)).If(hasPreStep(sar)).If(shouldRunPreStep(sar)))
+		runStepExecutor(sar, stepStagePre, sar.revertToolkitOnFailure(runPreStep(sar))).If(hasPreStep(sar)).If(shouldRunPreStep(sar)))
 }
 
 func (sar *stepActionRemote) main() common.Executor {
@@ -210,15 +216,51 @@ func (sar *stepActionRemote) main() common.Executor {
 				return sar.RunContext.JobContainer.CopyDir(copyToPath, sar.RunContext.Config.Workdir+string(filepath.Separator)+".", sar.RunContext.Config.UseGitIgnore)(ctx)
 			}
 
-			actionDir := fmt.Sprintf("%s/%s", sar.RunContext.ActionCacheDir(), sar.Step.UsesHash())
+			actionDir := sar.actionDir()
 
-			return sar.runAction(sar, actionDir, sar.remoteAction)(ctx)
+			return sar.revertToolkitOnFailure(sar.runAction(sar, actionDir, sar.remoteAction))(ctx)
 		}),
 	)
 }
 
 func (sar *stepActionRemote) post() common.Executor {
-	return runStepExecutor(sar, stepStagePost, runPostStep(sar)).If(hasPostStep(sar)).If(shouldRunPostStep(sar))
+	return runStepExecutor(sar, stepStagePost, sar.revertToolkitOnFailure(runPostStep(sar))).If(hasPostStep(sar)).If(shouldRunPostStep(sar))
+}
+
+// toolkitBundles is the action directory and the entrypoints the toolkit may live in.
+func (sar *stepActionRemote) toolkitBundles() (string, []string) {
+	if sar.remoteAction == nil {
+		return "", nil
+	}
+	dir := sar.actionDir()
+	return dir, actionScriptPaths(filepath.Join(dir, sar.remoteAction.Path), sar.action)
+}
+
+// patchActionToolkit edits the bundled toolkit so it works against Gitea, which lets the cache
+// client use the v2 API this runner serves. A no-op unless the runner serves it.
+func (sar *stepActionRemote) patchActionToolkit(ctx context.Context) error {
+	if sar.RunContext.GetEnv()[CacheServiceV2Env] != "" {
+		dir, scripts := sar.toolkitBundles()
+		patchToolkit(ctx, dir, scripts)
+	}
+	return nil
+}
+
+// revertToolkitOnFailure restores the untouched bundles when the action fails, so a later job
+// runs it as shipped rather than repeating a failure the patch may have caused.
+func (sar *stepActionRemote) revertToolkitOnFailure(exec common.Executor) common.Executor {
+	return func(ctx context.Context) error {
+		err := exec(ctx)
+		if err != nil {
+			dir, scripts := sar.toolkitBundles()
+			revertToolkit(ctx, dir, scripts)
+		}
+		return err
+	}
+}
+
+func (sar *stepActionRemote) actionDir() string {
+	return fmt.Sprintf("%s/%s", sar.RunContext.ActionCacheDir(), sar.Step.UsesHash())
 }
 
 func (sar *stepActionRemote) getRunContext() *RunContext {
@@ -269,7 +311,7 @@ func (sar *stepActionRemote) getActionModel() *model.Action {
 
 func (sar *stepActionRemote) getCompositeRunContext(ctx context.Context) *RunContext {
 	if sar.compositeRunContext == nil {
-		actionDir := fmt.Sprintf("%s/%s", sar.RunContext.ActionCacheDir(), sar.Step.UsesHash())
+		actionDir := sar.actionDir()
 		actionLocation := path.Join(actionDir, sar.remoteAction.Path)
 		_, containerActionDir := getContainerActionPaths(sar.getStepModel(), actionLocation, sar.RunContext)
 

act/runner/step_docker.go

@@ -110,10 +110,7 @@ func (sd *stepDocker) newStepContainer(ctx context.Context, image string, cmd, e
 		envList = append(envList, fmt.Sprintf("%s=%s", k, v))
 	}
 
-	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_TOOL_CACHE", "/opt/hostedtoolcache"))
-	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_OS", "Linux"))
-	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_ARCH", container.RunnerArch(ctx)))
-	envList = append(envList, fmt.Sprintf("%s=%s", "RUNNER_TEMP", "/tmp"))
+	envList = append(envList, rc.runnerEnv(ctx)...)
 
 	binds, mounts := rc.GetBindsAndMounts()
 	networkMode := "container:" + rc.jobContainerName()

act/runner/toolkit_patch.go

@@ -0,0 +1,262 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package runner
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/common/git"
+	"gitea.com/gitea/runner/act/model"
+)
+
+// Actions bundle the @actions toolkit into their own JavaScript, and two of its lines keep it
+// from working against Gitea. Both are edited out of the bundle the runner downloaded.
+//
+// isGhes() takes any host that is not github.com, *.ghe.com or *.localhost for GitHub
+// Enterprise. @actions/cache then forces the v1 API, and @actions/artifact refuses outright,
+// which is why the stock upload-artifact aborts here. The edit empties the last of the three
+// hostname tests, so `endsWith('.LOCALHOST')` becomes `endsWith(”)`, which every hostname
+// satisfies: one string literal, no call sites to resolve, and the same answer the toolkit's own
+// proposed ACTIONS_VENDOR switch would give. Gitea already makes this edit by hand in its fork
+// of upload-artifact.
+//
+// getCacheServiceURL() then resolves the cache service from ACTIONS_RESULTS_URL alone, where v1
+// reads ACTIONS_CACHE_URL first. Both reads there are given the same preference, which is what
+// keeps the runner out of the artifact path: the results URL still points at Gitea.
+//
+// Either of these landing upstream makes this file deletable:
+//
+//	https://github.com/actions/toolkit/pull/2123   — an ACTIONS_VENDOR switch, naming Gitea
+//	https://github.com/actions/toolkit/issues/2439 — treat ACTIONS_RESULTS_URL as the signal
+const (
+	CacheServiceV2Env = "ACTIONS_CACHE_SERVICE_V2"
+	cacheURLEnv       = "ACTIONS_CACHE_URL"
+	resultsURLEnv     = "ACTIONS_RESULTS_URL"
+
+	// localhostHost is the suffix isGhes accepts; emptying the test is what opens the gate,
+	// because every hostname ends with the empty string.
+	localhostHost = ".LOCALHOST"
+
+	// artifactRefusal is the only thing the gate guards in @actions/artifact, which is what makes
+	// such a bundle safe to open. A bundle carrying neither toolkit uses isGhes for something this
+	// runner has not looked at, and is left alone.
+	artifactRefusal = "GHESNotSupportedError"
+
+	// sidecarSuffix names the directory of untouched copies, a sibling of the action directory
+	// because that directory is copied wholesale into job containers.
+	sidecarSuffix = ".toolkit-patch"
+
+	// skipMarker in the sidecar means a patched bundle already failed once here.
+	skipMarker = "skip"
+
+	maxBundleSize = 64 << 20
+)
+
+var (
+	// localhostTest matches the third hostname test of isGhes, in any quoting. The match is case
+	// sensitive on purpose, and that is load-bearing: isGhes uppercases the hostname before
+	// testing it, while undici, bundled into all of these actions, tests a lowercase ".localhost"
+	// in isURLPotentiallyTrustworthy. Opening that one would tell its HTTP client that every URL
+	// is trustworthy. Uppercase, the literal occurs nowhere but this test, across 118 bundles
+	// covering every major version of sixteen actions.
+	localhostTest = regexp.MustCompile(`endsWith\s*\(\s*` + quoted(regexp.QuoteMeta(localhostHost)) + `\s*\)`)
+
+	// serviceURLBranches matches both branches of getCacheServiceURL at once: the v1 branch reads
+	// the cache URL and falls back to the results URL, the v2 branch just below reads the results
+	// URL alone. That `||` pairing is the only place the two variables are read together, so
+	// matching them as one expression is what keeps the edit inside this function rather than
+	// anywhere they happen to sit near each other. The branches are 21 bytes apart minified and
+	// 63 not, across every bundle measured.
+	serviceURLBranches = regexp.MustCompile(`(` + envRead(cacheURLEnv) + `\s*\|\|\s*)(` +
+		envRead(resultsURLEnv) + `)((?s).{0,256}?)(` + envRead(resultsURLEnv) + `)`)
+
+	// cacheURLFirst gives both reads the preference the v1 branch already had.
+	cacheURLFirst = []byte(`${1}(process.env.` + cacheURLEnv + `||${2})${3}(process.env.` + cacheURLEnv + `||${4})`)
+)
+
+func envRead(name string) string {
+	return `process\s*\.\s*env\s*(?:\.\s*` + name + `\b|\[\s*` + quoted(name) + `\s*\])`
+}
+
+// quoted matches a string literal in any of the three quote characters. RE2 has no
+// backreferences, so the pairs are spelled out.
+func quoted(pattern string) string {
+	return "(?:'" + pattern + "'|\"" + pattern + "\"|`" + pattern + "`)"
+}
+
+// actionScriptPaths returns the entrypoints of a node action, the only kind with a bundle. Only
+// remote actions get here: a local one lives in the user's checkout, which the runner does not
+// rewrite.
+func actionScriptPaths(dir string, action *model.Action) []string {
+	if action == nil || !action.Runs.Using.IsNode() {
+		return nil
+	}
+	var paths []string
+	for _, script := range []string{action.Runs.Pre, action.Runs.Main, action.Runs.Post} {
+		if script != "" {
+			paths = append(paths, filepath.Join(dir, script))
+		}
+	}
+	return paths
+}
+
+// patchToolkit edits the toolkit in an action's bundles, keeping each original beside them. Every
+// failure is silent and leaves the bundle as it was, which costs the cache client the v2 API and
+// an artifact action nothing at all.
+func patchToolkit(ctx context.Context, actionDir string, scripts []string) {
+	if len(scripts) == 0 {
+		return
+	}
+	if _, err := os.Stat(filepath.Join(sidecarDir(actionDir), skipMarker)); err == nil {
+		return
+	}
+	defer git.AcquireCloneLock(actionDir)()
+
+	for _, script := range scripts {
+		if err := patchBundle(script, originalFor(actionDir, script)); err != nil {
+			common.Logger(ctx).Debugf("actions toolkit: %s left unpatched: %v", filepath.Base(script), err)
+		}
+	}
+}
+
+// revertToolkit puts the originals back and stops this action being patched again, so the next job
+// runs it exactly as shipped. Called when a step failed with a patched bundle; it does not re-run
+// the step, because a step's outputs and env-file writes are already recorded by then.
+func revertToolkit(ctx context.Context, actionDir string, scripts []string) {
+	if len(scripts) == 0 {
+		return
+	}
+	if _, err := os.Stat(sidecarDir(actionDir)); err != nil {
+		return
+	}
+	defer git.AcquireCloneLock(actionDir)()
+
+	reverted := false
+	for _, script := range scripts {
+		original := originalFor(actionDir, script)
+		if !isPatchOf(original, script) {
+			continue
+		}
+		if err := os.Rename(original, script); err == nil {
+			reverted = true
+		}
+	}
+	if reverted {
+		_ = os.WriteFile(filepath.Join(sidecarDir(actionDir), skipMarker), nil, 0o600)
+		common.Logger(ctx).Warnf("actions toolkit: restored the original %s, it will not be patched again", filepath.Base(actionDir))
+	}
+}
+
+// sidecarDir holds an action's untouched bundles, and the marker that stops it being patched.
+func sidecarDir(actionDir string) string {
+	return actionDir + sidecarSuffix
+}
+
+// originalFor is where a script's untouched copy lives, or "" for a script the action's own
+// `runs` keys placed outside its directory, which is not this runner's to rewrite.
+func originalFor(actionDir, script string) string {
+	rel, err := filepath.Rel(actionDir, script)
+	if err != nil || strings.HasPrefix(rel, "..") {
+		return ""
+	}
+	return filepath.Join(sidecarDir(actionDir), rel)
+}
+
+// patchBundle rewrites one entrypoint in place. The untouched copy kept beside it is what marks
+// the bundle as already patched.
+func patchBundle(script, original string) error {
+	if original == "" {
+		return nil
+	}
+	if _, err := os.Stat(original); err == nil {
+		if isPatchOf(original, script) {
+			return nil
+		}
+		// The action's ref moved and git checked the new bundle out over the patched one, so
+		// the pair no longer belongs together. Patch afresh rather than keep an original that
+		// would restore an older version of the action.
+		if err := os.Remove(original); err != nil {
+			return err
+		}
+	}
+	info, err := os.Stat(script)
+	if err != nil {
+		return err
+	}
+	if info.Size() > maxBundleSize {
+		return nil
+	}
+	data, err := os.ReadFile(script)
+	if err != nil {
+		return err
+	}
+	patched, ok := patchedBundle(data)
+	if !ok {
+		return nil
+	}
+	if err := os.MkdirAll(filepath.Dir(original), 0o755); err != nil {
+		return err
+	}
+	// The copy is taken before the bundle is replaced, so a write that fails part way can put the
+	// action back as it was. A crash needs no handling: the clone executor checks the action out
+	// and hard resets it on every prepare, so a half-written bundle never outlives the job.
+	if err := os.WriteFile(original, data, info.Mode().Perm()); err != nil {
+		return err
+	}
+	if err := os.WriteFile(script, patched, info.Mode().Perm()); err != nil {
+		_ = os.Rename(original, script)
+		return err
+	}
+	return nil
+}
+
+// isPatchOf reports whether script is exactly what patching original produced. It is what proves
+// the two still belong together: an action whose ref moved is checked out over the patched bundle,
+// leaving an original that would restore the version before the move.
+func isPatchOf(original, script string) bool {
+	data, err := os.ReadFile(original)
+	if err != nil {
+		return false
+	}
+	current, err := os.ReadFile(script)
+	if err != nil {
+		return false
+	}
+	patched, ok := patchedBundle(data)
+	return ok && bytes.Equal(patched, current)
+}
+
+// patchedBundle opens the GHES gate, and where the cache toolkit is present, points the cache
+// service at the cache server. A bundle this runner cannot account for comes back untouched.
+func patchedBundle(data []byte) ([]byte, bool) {
+	if !localhostTest.Match(data) {
+		return data, false
+	}
+	switch {
+	case bytes.Contains(data, []byte(CacheServiceV2Env)):
+		// The cache toolkit: both edits or neither, because choosing v2 without redirecting the
+		// URL would send the client to a results URL that serves no cache service.
+		if !serviceURLBranches.Match(data) {
+			return data, false
+		}
+	case bytes.Contains(data, []byte(artifactRefusal)):
+		// The artifact toolkit, where the gate is a plain refusal and there is no URL to move:
+		// artifacts already go to Gitea, which implements that service.
+	default:
+		return data, false
+	}
+
+	opened := localhostTest.ReplaceAllFunc(data, func(test []byte) []byte {
+		// Drop the hostname from the test rather than rewriting the call, so the bundle's own
+		// quoting survives and the result stays valid even inside a string literal.
+		return bytes.Replace(test, []byte(localhostHost), nil, 1)
+	})
+	return serviceURLBranches.ReplaceAll(opened, cacheURLFirst), true
+}

act/runner/toolkit_patch_e2e_test.go

@@ -0,0 +1,196 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package runner
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.com/gitea/runner/act/artifactcache"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// actionsCacheRef pins the actions/cache release this is verified against. Bump it
+// deliberately: a new release is exactly what can stop the patch matching.
+const actionsCacheRef = "v6.1.0"
+
+// bundleFromGitHub downloads one entrypoint, keeping it in the user cache dir so repeated runs
+// cost nothing. The bundles are megabytes, too large to vendor.
+func bundleFromGitHub(t *testing.T, repo, ref, path string) string {
+	t.Helper()
+
+	cacheDir, err := os.UserCacheDir()
+	require.NoError(t, err)
+	dir := filepath.Join(cacheDir, "gitea-runner-test", strings.ReplaceAll(repo, "/", "-")+"-"+ref)
+	bundle := filepath.Join(dir, strings.ReplaceAll(path, "/", "-"))
+	if _, err := os.Stat(bundle); err == nil {
+		return bundle
+	}
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+
+	url := "https://raw.githubusercontent.com/" + repo + "/" + ref + "/" + path
+	ctx, cancel := context.WithTimeout(t.Context(), time.Minute)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	require.NoError(t, err)
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Skipf("cannot reach %s: %v", url, err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Skipf("GET %s: %s", url, resp.Status)
+	}
+	file, err := os.Create(bundle)
+	require.NoError(t, err)
+	_, err = io.Copy(file, resp.Body)
+	require.NoError(t, file.Close())
+	require.NoError(t, err)
+	return bundle
+}
+
+// runCacheAction runs one entrypoint the way a job would: a real Gitea server URL, and a results
+// URL that points at Gitea rather than at the runner. Nothing about the environment is rewritten,
+// so only the patch can make the client choose v2 and find the cache server.
+func runCacheAction(t *testing.T, script, workspace, runnerTemp, cacheURL, token, key string) string {
+	t.Helper()
+	state := filepath.Join(runnerTemp, "state")
+	output := filepath.Join(runnerTemp, "output")
+	for _, name := range []string{state, output} {
+		require.NoError(t, os.WriteFile(name, nil, 0o600))
+	}
+
+	cmd := exec.CommandContext(t.Context(), "node", script)
+	cmd.Dir = workspace
+	cmd.Env = append(os.Environ(),
+		"INPUT_PATH=to-cache",
+		"INPUT_KEY="+key,
+		"ACTIONS_RUNTIME_TOKEN="+token,
+		"ACTIONS_CACHE_URL="+cacheURL+"/",
+		// Unreachable on purpose: the artifact service lives here, the cache service must not.
+		"ACTIONS_RESULTS_URL=https://gitea.example",
+		"ACTIONS_CACHE_SERVICE_V2=true",
+		"GITHUB_SERVER_URL=https://gitea.example.com",
+		"GITHUB_REF=refs/heads/main",
+		"GITHUB_EVENT_NAME=push",
+		"GITHUB_WORKSPACE="+workspace,
+		"RUNNER_TEMP="+runnerTemp,
+		"GITHUB_STATE="+state,
+		"GITHUB_OUTPUT="+output,
+	)
+	out, err := cmd.CombinedOutput()
+	t.Logf("%s:\n%s", filepath.Base(filepath.Dir(script)), out)
+	require.NoError(t, err, "%s failed", script)
+	return string(out)
+}
+
+// tempDirPath is TempDir with symlinks resolved, because macOS hands out /var paths that resolve
+// to /private/var and the client derives archive paths relative to the workspace.
+func tempDirPath(t *testing.T) string {
+	t.Helper()
+
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	require.NoError(t, err)
+	return dir
+}
+
+// The whole chain against the pinned release, whose bundles ship unminified: patch them, run the
+// real client with an ordinary Gitea server URL and a results URL that goes nowhere, and have it
+// save and restore through this runner's cache server. The unreachable results URL is the point,
+// it is what proves the cache reaches the runner without the runner fronting Gitea. If a release
+// stops matching the patch the client falls back to v1 and this fails on the version line, which
+// is the signal to look at the new bundle.
+func TestCacheServiceV2EndToEnd(t *testing.T) {
+	requireHostTools(t, "node")
+
+	// A stand-in action directory, patched exactly as a downloaded one would be.
+	actionDir := tempDirPath(t)
+	scripts := map[string]string{}
+	for _, stage := range []string{"restore", "save"} {
+		body, err := os.ReadFile(bundleFromGitHub(t, "actions/cache", actionsCacheRef, "dist/"+stage+"/index.js"))
+		require.NoError(t, err)
+		scripts[stage] = filepath.Join(actionDir, stage+".js")
+		require.NoError(t, os.WriteFile(scripts[stage], body, 0o600))
+	}
+	patchToolkit(t.Context(), actionDir, []string{scripts["restore"], scripts["save"]})
+
+	handler, err := artifactcache.StartHandler(filepath.Join(t.TempDir(), "cache"), "127.0.0.1", 0, "", nil)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = handler.Close() })
+	const token, repo = "e2e-runtime-token", "testuser/testrepo"
+	handler.RegisterJob(token, repo)
+
+	workspace, runnerTemp := tempDirPath(t), tempDirPath(t)
+	require.NoError(t, os.MkdirAll(filepath.Join(workspace, "to-cache"), 0o755))
+	content := []byte("cached through the patched gate")
+	require.NoError(t, os.WriteFile(filepath.Join(workspace, "to-cache", "data.txt"), content, 0o600))
+
+	const key = "patched-gate-key"
+	missed := runCacheAction(t, scripts["restore"], workspace, runnerTemp, handler.ExternalURL(), token, key)
+	require.Contains(t, missed, "Cache service version: v2", "the patch did not take, the client stayed on v1")
+	require.Contains(t, missed, "Cache not found for input keys: "+key)
+
+	saved := runCacheAction(t, scripts["save"], workspace, runnerTemp, handler.ExternalURL(), token, key)
+	require.Contains(t, saved, "Cache saved with key: "+key)
+
+	restored := tempDirPath(t)
+	hit := runCacheAction(t, scripts["restore"], restored, runnerTemp, handler.ExternalURL(), token, key)
+	require.Contains(t, hit, "Cache restored from key: "+key)
+
+	got, err := os.ReadFile(filepath.Join(restored, "to-cache", "data.txt"))
+	require.NoError(t, err)
+	assert.Equal(t, content, got)
+}
+
+// The gate and the URL getter are separate functions, and a bundler may put either first: the gap
+// between them runs from 159 to 1179 bytes across these actions, which is why neither edit is
+// anchored on that distance. One entrypoint from each of the families that bundle the cache
+// toolkit, patched but not run, is what keeps a future release from quietly matching only one of
+// the two shapes and leaving every cache on v1.
+func TestToolkitPatchAcrossActions(t *testing.T) {
+	for _, tc := range []struct{ repo, ref, path string }{
+		{"actions/setup-go", "v7.0.0", "dist/setup/index.js"},
+		{"actions/setup-node", "v6.0.0", "dist/cache-save/index.js"},
+		{"actions/setup-python", "v6.0.0", "dist/setup/index.js"},
+		{"ruby/setup-ruby", "v1.271.0", "dist/index.js"},
+		{"pnpm/action-setup", "v6.0.9", "dist/index.js"},
+		// The artifact toolkit, where the gate is a refusal and there is nothing to redirect.
+		// v4.4.0 is the first release whose gate carries the localhost test this matches; the
+		// releases before it refuse in a shape the runner leaves alone.
+		{"actions/upload-artifact", "v4.4.0", "dist/upload/index.js"},
+		{"actions/upload-artifact", "v7.0.1", "dist/upload/index.js"},
+		{"actions/download-artifact", "v6.0.0", "dist/index.js"},
+		{"oven-sh/setup-bun", "v2.2.0", "dist/setup/index.js"},
+	} {
+		t.Run(tc.repo+"@"+tc.ref, func(t *testing.T) {
+			t.Parallel()
+
+			data, err := os.ReadFile(bundleFromGitHub(t, tc.repo, tc.ref, tc.path))
+			require.NoError(t, err)
+
+			out, patched := patchedBundle(data)
+			assert.True(t, patched, "the version gate was not patched")
+			assert.NotContains(t, string(out), ".LOCALHOST", "a copy of the gate was missed")
+
+			if !strings.Contains(string(data), CacheServiceV2Env) {
+				return // the artifact toolkit: a refusal to open, and no URL to move
+			}
+			// Only the reads inside getCacheServiceURL are rewritten. The others, such as the
+			// feature-availability check, must be left as they are.
+			assert.NotZero(t, strings.Count(string(out), "(process.env."+cacheURLEnv+"||process.env"),
+				"the cache service URL was not redirected")
+			assert.Equal(t, strings.Count(string(data), resultsURLEnv), strings.Count(string(out), resultsURLEnv),
+				"a read of the results URL was lost, it must stay as the fallback")
+		})
+	}
+}

act/runner/toolkit_patch_test.go

@@ -0,0 +1,328 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package runner
+
+import (
+	"context"
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.com/gitea/runner/act/model"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The three shapes real bundlers emit, reduced to the bytes that matter: the version gate, and
+// the URL getter that follows it. tsc keeps the names, webpack prefixes them, esbuild mangles
+// them, writes ternaries in place of the switch, and records the real name in the export
+// assignment. Each carries both reads of the results URL, as the real getter does.
+const (
+	urlTSC     = `function getCacheServiceURL() {` + "\n" + `    switch (getCacheServiceVersion()) {` + "\n" + `        case 'v1':` + "\n" + `            return (process.env['ACTIONS_CACHE_URL'] || process.env['ACTIONS_RESULTS_URL'] || '');` + "\n" + `        case 'v2':` + "\n" + `            return process.env['ACTIONS_RESULTS_URL'] || '';` + "\n" + `    }` + "\n" + `}`
+	urlEsbuild = `function YK(){let e=XK();return e==="v1"?process.env.ACTIONS_CACHE_URL||process.env.ACTIONS_RESULTS_URL||"":e==="v2"?process.env.ACTIONS_RESULTS_URL||"":""}`
+
+	isGhesTSC   = `function isGhes(){const h=new URL(process.env['GITHUB_SERVER_URL']||'https://github.com').hostname.toUpperCase();return h!=='GITHUB.COM'&&!h.endsWith('.GHE.COM')&&!h.endsWith('.LOCALHOST')}`
+	gateTSC     = isGhesTSC + "\n" + `function getCacheServiceVersion() {` + "\n" + `    if (isGhes())` + "\n" + `        return 'v1';` + "\n" + `    return process.env['ACTIONS_CACHE_SERVICE_V2'] ? 'v2' : 'v1';` + "\n" + `}` + "\n" + urlTSC
+	gateWebpack = `function config_isGhes(){const h=new URL(process.env['GITHUB_SERVER_URL']||'https://github.com').hostname.toUpperCase();return h!=='GITHUB.COM'&&!h.endsWith('.GHE.COM')&&!h.endsWith('.LOCALHOST')}` + "\n" + `function config_getCacheServiceVersion() {` + "\n" + `    if (config_isGhes())` + "\n" + `        return 'v1';` + "\n" + `    return process.env['ACTIONS_CACHE_SERVICE_V2'] ? 'v2' : 'v1';` + "\n" + `}` + "\n" + urlTSC
+	gateEsbuild = `vu.isGhes=$K;vu.getCacheServiceVersion=XK;function $K(){let e=new URL(process.env.GITHUB_SERVER_URL||"https://github.com").hostname.toUpperCase(),r=e==="GITHUB.COM",n=e.endsWith(".GHE.COM"),i=e.endsWith(".LOCALHOST");return!r&&!n&&!i}function XK(){return $K()?"v1":process.env.ACTIONS_CACHE_SERVICE_V2?"v2":"v1"}` + urlEsbuild
+)
+
+func TestPatchedBundle(t *testing.T) {
+	for _, tc := range []struct {
+		name, body  string
+		wantPatched bool
+	}{
+		{"tsc keeps the names", gateTSC, true},
+		{"webpack prefixes them", gateWebpack, true},
+		{"esbuild mangles and minifies them", gateEsbuild, true},
+		// A bundler picks its own quoting; gateTSC is single-quoted already.
+		{"double-quoted", requoted(`"`), true},
+		{"backtick-quoted", requoted("`"), true},
+		// sccache-action sets the variable itself; there is no gate to open.
+		{"mentions the variable without the gate", `core.exportVariable("ACTIONS_CACHE_SERVICE_V2","on")`, false},
+		// Both edits or neither: a gate patched without the URL would send the client to a
+		// results URL that serves no cache service.
+		{"gate without a recognisable url getter", strings.TrimSuffix(gateTSC, "\n"+urlTSC), false},
+		// And the other way round: an action that reads both variables but has no gate to open.
+		{"url getter without a gate", urlTSC, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			out, patched := patchedBundle([]byte(tc.body))
+			assert.Equal(t, tc.wantPatched, patched)
+			if !tc.wantPatched {
+				assert.Equal(t, tc.body, string(out), "an unpatched bundle must come back byte for byte")
+				return
+			}
+			assert.True(t, gateOpened(string(out)))
+			// The other two hostname tests are left alone, so a host that really is GitHub or
+			// GHES is still recognised as such.
+			assert.NotContains(t, string(out), ".LOCALHOST", "the localhost test is the one that opens")
+			assert.Contains(t, string(out), ".GHE.COM")
+
+			// Every read of the results URL now prefers the cache URL, and none was lost: the
+			// results URL stays the fallback, so a runner not serving the cache still works.
+			assert.Equal(t, strings.Count(tc.body, "ACTIONS_RESULTS_URL"), strings.Count(string(out), "ACTIONS_RESULTS_URL"))
+			assert.Equal(t, strings.Count(tc.body, "ACTIONS_RESULTS_URL"),
+				strings.Count(string(out), "(process.env.ACTIONS_CACHE_URL||process.env"))
+		})
+	}
+}
+
+// undici, bundled into every one of these actions, decides whether to trust a URL with a
+// lowercase test that reads almost the same. Opening it would tell the HTTP client that every URL
+// is trustworthy, so the uppercase the toolkit produces is what separates them.
+func TestPatchedBundleLeavesTrustworthyURLCheckAlone(t *testing.T) {
+	const undici = `if(n.hostname==="localhost"||n.hostname.includes("localhost.")||n.hostname.endsWith(".localhost")){return true}`
+
+	out, patched := patchedBundle([]byte(undici + gateTSC))
+	require.True(t, patched)
+	assert.Contains(t, string(out), undici, "the trustworthy-URL check must survive byte for byte")
+	assert.True(t, gateOpened(string(out)))
+}
+
+// The artifact toolkit puts the same gate in front of a plain refusal, with no URL to move, so
+// opening it is what lets the stock upload-artifact work against Gitea instead of aborting.
+func TestPatchedBundleOpensTheArtifactRefusal(t *testing.T) {
+	const artifact = isGhesTSC + "\n" + `uploadArtifact(){if(isGhes()){throw new GHESNotSupportedError()}}`
+
+	out, patched := patchedBundle([]byte(artifact))
+	assert.True(t, patched)
+	assert.True(t, gateOpened(string(out)))
+	assert.Contains(t, string(out), "GHESNotSupportedError", "the refusal itself is left in place, it just stops firing")
+
+	// A bundle using the gate for something this runner has not accounted for is not touched.
+	unknown := strings.Replace(artifact, "GHESNotSupportedError", "SomeOtherError", 1)
+	out, patched = patchedBundle([]byte(unknown))
+	assert.False(t, patched)
+	assert.Equal(t, unknown, string(out))
+}
+
+// requoted respells gateTSC's string literals with another quote character.
+func requoted(quote string) string {
+	gate := strings.ReplaceAll(gateTSC, `'.LOCALHOST'`, quote+".LOCALHOST"+quote)
+	gate = strings.ReplaceAll(gate, `['ACTIONS_RESULTS_URL']`, "["+quote+"ACTIONS_RESULTS_URL"+quote+"]")
+	return strings.ReplaceAll(gate, `['ACTIONS_CACHE_URL']`, "["+quote+"ACTIONS_CACHE_URL"+quote+"]")
+}
+
+// gateOpened reports whether the hostname test was emptied, in whatever quoting the bundle used.
+func gateOpened(body string) bool {
+	return strings.Contains(body, "endsWith(") && !strings.Contains(body, ".LOCALHOST")
+}
+
+// The patched bundle must still be JavaScript, and must resolve the way the runner needs: v2 for
+// an ordinary Gitea host, the cache server for the service URL, and the results URL when there is
+// no cache server. Unpatched, the same bundle must still choose v1, or the patch proves nothing.
+func TestPatchedBundleBehavesInNode(t *testing.T) {
+	requireHostTools(t, "node")
+
+	eval := func(t *testing.T, bundle, prelude, cacheURL string) string {
+		t.Helper()
+
+		script := prelude + bundle + "\nprocess.stdout.write(getCacheServiceVersion()+' '+getCacheServiceURL())"
+		cmd := exec.CommandContext(t.Context(), "node", "-e", script)
+		cmd.Env = append(os.Environ(),
+			"ACTIONS_CACHE_SERVICE_V2=true",
+			"ACTIONS_CACHE_URL="+cacheURL,
+			"ACTIONS_RESULTS_URL=https://gitea.example",
+			"GITHUB_SERVER_URL=https://gitea.example",
+		)
+		out, err := cmd.CombinedOutput()
+		require.NoError(t, err, "%s", out)
+		return string(out)
+	}
+
+	for _, tc := range []struct{ name, bundle, prelude string }{
+		{"tsc", gateTSC, ""},
+		{"webpack", gateWebpack, "const getCacheServiceVersion=()=>config_getCacheServiceVersion();"},
+		{"esbuild", gateEsbuild, "var vu={};const getCacheServiceVersion=()=>XK(),getCacheServiceURL=()=>YK();"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			// Unpatched, a Gitea host is taken for GHES: v1, whose branch already reads the
+			// cache URL. The patch has to move the version without moving that.
+			assert.Equal(t, "v1 http://cache:8088/", eval(t, tc.bundle, tc.prelude, "http://cache:8088/"))
+
+			patched, ok := patchedBundle([]byte(tc.bundle))
+			require.True(t, ok)
+
+			assert.Equal(t, "v2 http://cache:8088/", eval(t, string(patched), tc.prelude, "http://cache:8088/"))
+			assert.Equal(t, "v2 https://gitea.example", eval(t, string(patched), tc.prelude, ""),
+				"with no cache server the results URL is still the fallback")
+		})
+	}
+}
+
+// A bundler that embeds module sources as strings, such as webpack with devtool: eval, carries
+// the gate inside a double-quoted literal. Rewriting the call rather than emptying its argument
+// would end that string early and leave the bundle unparseable.
+func TestPatchedBundleSurvivesInsideAStringLiteral(t *testing.T) {
+	requireHostTools(t, "node")
+
+	escaped := strings.ReplaceAll(gateTSC, `"`, `\"`)
+	embedded := `eval("` + strings.ReplaceAll(escaped, "\n", `\n`) + `");`
+	out, patched := patchedBundle([]byte(embedded))
+	require.True(t, patched)
+
+	file := filepath.Join(t.TempDir(), "bundle.js")
+	require.NoError(t, os.WriteFile(file, out, 0o600))
+	checked, err := exec.CommandContext(t.Context(), "node", "--check", file).CombinedOutput()
+	require.NoError(t, err, "%s", checked)
+}
+
+func TestPatchBundleKeepsTheOriginal(t *testing.T) {
+	dir, script := bundleFile(t, gateTSC)
+	original := originalFor(dir, script)
+
+	require.NoError(t, patchBundle(script, original))
+	patched, err := os.ReadFile(script)
+	require.NoError(t, err)
+	assert.True(t, gateOpened(string(patched)))
+
+	kept, err := os.ReadFile(original)
+	require.NoError(t, err)
+	assert.Equal(t, gateTSC, string(kept), "the untouched bundle is kept outside the action tree")
+	assert.NotContains(t, original, dir+string(filepath.Separator), "originals must not ship into job containers")
+
+	// Patching again must not stack, and must not overwrite the kept original.
+	require.NoError(t, patchBundle(script, original))
+	again, err := os.ReadFile(script)
+	require.NoError(t, err)
+	assert.Equal(t, string(patched), string(again))
+	kept, err = os.ReadFile(original)
+	require.NoError(t, err)
+	assert.Equal(t, gateTSC, string(kept))
+}
+
+// A bundle with nothing to patch is left exactly as it was, with no original kept beside it.
+func TestPatchBundleLeavesOtherActionsAlone(t *testing.T) {
+	dir, script := bundleFile(t, `console.log("checkout")`)
+	original := originalFor(dir, script)
+
+	require.NoError(t, patchBundle(script, original))
+	body, err := os.ReadFile(script)
+	require.NoError(t, err)
+	assert.Equal(t, `console.log("checkout")`, string(body))
+	_, err = os.Stat(original)
+	assert.True(t, os.IsNotExist(err), "no original is kept for a bundle that was not patched")
+}
+
+// bundleFile writes one entrypoint into a fresh action directory.
+func bundleFile(t *testing.T, body string) (dir, script string) {
+	t.Helper()
+
+	dir = t.TempDir()
+	script = filepath.Join(dir, "index.js")
+	require.NoError(t, os.WriteFile(script, []byte(body), 0o600))
+	return dir, script
+}
+
+func TestActionScriptPaths(t *testing.T) {
+	node := &model.Action{Runs: model.ActionRuns{Using: "node20", Main: "dist/restore/index.js", Post: "dist/save/index.js"}}
+	assert.Equal(t, []string{"/a/dist/restore/index.js", "/a/dist/save/index.js"}, actionScriptPaths("/a", node))
+
+	// Only a node action has a bundle to patch.
+	assert.Nil(t, actionScriptPaths("/a", &model.Action{Runs: model.ActionRuns{Using: "docker", Image: "alpine"}}))
+	assert.Nil(t, actionScriptPaths("/a", nil))
+}
+
+// A step that fails with a patched bundle gets the untouched bundle back, and the action is not
+// patched again, so later jobs run it exactly as its author shipped it.
+func TestRevertToolkit(t *testing.T) {
+	dir, script := bundleFile(t, gateTSC)
+	scripts := []string{script}
+
+	patchToolkit(t.Context(), dir, scripts)
+	body, err := os.ReadFile(script)
+	require.NoError(t, err)
+	require.True(t, gateOpened(string(body)), "precondition: the bundle is patched")
+
+	revertToolkit(t.Context(), dir, scripts)
+	body, err = os.ReadFile(script)
+	require.NoError(t, err)
+	assert.Equal(t, gateTSC, string(body), "the original bundle is back")
+
+	// The skip marker survives, so the action stays unpatched from now on.
+	patchToolkit(t.Context(), dir, scripts)
+	body, err = os.ReadFile(script)
+	require.NoError(t, err)
+	assert.Equal(t, gateTSC, string(body), "a reverted action stays unpatched")
+}
+
+// An action whose ref moves is checked out over the patched bundle. The kept original then
+// belongs to the version before the move, and must not be restored over the new one.
+func TestPatchBundleAfterTheActionMoved(t *testing.T) {
+	dir, script := bundleFile(t, gateTSC)
+	original := originalFor(dir, script)
+	scripts := []string{script}
+
+	patchToolkit(t.Context(), dir, scripts)
+	require.NoError(t, os.WriteFile(script, []byte(gateWebpack), 0o600)) // the new version lands
+
+	// Reverting must not roll the action back to the version the original came from.
+	revertToolkit(t.Context(), dir, scripts)
+	body, err := os.ReadFile(script)
+	require.NoError(t, err)
+	assert.Equal(t, gateWebpack, string(body))
+
+	// Nothing was reverted, so the action is not marked off either: the new version is patched
+	// in its own right, and keeps its own original.
+	require.NoFileExists(t, filepath.Join(sidecarDir(dir), skipMarker))
+	require.NoError(t, patchBundle(script, original))
+	body, err = os.ReadFile(script)
+	require.NoError(t, err)
+	assert.True(t, gateOpened(string(body)))
+	kept, err := os.ReadFile(original)
+	require.NoError(t, err)
+	assert.Equal(t, gateWebpack, string(kept))
+}
+
+// The wiring: a step patches its own bundles only when the runner serves the v2 API, and a step
+// that fails gets them back. The action's path inside its repository is part of where they live.
+func TestStepActionRemoteToolkitPatch(t *testing.T) {
+	newStep := func(t *testing.T, env map[string]string) (*stepActionRemote, string) {
+		t.Helper()
+
+		sar := &stepActionRemote{
+			Step:         &model.Step{Uses: "owner/repo/sub@v1"},
+			remoteAction: &remoteAction{Org: "owner", Repo: "repo", Path: "sub", Ref: "v1"},
+			action:       &model.Action{Runs: model.ActionRuns{Using: "node20", Main: "index.js"}},
+			RunContext: &RunContext{
+				Env:    env,
+				Config: &Config{ActionCacheDir: t.TempDir()},
+			},
+		}
+		script := filepath.Join(sar.actionDir(), "sub", "index.js")
+		require.NoError(t, os.MkdirAll(filepath.Dir(script), 0o755))
+		require.NoError(t, os.WriteFile(script, []byte(gateTSC), 0o600))
+		return sar, script
+	}
+
+	t.Run("left alone when the runner does not serve the v2 API", func(t *testing.T) {
+		sar, script := newStep(t, map[string]string{})
+		require.NoError(t, sar.patchActionToolkit(t.Context()))
+
+		body, err := os.ReadFile(script)
+		require.NoError(t, err)
+		assert.Equal(t, gateTSC, string(body))
+	})
+
+	t.Run("patched, and put back when the step fails", func(t *testing.T) {
+		sar, script := newStep(t, map[string]string{CacheServiceV2Env: "true"})
+		require.NoError(t, sar.patchActionToolkit(t.Context()))
+
+		body, err := os.ReadFile(script)
+		require.NoError(t, err)
+		require.True(t, gateOpened(string(body)))
+
+		failed := errors.New("the step failed")
+		require.ErrorIs(t, sar.revertToolkitOnFailure(func(context.Context) error { return failed })(t.Context()), failed)
+
+		body, err = os.ReadFile(script)
+		require.NoError(t, err)
+		assert.Equal(t, gateTSC, string(body))
+	})
+}

docs/job-hooks.md

@@ -0,0 +1,70 @@
+# Job hooks
+
+Job hooks are operator-provided scripts that run **inside the job environment**, before the job's first step and after its last one. They are the equivalent of GitHub's [job hooks](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/run-scripts) and are configured under `runner.hooks` in the runner YAML config (see [config.example.yaml](../internal/pkg/config/config.example.yaml)):
+
+```yaml
+runner:
+  hooks:
+    job_started: /hooks/started.sh
+    job_completed: /hooks/completed.sh
+```
+
+| Setting | Runs |
+| --- | --- |
+| `runner.hooks.job_started` | Before the job's first step, before any action is downloaded |
+| `runner.hooks.job_completed` | After the job's last post step, while the job environment is still up |
+
+`ACTIONS_RUNNER_HOOK_JOB_STARTED` and `ACTIONS_RUNNER_HOOK_JOB_COMPLETED` are read from the runner's environment (`runner.envs`, `runner.env_file`) when the settings are unset, so a configuration carried over from actions/runner keeps working. The settings take precedence. A workflow cannot point the runner at a different hook: the variables are only read from the runner's own environment, never from the job's.
+
+Both hooks are **synchronous** and block the job while they run, and a non-zero exit from either one fails the job. There is no `continue-on-error` and no per-hook timeout — the job's own `runner.timeout` is the only bound. The operator is responsible for the hook's resilience; run anything long in the background from within the hook.
+
+## Where they run
+
+The hooks run in the same place as the job's steps: inside the job container, or on the host in host mode. The paths are resolved *there*, so the script has to exist in the job image or on the host — a path that only exists on the runner host is not visible to a containerized job. For host-wide cleanup that runs after the job environment is gone, use the [post-task script](post-task-script.md) instead.
+
+> This is a deliberate difference from actions/runner, which runs its job hooks on the host, outside any container the job declares. Running them where the steps run is what lets a hook prepare the environment the steps actually see.
+
+The script is run according to its extension:
+
+| Extension | Command |
+| --- | --- |
+| `.sh` | `bash -e <path>` |
+| `.ps1` | `pwsh -command . '<path>'` |
+| anything else | the file itself, which needs its own shebang and executable bit |
+
+As on GitHub, the shell flags applied to `run:` steps are **not** applied to a hook — set `pipefail` or anything else you want inside the script.
+
+### Docker-in-Docker and Docker-out-of-Docker
+
+The hook is executed and its files are exchanged over the Docker API, addressed by container ID, so no path is translated between the runner and the daemon. Both setups work unchanged, but they differ in where the hook file has to be:
+
+- **DinD** — the daemon has its own filesystem. Bake the hook into the job image; a path from the runner's filesystem is not visible to it.
+- **DooD** — the job container is created by the host's daemon, so a bind mount in `container.options` is resolved against the **host**, not against the runner container. Either bake the hook into the job image, or mount a host directory and add it to `container.valid_volumes`.
+
+A hook path that does not exist inside the job environment fails the job with `No such file or directory`, naming the path.
+
+## Environment
+
+A hook sees the job's environment: the workflow, job and `container:` `env:`, the runner's `envs`, and the `GITHUB_*` context variables, with the same masking applied to its output as to a step's. The step-specific ones (`GITHUB_ACTION`, `GITHUB_OUTPUT`, `GITHUB_STATE`) are not set — a hook is not a step, so `::save-state::` and `::set-output::` have nowhere to go.
+
+Its stdout is part of the job log, inside a collapsible group, and is scanned for workflow commands. `::add-mask::` registers a value to be masked for the rest of the job, `::set-env::` and `::add-path::` apply to the steps that follow.
+
+`$GITHUB_ENV` and `$GITHUB_PATH` point at files that are read back after the hook exits, so the file-command form works too:
+
+```bash
+#!/bin/bash
+echo "REGISTRY_TOKEN=$(fetch-token)" >> "$GITHUB_ENV"
+echo "/opt/tooling/bin" >> "$GITHUB_PATH"
+```
+
+Both files are the hook's own, separate from the per-step ones, so nothing a hook writes is truncated by the first step.
+
+## Recommendations
+
+- Keep hooks **fast** and return the right exit code: they are on the critical path of every job, and nothing bounds them.
+- Use **idempotent** operations, and expect `job_completed` to run after success, failure, and cancellation alike.
+- Mask anything secret the hook prints or exports with `::add-mask::`.
+
+## See also
+
+- [Post-task script](post-task-script.md) — host-side cleanup after the job environment is torn down.

docs/post-task-script.md

@@ -150,6 +150,7 @@ powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "%~dp0po
 
 ## See also
 
+- [Job hooks](job-hooks.md) — scripts running inside the job environment, around its steps
 - [Configuration](../README.md#configuration) — generating and loading `config.yaml`
 - [config.example.yaml](../internal/pkg/config/config.example.yaml) — all runner options
 - Bind-workdir idle cleanup (`runner.workdir_cleanup_age`) — separate from this hook; runs only when the runner is idle

go.mod

@@ -38,6 +38,7 @@ require (
 	github.com/timshannon/bolthold v0.0.0-20240314194003-30aac6950928
 	go.etcd.io/bbolt v1.5.0
 	go.yaml.in/yaml/v4 v4.0.0-rc.3
+	golang.org/x/net v0.56.0
 	golang.org/x/sys v0.47.0
 	golang.org/x/term v0.45.0
 	golang.org/x/text v0.40.0
@@ -105,7 +106,6 @@ require (
 	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/crypto v0.53.0 // indirect
-	golang.org/x/net v0.56.0 // indirect
 	golang.org/x/sync v0.22.0 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

internal/app/cmd/daemon.go

@@ -22,6 +22,7 @@ import (
 	"gitea.com/gitea/runner/internal/pkg/config"
 	"gitea.com/gitea/runner/internal/pkg/envcheck"
 	"gitea.com/gitea/runner/internal/pkg/labels"
+	"gitea.com/gitea/runner/internal/pkg/lock"
 	"gitea.com/gitea/runner/internal/pkg/metrics"
 	"gitea.com/gitea/runner/internal/pkg/ver"
 
@@ -49,6 +50,25 @@ func runDaemon(ctx context.Context, daemArgs *daemonArgs, configFile *string) fu
 			return fmt.Errorf("failed to load registration file: %w", err)
 		}
 
+		// Guard against a second runner process sharing this runner file: two
+		// processes with the same identity are indistinguishable to Gitea and
+		// end up cancelling each other's jobs.
+		releaseLock, err := lock.TryLock(cfg.Runner.File)
+		if errors.Is(err, lock.ErrLocked) {
+			log.Errorf("another gitea-runner process is already using %q; each runner process needs its own runner file (runner.file)", cfg.Runner.File)
+			return err
+		} else if err != nil {
+			// Best-effort guard: if the lock file can't be created (e.g. a
+			// read-only runner-file mount), warn and start anyway rather than
+			// refusing to run.
+			log.Warnf("could not lock runner file %q, continuing without the single-process guard: %v", cfg.Runner.File, err)
+		} else {
+			// Held until shutdown finishes: the draining runner still owns this
+			// identity on the server, so releasing early would let a restart
+			// reintroduce the duplicate-identity job cancellations.
+			defer func() { _ = releaseLock() }()
+		}
+
 		lbls := resolveLabels(daemArgs.Labels, cfg.Runner.Labels, reg.Labels)
 
 		ls := labels.Labels{}
@@ -64,6 +84,14 @@ func runDaemon(ctx context.Context, daemArgs *daemonArgs, configFile *string) fu
 			log.Warn("no labels configured, runner may not be able to pick up jobs")
 		}
 
+		// Before the first Docker API call: the standard library resolves the proxy
+		// environment once. Ungated because host labels still reach the daemon.
+		if dockerSocketPath, err := getDockerSocketPath(cfg.Container.DockerHost); err == nil {
+			run.BypassProxyForDockerHost(dockerSocketPath)
+		} else {
+			log.Debugf("cannot resolve the docker socket path, so Docker API calls are not exempted from the proxy: %v", err)
+		}
+
 		if ls.RequireDocker() || cfg.Container.RequireDocker {
 			// Wait for dockerd be ready
 			if timeout := cfg.Container.DockerTimeout; timeout > 0 {
@@ -101,6 +129,7 @@ func runDaemon(ctx context.Context, daemArgs *daemonArgs, configFile *string) fu
 			}
 			// if dockerSocketPath passes the check, override DOCKER_HOST with dockerSocketPath
 			os.Setenv("DOCKER_HOST", dockerSocketPath)
+			run.WarnIfDaemonHasNoProxy(ctx)
 			// empty cfg.Container.DockerHost means runner need to find an available docker host automatically
 			// and assign the path to cfg.Container.DockerHost
 			if cfg.Container.DockerHost == "" {
@@ -132,6 +161,11 @@ func runDaemon(ctx context.Context, daemArgs *daemonArgs, configFile *string) fu
 		)
 
 		runner := run.NewRunner(cfg, reg, cli)
+		defer func() {
+			if err := runner.Close(); err != nil {
+				log.Warnf("runner %s: cache server shutdown: %v", reg.Name, err)
+			}
+		}()
 
 		// declare the labels of the runner before fetching tasks
 		resp, err := runner.Declare(ctx, ls.Names())

internal/app/cmd/exec.go

@@ -22,6 +22,7 @@ import (
 	"gitea.com/gitea/runner/act/common"
 	"gitea.com/gitea/runner/act/model"
 	"gitea.com/gitea/runner/act/runner"
+	"gitea.com/gitea/runner/internal/app/run"
 
 	"github.com/joho/godotenv"
 	"github.com/moby/moby/api/types/container"
@@ -131,6 +132,8 @@ func (i *executeArgs) LoadEnvs() map[string]string {
 	_ = readEnvs(i.Envfile(), envs)
 
 	envs["ACTIONS_CACHE_URL"] = i.cacheHandler.ExternalURL() + "/"
+	// The same server answers the cache service v2 API, so let the actions reach it.
+	envs[runner.CacheServiceV2Env] = "true"
 
 	return envs
 }
@@ -415,6 +418,11 @@ func runExec(ctx context.Context, execArgs *executeArgs) func(cmd *cobra.Command
 		}
 		handler.RegisterJob(actionsRuntimeToken, "__local/__exec")
 
+		// no service aliases: exec builds one config for the whole plan
+		run.BypassProxyForDockerHost(os.Getenv("DOCKER_HOST"))
+		proxyEnv := run.JobProxyEnv(env, env["ACTIONS_CACHE_URL"], nil)
+		maps.Copy(env, proxyEnv)
+
 		// run the plan
 		config := &runner.Config{
 			Workdir:               execArgs.Workdir(),
@@ -425,6 +433,7 @@ func runExec(ctx context.Context, execArgs *executeArgs) func(cmd *cobra.Command
 			LogOutput:             true,
 			JSONLogger:            execArgs.jsonLogger,
 			Env:                   env,
+			ProxyEnv:              proxyEnv,
 			Vars:                  execArgs.LoadVars(),
 			Secrets:               execArgs.LoadSecrets(),
 			InsecureSecrets:       execArgs.insecureSecrets,

internal/app/cmd/register.go

@@ -18,6 +18,7 @@ import (
 	"gitea.com/gitea/runner/internal/pkg/client"
 	"gitea.com/gitea/runner/internal/pkg/config"
 	"gitea.com/gitea/runner/internal/pkg/labels"
+	"gitea.com/gitea/runner/internal/pkg/lock"
 	"gitea.com/gitea/runner/internal/pkg/ver"
 
 	"connectrpc.com/connect"
@@ -346,6 +347,19 @@ func registerNoInteractive(ctx context.Context, configFile string, regArgs *regi
 }
 
 func doRegister(ctx context.Context, cfg *config.Config, inputs *registerInputs) error {
+	// Refuse to rewrite the runner file while another process is using it.
+	releaseLock, err := lock.TryLock(cfg.Runner.File)
+	if errors.Is(err, lock.ErrLocked) {
+		return fmt.Errorf("another process is already using %q; stop it before re-registering", cfg.Runner.File)
+	} else if err != nil {
+		// Best-effort guard: if the lock file can't be created, warn and
+		// register anyway; writing the runner file will surface any real
+		// permission problem with a clearer error.
+		log.Warnf("could not lock runner file %q, continuing without the single-process guard: %v", cfg.Runner.File, err)
+	} else {
+		defer func() { _ = releaseLock() }()
+	}
+
 	// initial http client
 	cli := client.New(
 		inputs.InstanceAddr,

internal/app/run/proxy.go

@@ -0,0 +1,163 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package run
+
+import (
+	"context"
+	"net/url"
+	"os"
+	"slices"
+	"strings"
+
+	"gitea.com/gitea/runner/act/container"
+
+	log "github.com/sirupsen/logrus"
+	"golang.org/x/net/http/httpproxy"
+)
+
+// proxyFromEnv returns the runner's own proxy configuration, or nil when it has none.
+func proxyFromEnv() *httpproxy.Config {
+	cfg := httpproxy.FromEnvironment()
+	if cfg.HTTPProxy == "" && cfg.HTTPSProxy == "" {
+		return nil
+	}
+	return cfg
+}
+
+// JobProxyEnv returns the proxy variables a job runs with, given what runner.envs already
+// put in jobEnvs. Gitea is deliberately not made direct, so it stays reachable however the
+// runner reaches it.
+func JobProxyEnv(jobEnvs map[string]string, cacheURL string, serviceNames []string) map[string]string {
+	cfg := proxyFromEnv()
+	if cfg == nil {
+		return nil
+	}
+
+	// Go bypasses loopback on its own, curl and most other tools in a job do not.
+	direct := append([]string{"localhost", "127.0.0.1", "::1"}, serviceNames...)
+	direct = append(direct, hostOf(cacheURL))
+
+	proxyEnv := map[string]string{}
+	setPair := func(lower, upper, value string) {
+		if value == "" {
+			return
+		}
+		// Either spelling in runner.envs takes over both, so the pair cannot disagree.
+		if existing, ok := jobEnvs[lower]; ok {
+			value = existing
+		} else if existing, ok := jobEnvs[upper]; ok {
+			value = existing
+		}
+		proxyEnv[lower], proxyEnv[upper] = value, value
+	}
+	setPair("http_proxy", "HTTP_PROXY", cfg.HTTPProxy)
+	setPair("https_proxy", "HTTPS_PROXY", cfg.HTTPSProxy)
+
+	// no_proxy is merged rather than replaced: the hosts above are structural, and an
+	// operator cannot list the cache server's startup-assigned address in advance.
+	noProxy := appendNoProxy(cfg.NoProxy, direct...)
+	for _, name := range []string{"no_proxy", "NO_PROXY"} {
+		if existing, ok := jobEnvs[name]; ok {
+			noProxy = appendNoProxy(existing, strings.Split(noProxy, ",")...)
+			break
+		}
+	}
+	proxyEnv["no_proxy"], proxyEnv["NO_PROXY"] = noProxy, noProxy
+	return proxyEnv
+}
+
+// BypassProxyForDockerHost keeps the runner's Docker API traffic off the proxy: the docker
+// client proxies every transport that is not a unix socket or a named pipe, so a tcp://
+// daemon would be reached through a proxy that cannot route to it.
+//
+// It must run before the first Docker API call, because the standard library resolves the
+// proxy environment once.
+func BypassProxyForDockerHost(dockerHost string) {
+	cfg := proxyFromEnv()
+	if cfg == nil {
+		return
+	}
+	host := hostOf(dockerHost)
+	if host == "" {
+		// A unix socket or named pipe is never proxied.
+		return
+	}
+
+	noProxy := appendNoProxy(cfg.NoProxy, host)
+	for _, name := range []string{"no_proxy", "NO_PROXY"} {
+		if err := os.Setenv(name, noProxy); err != nil {
+			log.Warnf("cannot set %s for the runner process: %v", name, err)
+		}
+	}
+	log.Debugf("docker host %s is reached directly, no_proxy is now %q", host, noProxy)
+}
+
+// WarnIfDaemonHasNoProxy points at the one part the runner cannot set: the docker daemon
+// pulls the images, and a daemon in its own container needs its own proxy.
+func WarnIfDaemonHasNoProxy(ctx context.Context) {
+	if proxyFromEnv() == nil {
+		return
+	}
+	info, err := container.GetHostInfo(ctx)
+	if err != nil {
+		log.Debugf("cannot read the docker daemon's proxy configuration: %v", err)
+		return
+	}
+	if info.HTTPProxy == "" && info.HTTPSProxy == "" {
+		log.Warn("the runner has a proxy but the docker daemon reports none, so image pulls will not use it: https://docs.docker.com/engine/daemon/proxy/")
+	}
+}
+
+// proxyPasswords returns the passwords embedded in the runner's proxy URLs, to mask before
+// a job echoes its environment.
+func proxyPasswords() []string {
+	cfg := proxyFromEnv()
+	if cfg == nil {
+		return nil
+	}
+
+	var passwords []string
+	for _, raw := range []string{cfg.HTTPProxy, cfg.HTTPSProxy} {
+		parsed, err := url.Parse(raw)
+		if err != nil || parsed.User == nil {
+			continue
+		}
+		if password, ok := parsed.User.Password(); ok && password != "" && !slices.Contains(passwords, password) {
+			passwords = append(passwords, password)
+		}
+	}
+	return passwords
+}
+
+// appendNoProxy adds hosts to a no_proxy list, keeping the operator's entries and adding
+// none twice.
+func appendNoProxy(noProxy string, hosts ...string) string {
+	entries := []string{}
+	for entry := range strings.SplitSeq(noProxy, ",") {
+		if entry = strings.TrimSpace(entry); entry != "" {
+			entries = append(entries, entry)
+		}
+	}
+
+	for _, host := range hosts {
+		if host == "" || slices.Contains(entries, host) {
+			continue
+		}
+		entries = append(entries, host)
+	}
+	return strings.Join(entries, ",")
+}
+
+// hostOf returns the host of a URL without its port, the form a no_proxy entry takes. It is
+// empty for anything without a network host, such as a unix socket.
+func hostOf(raw string) string {
+	if raw == "" {
+		return ""
+	}
+	parsed, err := url.Parse(strings.TrimSuffix(raw, "/"))
+	if err != nil || parsed.Hostname() == "" {
+		return ""
+	}
+	return parsed.Hostname()
+}

internal/app/run/proxy_test.go

@@ -0,0 +1,192 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package run
+
+import (
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// clearProxyEnv starts a test from a runner that has no proxy, whatever the developer's own
+// environment looks like.
+func clearProxyEnv(t *testing.T) {
+	t.Helper()
+	for _, name := range []string{"http_proxy", "HTTP_PROXY", "https_proxy", "HTTPS_PROXY", "no_proxy", "NO_PROXY"} {
+		t.Setenv(name, "")
+	}
+}
+
+func TestJobProxyEnv(t *testing.T) {
+	const loopback = "localhost,127.0.0.1,::1"
+	const proxy = "http://proxy:3128"
+
+	for _, tc := range []struct {
+		name     string
+		runner   map[string]string // the runner process environment
+		envs     map[string]string // what runner.envs already put in the job
+		cacheURL string
+		services []string
+		want     map[string]string
+	}{
+		{
+			// The guarantee that makes this safe to ship: a runner without a proxy gives its
+			// jobs nothing at all.
+			name:     "runner has no proxy",
+			cacheURL: "http://cache.local:8088/",
+		},
+		{
+			name:   "a lone no_proxy is not a proxy",
+			runner: map[string]string{"no_proxy": "example.com"},
+		},
+		{
+			name:   "both spellings of every variable",
+			runner: map[string]string{"http_proxy": proxy, "https_proxy": proxy},
+			want: map[string]string{
+				"http_proxy": proxy, "HTTP_PROXY": proxy,
+				"https_proxy": proxy, "HTTPS_PROXY": proxy,
+				"no_proxy": loopback, "NO_PROXY": loopback,
+			},
+		},
+		{
+			name:   "a variable the runner does not have is omitted",
+			runner: map[string]string{"https_proxy": proxy},
+			want: map[string]string{
+				"https_proxy": proxy, "HTTPS_PROXY": proxy,
+				"no_proxy": loopback, "NO_PROXY": loopback,
+			},
+		},
+		{
+			// The cache server and the service containers are on the local network; Gitea is
+			// not added and keeps being reached through the proxy.
+			name:     "hosts the job must reach directly",
+			runner:   map[string]string{"http_proxy": proxy, "no_proxy": "internal.example"},
+			cacheURL: "http://192.168.1.10:34567/",
+			services: []string{"postgres", "redis"},
+			want: map[string]string{
+				"http_proxy": proxy, "HTTP_PROXY": proxy,
+				"no_proxy": "internal.example," + loopback + ",postgres,redis,192.168.1.10",
+				"NO_PROXY": "internal.example," + loopback + ",postgres,redis,192.168.1.10",
+			},
+		},
+		{
+			name:   "runner.envs wins, for both spellings",
+			runner: map[string]string{"http_proxy": "http://from-env:3128"},
+			envs:   map[string]string{"http_proxy": "http://from-config:3128"},
+			want: map[string]string{
+				"http_proxy": "http://from-config:3128", "HTTP_PROXY": "http://from-config:3128",
+				"no_proxy": loopback, "NO_PROXY": loopback,
+			},
+		},
+		{
+			name:   "runner.envs wins through the upper case spelling too",
+			runner: map[string]string{"http_proxy": "http://from-env:3128"},
+			envs:   map[string]string{"HTTP_PROXY": "http://from-config:3128"},
+			want: map[string]string{
+				"http_proxy": "http://from-config:3128", "HTTP_PROXY": "http://from-config:3128",
+				"no_proxy": loopback, "NO_PROXY": loopback,
+			},
+		},
+		{
+			// A runner.envs no_proxy adds to the hosts that must stay direct rather than
+			// replacing them, which would send cache traffic through the proxy.
+			name:     "runner.envs no_proxy is merged, not substituted",
+			runner:   map[string]string{"http_proxy": proxy},
+			envs:     map[string]string{"no_proxy": "operator.example"},
+			cacheURL: "http://192.168.1.10:34567/",
+			want: map[string]string{
+				"http_proxy": proxy, "HTTP_PROXY": proxy,
+				"no_proxy": "operator.example," + loopback + ",192.168.1.10",
+				"NO_PROXY": "operator.example," + loopback + ",192.168.1.10",
+			},
+		},
+		{
+			name:     "runner.envs NO_PROXY is merged through the upper case spelling too",
+			runner:   map[string]string{"http_proxy": proxy},
+			envs:     map[string]string{"NO_PROXY": "operator.example"},
+			cacheURL: "http://192.168.1.10:34567/",
+			want: map[string]string{
+				"http_proxy": proxy, "HTTP_PROXY": proxy,
+				"no_proxy": "operator.example," + loopback + ",192.168.1.10",
+				"NO_PROXY": "operator.example," + loopback + ",192.168.1.10",
+			},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			clearProxyEnv(t)
+			for name, value := range tc.runner {
+				t.Setenv(name, value)
+			}
+			assert.Equal(t, tc.want, JobProxyEnv(tc.envs, tc.cacheURL, tc.services))
+		})
+	}
+}
+
+// docker-in-docker over tcp: the docker client would otherwise send API calls to a proxy
+// that cannot route to the daemon.
+func TestBypassProxyForDockerHost(t *testing.T) {
+	for _, tc := range []struct {
+		name       string
+		httpProxy  string
+		dockerHost string
+		want       string
+	}{
+		{
+			name:       "tcp daemon is added",
+			httpProxy:  "http://proxy:3128",
+			dockerHost: "tcp://docker:2375",
+			want:       "internal.example,docker",
+		},
+		{
+			name:       "unix socket is left alone",
+			httpProxy:  "http://proxy:3128",
+			dockerHost: "unix:///var/run/docker.sock",
+			want:       "internal.example",
+		},
+		{
+			name:       "nothing happens without a proxy",
+			dockerHost: "tcp://docker:2375",
+			want:       "internal.example",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			clearProxyEnv(t)
+			t.Setenv("no_proxy", "internal.example")
+			if tc.httpProxy != "" {
+				t.Setenv("http_proxy", tc.httpProxy)
+			}
+
+			BypassProxyForDockerHost(tc.dockerHost)
+
+			assert.Equal(t, tc.want, os.Getenv("no_proxy"))
+		})
+	}
+}
+
+func TestProxyPasswords(t *testing.T) {
+	clearProxyEnv(t)
+	t.Setenv("http_proxy", "http://user:hunter2@proxy:3128")
+	t.Setenv("https_proxy", "http://user:s3cret@proxy:3128")
+	assert.Equal(t, []string{"hunter2", "s3cret"}, proxyPasswords())
+
+	t.Setenv("https_proxy", "http://proxy:3128")
+	assert.Equal(t, []string{"hunter2"}, proxyPasswords())
+}
+
+func TestAppendNoProxy(t *testing.T) {
+	assert.Equal(t, "a.example,b.example", appendNoProxy(" a.example , b.example "))
+	// a host already listed is not repeated
+	assert.Equal(t, "cache.local", appendNoProxy("cache.local", "cache.local"))
+	assert.Empty(t, appendNoProxy("", "", ""))
+}
+
+func TestHostOf(t *testing.T) {
+	assert.Equal(t, "cache.local", hostOf("http://cache.local:8088/"))
+	assert.Equal(t, "192.168.1.10", hostOf("http://192.168.1.10:34567"))
+	// nothing to bypass for a socket path or an unparseable URL
+	assert.Empty(t, hostOf("unix:///var/run/docker.sock"))
+	assert.Empty(t, hostOf("cache.local:8088"))
+	assert.Empty(t, hostOf("://nope"))
+}

internal/app/run/runner.go

@@ -14,6 +14,7 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strconv"
 	"strings"
 	"sync"
@@ -53,6 +54,7 @@ func RunnerCapabilities() []string {
 // Runner runs the pipeline.
 type Runner struct {
 	name string
+	uuid string
 
 	cfg *config.Config
 
@@ -107,6 +109,12 @@ func NewRunner(cfg *config.Config, reg *config.Registration, cli client.Client)
 		}
 	}
 
+	if envs["ACTIONS_CACHE_URL"] != "" && (cfg.Cache.V2 == nil || *cfg.Cache.V2) {
+		// act patches the GHES check out of an action's bundle when it sees this, so the client
+		// uses the cache service v2 API this server also answers; see act/runner/toolkit_patch.go.
+		envs[runner.CacheServiceV2Env] = "true"
+	}
+
 	// set artifact gitea api
 	artifactGiteaAPI := strings.TrimSuffix(cli.Address(), "/") + "/api/actions_pipeline/"
 	envs["ACTIONS_RUNTIME_URL"] = artifactGiteaAPI
@@ -118,6 +126,7 @@ func NewRunner(cfg *config.Config, reg *config.Registration, cli client.Client)
 
 	runner := &Runner{
 		name:           reg.Name,
+		uuid:           reg.UUID,
 		cfg:            cfg,
 		client:         cli,
 		labels:         ls,
@@ -129,6 +138,14 @@ func NewRunner(cfg *config.Config, reg *config.Registration, cli client.Client)
 	return runner
 }
 
+// Close shuts down the cache server this runner exposes to job containers.
+func (r *Runner) Close() error {
+	return r.cacheHandler.Close()
+}
+
+// removeOrphanNetworks is a variable so tests can substitute one that needs no Docker daemon.
+var removeOrphanNetworks = container.RemoveOrphanNetworks
+
 // OnIdle performs lightweight maintenance during polling idle windows.
 // It runs synchronously on the poller goroutine; shouldRunIdleCleanup
 // throttles invocations to runner.idle_cleanup_interval so the impact on
@@ -150,6 +167,21 @@ func (r *Runner) OnIdle(ctx context.Context) {
 	if hostRoot := filepath.FromSlash(r.cfg.Host.WorkdirParent); hostRoot != "" {
 		r.cleanupStaleDirs(ctx, hostRoot, isHostScratchDir)
 	}
+	r.cleanupOrphanNetworks(ctx)
+}
+
+// cleanupOrphanNetworks reclaims the per-job networks of jobs this runner did not live to
+// tear down. A labelled network with no containers on it is finished with, and as for the
+// directories above, a task beginning during the pass is safe because the cutoff keeps a
+// network it has created but not yet attached a container to out of scope.
+func (r *Runner) cleanupOrphanNetworks(ctx context.Context) {
+	if r.uuid == "" || !r.labels.RequireDocker() && !r.cfg.Container.RequireDocker {
+		return
+	}
+	cutoff := r.now().Add(-r.cfg.Runner.WorkdirCleanupAge)
+	if err := removeOrphanNetworks(ctx, r.uuid, cutoff); err != nil {
+		log.Warnf("failed to clean up networks left behind by earlier jobs: %v", err)
+	}
 }
 
 func (r *Runner) shouldRunIdleCleanup() bool {
@@ -268,7 +300,8 @@ func (r *Runner) Run(ctx context.Context, task *runnerv1.Task) error {
 
 	ctx, cancel := context.WithTimeout(ctx, r.cfg.Runner.Timeout)
 	defer cancel()
-	reporter := report.NewReporter(ctx, cancel, r.client, task, r.cfg)
+	// A proxy URL may carry credentials, and every job is given it; keep them out of the log.
+	reporter := report.NewReporter(ctx, cancel, r.client, task, r.cfg, proxyPasswords()...)
 	var runErr error
 	defer func() {
 		r.runningCount.Add(-1)
@@ -341,6 +374,11 @@ func (r *Runner) run(ctx context.Context, task *runnerv1.Task, reporter *report.
 	taskContext := task.Context.Fields
 	envs := r.cloneEnvs()
 
+	// Added per task because this job's service containers must be reached directly, and
+	// act reaches them by their workflow key.
+	proxyEnv := JobProxyEnv(envs, envs["ACTIONS_CACHE_URL"], slices.Sorted(maps.Keys(job.Services)))
+	maps.Copy(envs, proxyEnv)
+
 	if r.capabilities != "" {
 		envs["GITEA_ACTIONS_CAPABILITIES"] = r.capabilities
 	}
@@ -450,6 +488,7 @@ func (r *Runner) run(ctx context.Context, task *runnerv1.Task, reporter *report.
 		LogOutput:            true,
 		JSONLogger:           false,
 		Env:                  envs,
+		ProxyEnv:             proxyEnv,
 		Secrets:              task.Secrets,
 		GitHubInstance:       strings.TrimSuffix(r.client.Address(), "/"),
 		AutoRemove:           true,
@@ -464,6 +503,9 @@ func (r *Runner) run(ctx context.Context, task *runnerv1.Task, reporter *report.
 		ContainerNetworkCreateOptions: container.NewDockerNetworkCreateExecutorInput{
 			EnableIPv4: r.cfg.Container.NetworkCreateOptions.EnableIPv4,
 			EnableIPv6: r.cfg.Container.NetworkCreateOptions.EnableIPv6,
+			// so a network this job leaks, if the runner dies before its teardown, can be
+			// told apart from one belonging to another runner on the same daemon
+			RunnerUUID: r.uuid,
 		},
 		ContainerOptions:                  r.cfg.Container.Options,
 		ContainerDaemonSocket:             r.cfg.Container.DockerHost,
@@ -471,6 +513,8 @@ func (r *Runner) run(ctx context.Context, task *runnerv1.Task, reporter *report.
 		DefaultActionInstance:             r.getDefaultActionsURL(task),
 		DefaultActionInstanceIsSelfHosted: r.isSelfHostedActionsURL(task),
 		PlatformPicker:                    r.labels.PickPlatform,
+		JobStartedHook:                    r.cfg.Runner.Hooks.JobStarted,
+		JobCompletedHook:                  r.cfg.Runner.Hooks.JobCompleted,
 		Vars:                              task.Vars,
 		ValidVolumes:                      r.cfg.Container.ValidVolumes,
 		InsecureSkipTLS:                   r.cfg.Runner.Insecure,

internal/app/run/runner_idle_cleanup_test.go

@@ -297,3 +297,37 @@ func TestRunnerOnIdleSkipsWhenAlreadyCancelled(t *testing.T) {
 
 	assert.DirExists(t, stale)
 }
+
+// The idle sweep reclaims the docker networks of jobs this runner did not live to tear down,
+// and stays out of the way of runners that share the daemon but not the registration.
+func TestRunnerOnIdleRemovesOrphanNetworks(t *testing.T) {
+	now := time.Date(2026, time.April, 29, 20, 0, 0, 0, time.UTC)
+	cfg := &config.Config{
+		Container: config.Container{RequireDocker: true},
+		Runner: config.Runner{
+			WorkdirCleanupAge:   24 * time.Hour,
+			IdleCleanupInterval: time.Minute,
+		},
+	}
+
+	var swept []string
+	var sweptCutoff time.Time
+	origRemoveOrphanNetworks := removeOrphanNetworks
+	removeOrphanNetworks = func(_ context.Context, runnerUUID string, createdBefore time.Time) error {
+		swept = append(swept, runnerUUID)
+		sweptCutoff = createdBefore
+		return nil
+	}
+	t.Cleanup(func() { removeOrphanNetworks = origRemoveOrphanNetworks })
+
+	r := &Runner{uuid: "runner-1", cfg: cfg, now: func() time.Time { return now }}
+	r.OnIdle(context.Background())
+	assert.Equal(t, []string{"runner-1"}, swept)
+	// a network of a job starting during the pass is younger than this and so out of scope
+	assert.Equal(t, now.Add(-24*time.Hour), sweptCutoff)
+
+	// a host-only runner has no daemon to sweep
+	hostOnly := &Runner{uuid: "runner-2", cfg: &config.Config{Runner: cfg.Runner}, now: func() time.Time { return now }}
+	hostOnly.OnIdle(context.Background())
+	assert.Equal(t, []string{"runner-1"}, swept)
+}

internal/app/run/runner_test.go

@@ -7,12 +7,14 @@ import (
 	"context"
 	"testing"
 
+	"gitea.com/gitea/runner/act/runner"
 	clientmocks "gitea.com/gitea/runner/internal/pkg/client/mocks"
 	"gitea.com/gitea/runner/internal/pkg/config"
 	"gitea.com/gitea/runner/internal/pkg/ver"
 
 	"connectrpc.com/connect"
 	runnerv1 "gitea.dev/actions-proto-go/runner/v1"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
 	"github.com/stretchr/testify/require"
 	"google.golang.org/protobuf/types/known/structpb"
@@ -91,6 +93,25 @@ func TestNewRunnerInitializesLabelsAndEnvironment(t *testing.T) {
 	require.Equal(t, "true", r.envs["GITEA_ACTIONS"])
 	require.NotEmpty(t, r.envs["GITEA_ACTIONS_RUNNER_VERSION"])
 	require.Nil(t, r.cacheHandler)
+	require.Empty(t, r.envs[runner.CacheServiceV2Env], "no cache server, nothing to serve v2 from")
+}
+
+// Proxy variables are assembled per task, because a job's service containers have to be
+// reached directly and they are only known once the workflow is parsed.
+func TestNewRunnerLeavesProxyToTheTask(t *testing.T) {
+	clearProxyEnv(t)
+	t.Setenv("http_proxy", "http://proxy:3128")
+
+	cfg := &config.Config{}
+	cfg.Cache.ExternalServer = "http://cache.local:8088/"
+	reg := &config.Registration{Name: "runner"}
+	cli := clientmocks.NewClient(t)
+	cli.On("Address").Return("https://gitea.example/").Maybe()
+
+	r := NewRunner(cfg, reg, cli)
+
+	require.NotContains(t, r.envs, "http_proxy")
+	require.NotContains(t, r.envs, "no_proxy")
 }
 
 func taskWithDefaultActionsURL(url string) *runnerv1.Task {
@@ -102,3 +123,22 @@ func taskWithDefaultActionsURL(url string) *runnerv1.Task {
 		},
 	}
 }
+
+// The cache service v2 API is announced to jobs unless it is turned off. Announcing it is what
+// makes act patch the GHES check out of an action's bundle, so the client can reach it.
+func TestNewRunnerCacheServiceV2(t *testing.T) {
+	announced := func(v2 *bool) string {
+		cfg := &config.Config{}
+		cfg.Cache.V2, cfg.Cache.Dir, cfg.Cache.Host = v2, t.TempDir(), "127.0.0.1"
+		cli := clientmocks.NewClient(t)
+		cli.On("Address").Return("https://gitea.example/").Maybe()
+
+		r := NewRunner(cfg, &config.Registration{Name: "runner"}, cli)
+		t.Cleanup(func() { _ = r.Close() })
+		return r.envs[runner.CacheServiceV2Env]
+	}
+
+	off := false
+	assert.Equal(t, "true", announced(nil))
+	assert.Empty(t, announced(&off))
+}

internal/pkg/config/config.example.yaml

@@ -15,6 +15,9 @@ runner:
   # Where to store the registration result.
   file: .runner
   # Execute how many tasks concurrently at the same time.
+  # With `container.network` empty, each concurrent docker job takes a subnet from the
+  # daemon's address pool, so a high capacity can exhaust it. See `default-address-pools`
+  # in the docker daemon config.
   capacity: 1
   # Extra environment variables to run jobs.
   envs:
@@ -43,9 +46,12 @@ runner:
   # While idle, remove stale bind-workdir task directories and orphaned host-mode
   # scratch directories (left behind when a host cleanup delete stalls) older than
   # this duration. Setting either workdir_cleanup_age or idle_cleanup_interval to 0
-  # (or any non-positive value) disables stale-directory cleanup entirely.
+  # (or any non-positive value) disables stale-directory cleanup entirely, along with
+  # the docker network cleanup below.
   workdir_cleanup_age: 24h
-  # Cadence for the idle stale-directory cleanup pass.
+  # Cadence for the idle cleanup pass. Besides the directories above, on runners that use
+  # docker it removes the per-job networks of jobs this runner did not live to tear down,
+  # which would otherwise hold a subnet of the daemon address pool until the host is rebuilt.
   idle_cleanup_interval: 10m
   # The base interval for periodic log flush to the Gitea instance.
   # Logs may be sent earlier if the buffer reaches log_report_batch_size
@@ -104,6 +110,14 @@ runner:
   post_task_script: ''
   # Hard limit on post_task_script runtime. Default if omitted: 5m.
   post_task_script_timeout: 5m
+  # Scripts run inside the job environment before the job's first step and after its last
+  # one, the equivalent of GitHub's ACTIONS_RUNNER_HOOK_JOB_STARTED and
+  # ACTIONS_RUNNER_HOOK_JOB_COMPLETED, which are read when these are unset. The paths are
+  # resolved inside the job environment. Either one failing fails the job.
+  # Full guide: docs/job-hooks.md
+  hooks:
+    job_started: ''
+    job_completed: ''
 
 cache:
   # Enable the built-in cache server (used by actions/cache and similar actions).
@@ -141,6 +155,11 @@ cache:
   # A moved tag (e.g. a re-tagged "v6") or an updated branch stays at the cached commit
   # until its cache entry expires or is manually removed.
   offline_mode: false
+  # Serve the actions cache service v2 API, used by actions/cache@v4.2 and later. Those actions
+  # refuse any host they do not take for GitHub, so reaching it means editing that check out of
+  # the action's own bundle, keeping the untouched copy beside it. The same edit lets the stock
+  # upload-artifact and download-artifact work here. A bundle that does not match is left alone.
+  v2: true
 
 container:
   # Specifies the network to which the container will connect.
@@ -153,13 +172,19 @@ container:
   # network_create_options only apply when `network` is left empty and the runner
   # auto-creates a per-job network that does not already exist. They have no effect
   # when a custom `network` name is set, because that network is used as-is and never
-  # created by the runner. Omit the entire block to use Docker's defaults.
+  # created by the runner. Omit the entire block to use Docker's defaults. An auto-created
+  # network is labelled com.gitea.runner.uuid=<this runner's uuid>, which is how the idle
+  # cleanup tells its own leftovers apart from those of other runners on the same daemon.
   network_create_options:
     enable_ipv4: true  # Omit to use Docker's default (IPv4 enabled). Set false to disable IPv4.
     enable_ipv6: false # Omit to use Docker's default (IPv6 disabled). Enabling it requires dockerd started with --ipv6.
   # Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
   privileged: false
-  # Any other options to be used when the container is started (e.g., --add-host=my.gitea.url:host-gateway).
+  # Any other options to be used when the container is started, for example:
+  #   options: --add-host=my.gitea.url:host-gateway
+  # A volume declared here replaces the one the runner mounts on the same container path, so the
+  # tool cache can be kept on the host. Its source must also be allowed by valid_volumes below:
+  #   options: --volume /host/toolcache:/opt/hostedtoolcache
   options:
   # The parent directory of a job's working directory.
   # NOTE: There is no need to add the first '/' of the path as runner will add it automatically.
@@ -185,6 +210,9 @@ container:
   docker_host: ""
   # Pull docker image(s) even if already present.
   # Defaults to false when the key is omitted.
+  # Two exceptions: an image pinned by digest (image@sha256:...) cannot change, so it is never
+  # re-pulled, and a pull that fails while a copy is already on the host does not fail the job,
+  # which runs on that copy with a warning in its log.
   force_pull: false
   # Rebuild docker image(s) even if already present
   force_rebuild: false

internal/pkg/config/config.go

@@ -4,6 +4,7 @@
 package config
 
 import (
+	"bytes"
 	"errors"
 	"fmt"
 	"maps"
@@ -41,7 +42,7 @@ type Runner struct {
 	FetchInterval         time.Duration     `yaml:"fetch_interval"`           // FetchInterval specifies the interval duration for fetching resources.
 	FetchIntervalMax      time.Duration     `yaml:"fetch_interval_max"`       // FetchIntervalMax specifies the maximum backoff interval when idle.
 	WorkdirCleanupAge     time.Duration     `yaml:"workdir_cleanup_age"`      // WorkdirCleanupAge removes stale bind-workdir task directories and orphaned host-mode scratch dirs older than this duration during idle cleanup.
-	IdleCleanupInterval   time.Duration     `yaml:"idle_cleanup_interval"`    // IdleCleanupInterval runs stale-directory cleanup periodically while the runner is idle. Set to 0 to disable cleanup cadence.
+	IdleCleanupInterval   time.Duration     `yaml:"idle_cleanup_interval"`    // IdleCleanupInterval runs the idle cleanup (stale directories and orphaned docker networks) periodically while the runner is idle. Set to 0 to disable cleanup cadence.
 	LogReportInterval     time.Duration     `yaml:"log_report_interval"`      // LogReportInterval specifies the base interval for periodic log flush.
 	LogReportMaxLatency   time.Duration     `yaml:"log_report_max_latency"`   // LogReportMaxLatency specifies the max time a log row can wait before being sent.
 	LogReportBatchSize    int               `yaml:"log_report_batch_size"`    // LogReportBatchSize triggers immediate log flush when buffer reaches this size.
@@ -54,6 +55,13 @@ type Runner struct {
 	AllocatePTY           bool              `yaml:"allocate_pty"`             // AllocatePTY allocates a pseudo-TTY for each step's process. Default is false, matching GitHub's actions/runner. Enable only for jobs that need an interactive terminal; tools like docker build emit redrawing progress frames into the captured log when a TTY is present. Applies to both host and docker backends.
 	PostTaskScript        string            `yaml:"post_task_script"`         // PostTaskScript is the path to an executable script run on the host after each task's cleanup completes. Empty disables the hook. On Windows use .exe/.bat/.cmd; PowerShell (.ps1) is not supported yet as the configured path.
 	PostTaskScriptTimeout time.Duration     `yaml:"post_task_script_timeout"` // PostTaskScriptTimeout caps how long the post-task script may run. Default is 5m when post_task_script is set.
+	Hooks                 RunnerHooks       `yaml:"hooks"`                    // Hooks are scripts run inside the job environment around the job's steps.
+}
+
+// RunnerHooks represents the scripts run inside the job environment around the job's steps.
+type RunnerHooks struct {
+	JobStarted   string `yaml:"job_started"`   // JobStarted is the path of a script run before the job's first step. Falls back to ACTIONS_RUNNER_HOOK_JOB_STARTED; a failure fails the job.
+	JobCompleted string `yaml:"job_completed"` // JobCompleted is the path of a script run after the job's last step, while the job environment is still up. Falls back to ACTIONS_RUNNER_HOOK_JOB_COMPLETED; a failure fails the job.
 }
 
 // Cache represents the configuration for caching.
@@ -66,6 +74,7 @@ type Cache struct {
 	ExternalSecret     string `yaml:"external_secret"`      // ExternalSecret is a shared secret between this runner and an external gitea-runner cache-server, enabling per-job ACTIONS_RUNTIME_TOKEN authentication and repo scoping over the network. Required whenever ExternalServer is set; ExternalSecretFile is the alternative way to provide it.
 	ExternalSecretFile string `yaml:"external_secret_file"` // ExternalSecretFile is the path to a file holding the ExternalSecret value, so the secret can be mounted instead of stored in the config file. LoadDefault reads it into ExternalSecret; setting both is an error.
 	OfflineMode        bool   `yaml:"offline_mode"`         // OfflineMode reuses a cached action without fetching from the remote; a moved tag or branch stays at the cached commit until the cache entry is removed.
+	V2                 *bool  `yaml:"v2"`                   // V2 serves the actions cache service v2 API to jobs, used by actions/cache@v4.2 and later, and edits the action bundles that would otherwise refuse it. Unset means enabled.
 }
 
 // Container represents the configuration for the container.
@@ -78,7 +87,7 @@ type Container struct {
 	WorkdirParent        string                        `yaml:"workdir_parent"`         // WorkdirParent specifies the parent directory for the container's working directory.
 	ValidVolumes         []string                      `yaml:"valid_volumes"`          // ValidVolumes specifies the volumes (including bind mounts) can be mounted to containers.
 	DockerHost           string                        `yaml:"docker_host"`            // DockerHost specifies the Docker host. It overrides the value specified in environment variable DOCKER_HOST.
-	ForcePull            bool                          `yaml:"force_pull"`             // Pull docker image(s) even if already present
+	ForcePull            bool                          `yaml:"force_pull"`             // Pull docker image(s) even if already present, except digest-pinned ones. A pull that fails while a local copy exists is a warning, not a job failure.
 	ForceRebuild         bool                          `yaml:"force_rebuild"`          // Rebuild docker image(s) even if already present
 	RequireDocker        bool                          `yaml:"require_docker"`         // Always require a reachable docker daemon, even if not required by runner
 	DockerTimeout        time.Duration                 `yaml:"docker_timeout"`         // Timeout to wait for the docker daemon to be reachable, if docker is required by require_docker or runner
@@ -136,6 +145,7 @@ func LoadDefault(file string) (*Config, error) {
 		if err := yaml.Unmarshal(content, cfg); err != nil {
 			return nil, fmt.Errorf("parse config file %q: %w", file, err)
 		}
+		warnUnknownKeys(file, content)
 		definedRunnerKeys, err = definedRunnerConfigKeys(content)
 		if err != nil {
 			return nil, fmt.Errorf("parse config file %q for defaults metadata: %w", file, err)
@@ -281,6 +291,21 @@ func LoadDefault(file string) (*Config, error) {
 	return cfg, nil
 }
 
+// warnUnknownKeys reports keys the config does not define, which are otherwise ignored
+// without a trace. It only warns, so a config carrying keys from another runner version
+// still loads.
+func warnUnknownKeys(file string, content []byte) {
+	decoder := yaml.NewDecoder(bytes.NewReader(content))
+	decoder.KnownFields(true)
+
+	var typeErr *yaml.TypeError
+	if err := decoder.Decode(&Config{}); errors.As(err, &typeErr) {
+		for _, message := range typeErr.Errors {
+			log.Warnf("config file %q: %s, it will be ignored", file, message)
+		}
+	}
+}
+
 func definedRunnerConfigKeys(content []byte) (map[string]bool, error) {
 	var root yaml.Node
 	if err := yaml.Unmarshal(content, &root); err != nil {

internal/pkg/config/config_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -139,9 +140,6 @@ runner:
 	assert.Equal(t, -1*time.Second, cfg.Runner.IdleCleanupInterval)
 }
 
-// TestLoadDefault_MalformedYAMLReturnsParseError pins the error surfaced for
-// invalid YAML to the canonical "parse config file" message rather than the
-// "for defaults metadata" variant — i.e. the main yaml.Unmarshal runs first.
 func TestLoadDefault_LoadsPostTaskScript(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "config.yaml")
@@ -170,6 +168,25 @@ runner:
 	assert.Equal(t, 5*time.Minute, cfg.Runner.PostTaskScriptTimeout)
 }
 
+func TestLoadDefault_LoadsJobHooks(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	require.NoError(t, os.WriteFile(path, []byte(`
+runner:
+  hooks:
+    job_started: /hooks/started.sh
+    job_completed: /hooks/completed.sh
+`), 0o600))
+
+	cfg, err := LoadDefault(path)
+	require.NoError(t, err)
+	assert.Equal(t, "/hooks/started.sh", cfg.Runner.Hooks.JobStarted)
+	assert.Equal(t, "/hooks/completed.sh", cfg.Runner.Hooks.JobCompleted)
+}
+
+// TestLoadDefault_MalformedYAMLReturnsParseError pins the error surfaced for
+// invalid YAML to the canonical "parse config file" message rather than the
+// "for defaults metadata" variant — i.e. the main yaml.Unmarshal runs first.
 func TestLoadDefault_MalformedYAMLReturnsParseError(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "config.yaml")
@@ -181,6 +198,21 @@ func TestLoadDefault_MalformedYAMLReturnsParseError(t *testing.T) {
 	assert.NotContains(t, err.Error(), "defaults metadata")
 }
 
+func TestLoadDefault_WarnsOnUnknownKeysButStillLoads(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	require.NoError(t, os.WriteFile(path, []byte("container:\n  volumes:\n    - /host:/ctr\n  privileged: true\n"), 0o600))
+
+	hook := test.NewGlobal()
+	defer hook.Reset()
+
+	cfg, err := LoadDefault(path)
+	require.NoError(t, err)
+	assert.True(t, cfg.Container.Privileged)
+	require.Len(t, hook.Entries, 1)
+	assert.Contains(t, hook.LastEntry().Message, "field volumes not found")
+}
+
 func TestContainerNetworkCreateOptions(t *testing.T) {
 	// Verify that the enable_ipv4/enable_ipv6 YAML keys unmarshal into the *bool fields,
 	// distinguishing an explicit true/false from an omitted key (nil). A nil here is
@@ -315,3 +347,13 @@ cache:
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "contains no secret")
 }
+
+// The shipped example must parse, and every key in it must be one the config knows.
+func TestLoadDefault_ExampleConfigParses(t *testing.T) {
+	hook := test.NewGlobal()
+	defer hook.Reset()
+
+	_, err := LoadDefault("config.example.yaml")
+	require.NoError(t, err)
+	assert.Empty(t, hook.AllEntries())
+}

internal/pkg/lock/keyed.go

@@ -0,0 +1,38 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package lock
+
+import "sync"
+
+// Keyed serializes the work done under one key while letting different keys run in
+// parallel. Its zero value is ready to use, and it keeps one mutex per key it has seen.
+type Keyed[K comparable] struct {
+	mu      sync.Mutex
+	mutexes map[K]*sync.Mutex
+}
+
+// Lock locks the mutex for key and returns its unlock function.
+func (kl *Keyed[K]) Lock(key K) func() {
+	kl.mu.Lock()
+	if kl.mutexes == nil {
+		kl.mutexes = map[K]*sync.Mutex{}
+	}
+	lock := kl.mutexes[key]
+	if lock == nil {
+		lock = &sync.Mutex{}
+		kl.mutexes[key] = lock
+	}
+	kl.mu.Unlock()
+
+	lock.Lock()
+	return lock.Unlock
+}
+
+// Delete drops the mutex for key. Holders of it keep working, they just no longer share it
+// with a later Lock of the same key.
+func (kl *Keyed[K]) Delete(key K) {
+	kl.mu.Lock()
+	delete(kl.mutexes, key)
+	kl.mu.Unlock()
+}

internal/pkg/lock/lock.go

@@ -0,0 +1,35 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+// Package lock provides a cross-platform, non-blocking advisory file lock used
+// to ensure a single runner process owns a given runner file.
+package lock
+
+import (
+	"errors"
+	"fmt"
+)
+
+// ErrLocked is returned by TryLock when another process already holds the lock.
+var ErrLocked = errors.New("runner file is already locked by another process")
+
+// TryLock takes a non-blocking exclusive advisory lock tied to runnerFile. The
+// lock is placed on a sibling "<runnerFile>.lock" so it never interferes with
+// in-place rewrites of the runner file itself.
+//
+// It returns a release function that drops the lock. The operating system also
+// releases the lock automatically when the process exits, including on a hard
+// kill, so a crashed runner never leaves a stale lock behind.
+//
+// If another process already holds the lock, it returns ErrLocked.
+func TryLock(runnerFile string) (func() error, error) {
+	path := runnerFile + ".lock"
+	release, err := tryLock(path)
+	if errors.Is(err, ErrLocked) {
+		return nil, ErrLocked
+	}
+	if err != nil {
+		return nil, fmt.Errorf("lock %q: %w", path, err)
+	}
+	return release, nil
+}

internal/pkg/lock/lock_plan9.go

@@ -0,0 +1,11 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build plan9
+
+package lock
+
+// tryLock is a best-effort no-op on plan9, which lacks flock/LockFileEx.
+func tryLock(_ string) (func() error, error) {
+	return func() error { return nil }, nil
+}

internal/pkg/lock/lock_test.go

@@ -0,0 +1,54 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !plan9
+
+package lock
+
+import (
+	"errors"
+	"path/filepath"
+	"testing"
+)
+
+func TestTryLock(t *testing.T) {
+	runnerFile := filepath.Join(t.TempDir(), ".runner")
+
+	release, err := TryLock(runnerFile)
+	if err != nil {
+		t.Fatalf("first TryLock failed: %v", err)
+	}
+
+	// A second lock on the same file must be refused while the first is held.
+	if _, err := TryLock(runnerFile); !errors.Is(err, ErrLocked) {
+		t.Fatalf("second TryLock: want ErrLocked, got %v", err)
+	}
+
+	if err := release(); err != nil {
+		t.Fatalf("release failed: %v", err)
+	}
+
+	// After release the lock is available again.
+	release2, err := TryLock(runnerFile)
+	if err != nil {
+		t.Fatalf("TryLock after release failed: %v", err)
+	}
+	if err := release2(); err != nil {
+		t.Fatalf("second release failed: %v", err)
+	}
+}
+
+// TestTryLockUncreatable ensures a lock file that cannot be created reports a
+// non-ErrLocked error, so callers can tell "already locked by another process"
+// apart from "couldn't lock" and degrade gracefully (e.g. a read-only mount).
+func TestTryLockUncreatable(t *testing.T) {
+	runnerFile := filepath.Join(t.TempDir(), "missing-dir", ".runner")
+
+	_, err := TryLock(runnerFile)
+	if err == nil {
+		t.Fatal("TryLock on an uncreatable lock file: want error, got nil")
+	}
+	if errors.Is(err, ErrLocked) {
+		t.Fatal("TryLock on an uncreatable lock file: want non-ErrLocked error, got ErrLocked")
+	}
+}

internal/pkg/lock/lock_unix.go

@@ -0,0 +1,35 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !windows && !plan9
+
+package lock
+
+import (
+	"errors"
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+// tryLock opens (creating if needed) the lock file and takes a non-blocking
+// exclusive flock on it. The returned release closes the file, which drops the
+// lock; the kernel also drops it when the process exits.
+func tryLock(path string) (func() error, error) {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return nil, err
+	}
+	if err := unix.Flock(int(f.Fd()), unix.LOCK_EX|unix.LOCK_NB); err != nil {
+		_ = f.Close()
+		if errors.Is(err, unix.EWOULDBLOCK) || errors.Is(err, unix.EAGAIN) {
+			return nil, ErrLocked
+		}
+		return nil, err
+	}
+	return func() error {
+		// Best-effort unlock; closing the fd releases the lock regardless.
+		_ = unix.Flock(int(f.Fd()), unix.LOCK_UN)
+		return f.Close()
+	}, nil
+}

internal/pkg/lock/lock_windows.go

@@ -0,0 +1,36 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build windows
+
+package lock
+
+import (
+	"errors"
+	"os"
+
+	"golang.org/x/sys/windows"
+)
+
+// tryLock opens (creating if needed) the lock file and takes a non-blocking
+// exclusive lock on it via LockFileEx. The returned release closes the file,
+// which drops the lock; Windows also drops it when the process exits.
+func tryLock(path string) (func() error, error) {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return nil, err
+	}
+	handle := windows.Handle(f.Fd())
+	overlapped := new(windows.Overlapped)
+	if err := windows.LockFileEx(handle, windows.LOCKFILE_EXCLUSIVE_LOCK|windows.LOCKFILE_FAIL_IMMEDIATELY, 0, 1, 0, overlapped); err != nil {
+		_ = f.Close()
+		if errors.Is(err, windows.ERROR_LOCK_VIOLATION) {
+			return nil, ErrLocked
+		}
+		return nil, err
+	}
+	return func() error {
+		_ = windows.UnlockFileEx(handle, 0, 1, 0, overlapped)
+		return f.Close()
+	}, nil
+}

internal/pkg/report/reporter.go

@@ -32,6 +32,12 @@ const (
 	maxOutputValueLen = 1024 * 1024 // 1 MiB
 )
 
+// jobOutput is a job output on its way to the server, sent once the server has acknowledged it.
+type jobOutput struct {
+	value string
+	sent  bool
+}
+
 type Reporter struct {
 	ctx    context.Context
 	cancel context.CancelFunc
@@ -53,7 +59,8 @@ type Reporter struct {
 	state             *runnerv1.TaskState
 	stateChanged      bool
 	stateMu           sync.RWMutex
-	outputs           sync.Map
+	outputsMu         sync.Mutex
+	outputs           map[string]jobOutput
 	daemon            chan struct{}
 	heartbeatStop     chan struct{}
 	heartbeatStopOnce sync.Once
@@ -79,8 +86,13 @@ type Reporter struct {
 	stopCommandEndToken string
 }
 
-func NewReporter(ctx context.Context, cancel context.CancelFunc, client client.Client, task *runnerv1.Task, cfg *config.Config) *Reporter {
+// extraMasks are values known before the job starts that are not among its secrets, such as
+// the password in the runner's proxy URL.
+func NewReporter(ctx context.Context, cancel context.CancelFunc, client client.Client, task *runnerv1.Task, cfg *config.Config, extraMasks ...string) *Reporter {
 	var oldnew []string
+	for _, v := range extraMasks {
+		oldnew = runner.AppendSecretMasker(oldnew, v)
+	}
 	if v := task.Context.Fields["token"].GetStringValue(); v != "" {
 		oldnew = runner.AppendSecretMasker(oldnew, v)
 	}
@@ -394,7 +406,12 @@ func (r *Reporter) logf(format string, a ...any) {
 func (r *Reporter) SetOutputs(outputs map[string]string) {
 	r.stateMu.Lock()
 	defer r.stateMu.Unlock()
+	r.outputsMu.Lock()
+	defer r.outputsMu.Unlock()
 
+	if r.outputs == nil {
+		r.outputs = map[string]jobOutput{}
+	}
 	for k, v := range outputs {
 		if l := len(k); l > maxOutputKeyLen {
 			log.Warnf("ignore output %q because the key is too long: %d > %d", k, l, maxOutputKeyLen)
@@ -406,10 +423,9 @@ func (r *Reporter) SetOutputs(outputs map[string]string) {
 			r.logf("ignore output %q because the value is too long: %d > %d", k, l, maxOutputValueLen)
 			continue
 		}
-		if _, ok := r.outputs.Load(k); ok {
-			continue
+		if _, ok := r.outputs[k]; !ok {
+			r.outputs[k] = jobOutput{value: v}
 		}
-		r.outputs.Store(k, v)
 	}
 }
 
@@ -574,14 +590,14 @@ func (r *Reporter) ReportState(reportResult bool) error {
 	r.clientM.Lock()
 	defer r.clientM.Unlock()
 
-	// Build the outputs map first (single Range pass instead of two).
 	outputs := make(map[string]string)
-	r.outputs.Range(func(k, v any) bool {
-		if val, ok := v.(string); ok {
-			outputs[k.(string)] = val
+	r.outputsMu.Lock()
+	for key, out := range r.outputs {
+		if !out.sent {
+			outputs[key] = out.value
 		}
-		return true
-	})
+	}
+	r.outputsMu.Unlock()
 
 	// Consume stateChanged atomically with the snapshot; restored on error
 	// below so a concurrent Fire() during UpdateTask isn't silently lost.
@@ -594,7 +610,8 @@ func (r *Reporter) ReportState(reportResult bool) error {
 		r.stateMu.Unlock()
 		return nil
 	}
-	state := proto.Clone(r.state).(*runnerv1.TaskState)
+	state := &runnerv1.TaskState{}
+	proto.Merge(state, r.state)
 	r.stateChanged = false
 	r.stateMu.Unlock()
 
@@ -622,21 +639,23 @@ func (r *Reporter) ReportState(reportResult bool) error {
 	metrics.ReportStateTotal.WithLabelValues(metrics.LabelResultSuccess).Inc()
 	r.lastReportedAtNanos.Store(time.Now().UnixNano())
 
+	var noSent []string
+	r.outputsMu.Lock()
 	for _, k := range resp.Msg.SentOutputs {
-		r.outputs.Store(k, struct{}{})
+		if _, ok := r.outputs[k]; ok {
+			r.outputs[k] = jobOutput{sent: true}
+		}
 	}
+	for key, out := range r.outputs {
+		if !out.sent {
+			noSent = append(noSent, key)
+		}
+	}
+	r.outputsMu.Unlock()
 
 	if resp.Msg.State != nil && resp.Msg.State.Result == runnerv1.Result_RESULT_CANCELLED {
 		r.cancel()
 	}
-
-	var noSent []string
-	r.outputs.Range(func(k, v any) bool {
-		if _, ok := v.(string); ok {
-			noSent = append(noSent, k.(string))
-		}
-		return true
-	})
 	if len(noSent) > 0 {
 		return fmt.Errorf("there are still outputs that have not been sent: %v", noSent)
 	}

internal/pkg/report/reporter_test.go

@@ -5,13 +5,18 @@ package report
 
 import (
 	"context"
+	"encoding/base64"
 	"errors"
 	"fmt"
+	"maps"
+	"net/url"
+	"slices"
 	"strings"
 	"sync/atomic"
 	"testing"
 	"time"
 
+	"gitea.com/gitea/runner/act/runner"
 	"gitea.com/gitea/runner/internal/pkg/client/mocks"
 	"gitea.com/gitea/runner/internal/pkg/config"
 
@@ -1011,33 +1016,59 @@ func TestReporter_SetOutputs(t *testing.T) {
 	r := &Reporter{state: &runnerv1.TaskState{}}
 
 	r.SetOutputs(map[string]string{"foo": "bar"})
-	got, ok := r.outputs.Load("foo")
+	got, ok := r.outputs["foo"]
 	require.True(t, ok)
-	assert.Equal(t, "bar", got)
+	assert.Equal(t, "bar", got.value)
 
 	// first value wins: a later write to the same key is ignored
 	r.SetOutputs(map[string]string{"foo": "baz"})
-	got, _ = r.outputs.Load("foo")
-	assert.Equal(t, "bar", got)
+	assert.Equal(t, "bar", r.outputs["foo"].value)
 
 	// keys longer than maxOutputKeyLen are dropped
 	longKey := strings.Repeat("k", maxOutputKeyLen+1)
 	r.SetOutputs(map[string]string{longKey: "v"})
-	_, ok = r.outputs.Load(longKey)
+	_, ok = r.outputs[longKey]
 	assert.False(t, ok)
 
 	// values longer than maxOutputValueLen are dropped
 	longValue := strings.Repeat("v", maxOutputValueLen+1)
 	r.SetOutputs(map[string]string{"big": longValue})
-	_, ok = r.outputs.Load("big")
+	_, ok = r.outputs["big"]
 	assert.False(t, ok)
 
 	// a value at exactly the limit is still stored
 	maxValue := strings.Repeat("v", maxOutputValueLen)
 	r.SetOutputs(map[string]string{"atlimit": maxValue})
-	got, ok = r.outputs.Load("atlimit")
+	got, ok = r.outputs["atlimit"]
 	require.True(t, ok)
-	assert.Len(t, got, maxOutputValueLen)
+	assert.Len(t, got.value, maxOutputValueLen)
+}
+
+// An output the server acknowledged is not reported again.
+func TestReporter_OutputsSentOnce(t *testing.T) {
+	client := mocks.NewClient(t)
+	var reported []map[string]string
+	client.On("UpdateTask", mock.Anything, mock.Anything).Return(
+		func(_ context.Context, req *connect_go.Request[runnerv1.UpdateTaskRequest]) (*connect_go.Response[runnerv1.UpdateTaskResponse], error) {
+			reported = append(reported, req.Msg.Outputs)
+			return connect_go.NewResponse(&runnerv1.UpdateTaskResponse{SentOutputs: slices.Collect(maps.Keys(req.Msg.Outputs))}), nil
+		})
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	taskCtx, err := structpb.NewStruct(map[string]any{})
+	require.NoError(t, err)
+	cfg, _ := config.LoadDefault("")
+	r := NewReporter(ctx, cancel, client, &runnerv1.Task{Context: taskCtx}, cfg)
+
+	r.SetOutputs(map[string]string{"foo": "bar"})
+	require.NoError(t, r.ReportState(false))
+	assert.True(t, r.outputs["foo"].sent)
+
+	require.NoError(t, r.ReportState(true))
+	require.Len(t, reported, 2)
+	assert.Equal(t, map[string]string{"foo": "bar"}, reported[0])
+	assert.Empty(t, reported[1])
 }
 
 func TestReporter_EffectiveCloseTimeout(t *testing.T) {
@@ -1068,3 +1099,24 @@ func TestReporter_ParseResult(t *testing.T) {
 		})
 	}
 }
+
+// A secret leaked in an encoded form — the shape it takes once an action puts it in a
+// JSON body, a URL or a base64 payload — must be masked in the reported log as well.
+func TestReporter_masksEncodedSecrets(t *testing.T) {
+	secret := `p@ss w"rd/1`
+	r := &Reporter{logReplacer: strings.NewReplacer()}
+	r.oldnew = runner.AppendSecretMasker(r.oldnew, secret)
+	r.logReplacer = strings.NewReplacer(r.oldnew...)
+
+	for _, line := range []string{
+		"token: " + secret,
+		"basic " + base64.StdEncoding.EncodeToString([]byte(secret)),
+		"https://example.com/?token=" + url.QueryEscape(secret),
+	} {
+		row := r.parseLogRow(&log.Entry{Message: line})
+		require.NotNil(t, row)
+		assert.Contains(t, row.Content, "***")
+		assert.NotContains(t, row.Content, secret)
+		assert.NotContains(t, row.Content, base64.StdEncoding.EncodeToString([]byte(secret)))
+	}
+}