fix: align Docker actions, job env and host mode with GitHub (#1268)

- Docker actions evaluate `runs.args` and `runs.env` with their own `inputs`, so a same-named `workflow_dispatch` input no longer replaces the step's `with:` value
- Dockerfile action images are tagged per step and job and removed afterwards, so changed Dockerfiles rebuild and concurrent jobs never share an image
- Workflow and job `env` are evaluated before job and service container credentials and service `env` use them
- Docker actions in host jobs get the host workspace and file-command directory mounted, and no longer inherit the runner's own `PATH`
- Cache server address detection accepts a single interface address

Fixes: https://gitea.com/gitea/runner/issues/390
Fixes: https://gitea.com/gitea/runner/issues/406
Fixes: https://gitea.com/gitea/runner/issues/578
Related: https://gitea.com/gitea/runner/issues/64
Reviewed-on: https://gitea.com/gitea/runner/pulls/1268
Reviewed-by: bircni <[email protected]>
Co-authored-by: silverwind <[email protected]>

.gitea/workflows/release-nightly.yml

@@ -74,10 +74,10 @@ jobs:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to DockerHub
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
@@ -94,7 +94,7 @@ jobs:
           echo REPO_VERSION=$(git describe --tags --always | sed 's/-/+/' | sed 's/^v//') >> $GITHUB_OUTPUT
 
       - name: Build and push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: ./Dockerfile

.gitea/workflows/release-tag.yml

@@ -77,10 +77,10 @@ jobs:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to DockerHub
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
@@ -103,7 +103,7 @@ jobs:
             suffix=${{ matrix.variant.tag_suffix }},onlatest=true
 
       - name: Build and push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: ./Dockerfile

.gitea/workflows/test.yml

@@ -30,8 +30,8 @@ jobs:
       # daemon retains them between runs, so this is usually a fast manifest re-check.
       - name: pre-pull test images
         env:
-          TEST_JOB_IMAGE: node:24-bookworm-slim@sha256:3638d9a6fe4030bd716be989438248074489337ba3275657f93595428be4fc03 # renovate: datasource=docker
-          TEST_SERVICE_IMAGE: nginx:alpine@sha256:db35bfc6b2951e7f8a72db5db120288c127ffaeeb4a6d4b95a26fead017d5913 # renovate: datasource=docker
+          TEST_JOB_IMAGE: node:24-bookworm-slim@sha256:0e0ff40c39bc087845bfb27465a0df4ea419520094bc35842ff83dd8cbe6f9b6 # renovate: datasource=docker
+          TEST_SERVICE_IMAGE: nginx:alpine@sha256:df221db836e1754089190208cee7eeda94f233197056426eda74a43ab1abeac2 # renovate: datasource=docker
         run: |
           for image in "$TEST_JOB_IMAGE" "$TEST_SERVICE_IMAGE"; do
             for attempt in 1 2 3; do
@@ -53,6 +53,8 @@ jobs:
       # after `make test` so the images it needs are already present on the host daemon.
       - name: test against dind image
         run: make test-dind
+      - name: test against podman
+        run: make test-dind TARGET=podman
       - name: coverage report
         run: |
           make coverage-report

CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

DEVELOPMENT.md

@@ -31,6 +31,11 @@ depending on the prefix:
 - Command *properties* also escape `%3A` and `%2C`, which the UI never decodes, so the reporter
   decodes exactly those two when folding a location into an annotation.
 
+## Built-in actions
+
+Each lives in `internal/pkg/action/<name>` and is registered in `builtinActions` in
+`act/runner/step_action_builtin.go`.
+
 ## End-to-end compatibility tests
 
 `make test-e2e` runs the runner against `E2E_GITEA_IMAGE`. It defaults to the nightly image.

Dockerfile

@@ -32,6 +32,8 @@ COPY scripts/s6 /etc/s6
 
 VOLUME /data
 
+ENV TINI_SUBREAPER=1
+
 ENTRYPOINT ["s6-svscan","/etc/s6"]
 
 ### DIND-ROOTLESS VARIANT
@@ -56,6 +58,7 @@ VOLUME /data
 RUN mkdir -p /data && chown -R rootless:rootless /etc/s6 /data
 
 ENV DOCKER_HOST=unix:///run/user/1000/docker.sock
+ENV TINI_SUBREAPER=1
 
 USER rootless
 ENTRYPOINT ["s6-svscan","/etc/s6"]

Makefile

@@ -6,7 +6,13 @@ SHASUM ?= shasum -a 256
 HAS_GO = $(shell hash $(GO) > /dev/null 2>&1 && echo "GO" || echo "NOGO" )
 XGO_PACKAGE ?= src.techknowlogick.com/[email protected] # renovate: datasource=go
 XGO_VERSION := go-1.27.x
-GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/[email protected]6 # renovate: datasource=go
+GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/[email protected]7 # renovate: datasource=go
+
+PODMAN_TEST_IMAGE ?= quay.io/containers/podman:v5.8.4-immutable@sha256:90405e3c6a86f33c5a6f8dbdfa8e02a98143a8ba4337b84bdaec5336d2ef008a # renovate: datasource=docker
+E2E_JOB_IMAGE ?= node:24-bookworm@sha256:64af3819f9275802414d7cdc38c27e9d82bd564dec4d4da87d008255d36c63b4 # renovate: datasource=docker
+SERVICE_IMAGE ?= nginx:1.31.4-alpine@sha256:db35bfc6b2951e7f8a72db5db120288c127ffaeeb4a6d4b95a26fead017d5913 # renovate: datasource=docker
+E2E_GITEA_IMAGE ?= gitea/gitea:main-nightly
+E2E_K3S_IMAGE ?= rancher/k3s:v1.36.4-k3s1@sha256:edad48e12bf81c3a09ac1c05c0c0ffaaa22145980b989d6fae84543a76b83657 # renovate: datasource=docker
 
 LINUX_ARCHS ?= linux/amd64,linux/arm64
 DARWIN_ARCHS ?= darwin-12/amd64,darwin-12/arm64
@@ -18,8 +24,8 @@ 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/[email protected].1 # renovate: datasource=go
-GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.7.0 # renovate: datasource=go
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/[email protected].2 # renovate: datasource=go
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.8.0 # renovate: datasource=go
 
 GOTEST_FLAGS ?= -race -timeout 20m -parallel 8
 
@@ -96,13 +102,8 @@ go-check:
 	fi
 
 .PHONY: fmt-check
-fmt-check: fmt
-	@diff=$$(git diff --color=always -- '*.go'); \
-	if [ -n "$$diff" ]; then \
-		echo "Please run 'make fmt' and commit the result:"; \
-		printf "%s" "$${diff}"; \
-		exit 1; \
-	fi
+fmt-check: ## check the Go code formatting
+	$(GO) run $(GOLANGCI_LINT_PACKAGE) fmt --diff-colored
 
 .PHONY: deps-tools
 deps-tools: ## install tool dependencies
@@ -149,13 +150,8 @@ tidy: ## run go mod tidy
 	fi
 
 .PHONY: tidy-check
-tidy-check: tidy
-	@diff=$$(git diff --color=always -- go.mod go.sum); \
-	if [ -n "$$diff" ]; then \
-		echo "Please run 'make tidy' and commit the result:"; \
-		printf "%s" "$${diff}"; \
-		exit 1; \
-	fi
+tidy-check: ## check that go.mod and go.sum are tidy
+	$(GO) mod tidy -diff
 
 .PHONY: test
 test: ## test everything (integration tests self-skip without docker/network)
@@ -168,17 +164,14 @@ coverage-report: ## turn coverage.txt from `make test` into .tmp/coverage.md
 	@echo "Wrote .tmp/coverage.md"
 
 .PHONY: test-dind
-test-dind: ## run the daemon-facing tests against the built dind image (TARGET=dind|dind-rootless)
-	@./scripts/test-dind.sh $(TARGET)
+test-dind: ## run the daemon-facing tests against the built dind image or podman (TARGET=dind|dind-rootless|podman)
+	@PODMAN_TEST_IMAGE=$(PODMAN_TEST_IMAGE) ./scripts/test-dind.sh $(TARGET)
 
-E2E_JOB_IMAGE ?= node:24-bookworm@sha256:934240a162082fd8b8a2f90cd5114446443f1eba1c5378f6687167ca405e6584 # renovate: datasource=docker
-SERVICE_IMAGE ?= nginx:1.31.4-alpine@sha256:db35bfc6b2951e7f8a72db5db120288c127ffaeeb4a6d4b95a26fead017d5913 # renovate: datasource=docker
-E2E_GITEA_IMAGE ?= gitea/gitea:main-nightly
 E2E_CONCURRENCY ?= 8
 
 .PHONY: test-e2e
 test-e2e: ## run Gitea compatibility tests against E2E_GITEA_IMAGE
-	@E2E_CONCURRENCY=$(E2E_CONCURRENCY) E2E_GITEA_IMAGE=$(E2E_GITEA_IMAGE) E2E_JOB_IMAGE=$(E2E_JOB_IMAGE) GO=$(GO) SERVICE_IMAGE=$(SERVICE_IMAGE) ./tools/test-e2e.sh
+	@E2E_CONCURRENCY=$(E2E_CONCURRENCY) E2E_GITEA_IMAGE=$(E2E_GITEA_IMAGE) E2E_K3S_IMAGE=$(E2E_K3S_IMAGE) E2E_JOB_IMAGE=$(E2E_JOB_IMAGE) GO=$(GO) SERVICE_IMAGE=$(SERVICE_IMAGE) ./tools/test-e2e.sh
 
 .PHONY: install
 install: $(GOFILES) ## install the runner binary via `go install`

README.md

@@ -79,53 +79,24 @@ If the registry succeed, it will run immediately. Next time, you could run the r
 
 ### Run with docker
 
-```bash
-docker run -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> -v /var/run/docker.sock:/var/run/docker.sock --name my_runner gitea/runner:nightly
-```
-
-Mount a volume on `/data` if you want the registration file and optional config to survive container recreation (see [scripts/run.sh](scripts/run.sh)).
-
-> **`/data` does not hold the image cache.** It is the runner's working directory and contains only the `.runner` registration file and, optionally, your config file. Images pulled for jobs live in the *Docker daemon's* data root, which for the `dind` flavours is inside the container (`/var/lib/docker`, or `/home/rootless/.local/share/docker` for `dind-rootless`). To keep the image cache across restarts, give that path its own volume as well — otherwise every new container re-pulls the job images. With the `basic` flavour the images live on whichever daemon you point the runner at, so there is nothing extra to persist.
-
-### Image flavours
-
-The image is published in three flavours, all built from the single multi-stage [Dockerfile](Dockerfile) in this repository. They differ only in how a Docker daemon is made available to the jobs the runner executes; the `gitea-runner` binary inside them is identical.
-
-| Tag | Build target | Base image | Docker daemon | Process supervisor | Runs as |
-| --- | --- | --- | --- | --- | --- |
-| `latest` (and `<version>`) | `basic` | `alpine` | none — uses an external daemon you provide | [`tini`](https://github.com/krallin/tini) | `root` |
-| `latest-dind` | `dind` | `docker:dind` | bundled, started inside the container | [`s6`](https://skarnet.org/software/s6/) | `root` (privileged) |
-| `latest-dind-rootless` | `dind-rootless` | `docker:dind-rootless` | bundled, started rootless inside the container | [`s6`](https://skarnet.org/software/s6/) | `rootless` (UID 1000) |
-
-#### `latest` — basic
-
-The default flavour ships only the runner on a minimal Alpine base. It contains **no Docker daemon of its own**: jobs that use `docker://` images need a daemon supplied from outside the container, typically by bind-mounting the host's socket:
-
-```bash
-docker run -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> \
-  -v /var/run/docker.sock:/var/run/docker.sock --name my_runner gitea/runner:latest
-```
-
-`tini` is the entrypoint (it reaps zombie processes), and it just runs [`scripts/run.sh`](scripts/run.sh), which registers the runner on first start and then execs `gitea-runner daemon`. This flavour does not need `--privileged`. The trade-off is that jobs share the host's daemon, so they can see other containers and images on that daemon.
-
-#### `latest-dind` — Docker-in-Docker
-
-This flavour is based on the official `docker:dind` image and bundles its own Docker daemon, so it needs no external socket — only the `--privileged` flag that Docker-in-Docker requires:
+The recommended Docker-in-Docker image runs its own Docker daemon for jobs. Jobs never get the host's Docker socket, which is equivalent to root access on the host.
 
 ```bash
 docker run --privileged -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> \
-  --name my_runner gitea/runner:latest-dind
+  -v "$PWD/data:/data" -v runner-docker:/var/lib/docker --name my_runner gitea/runner:nightly-dind
 ```
 
-Two processes have to run side by side here (the Docker daemon and the runner), so the entrypoint is the [`s6`](https://skarnet.org/software/s6/) supervision tree under [`scripts/s6`](scripts/s6) instead of `tini`. `s6` starts `dockerd`, and the runner service waits for the daemon to come up (`s6-svwait`) before launching [`run.sh`](scripts/run.sh). Each container has a private daemon isolated from the host's, at the cost of running privileged.
+The volumes keep the runner's registration and the job image cache across container recreation.
 
-#### `latest-dind-rootless` — rootless Docker-in-Docker
+### Image flavours
 
-Same idea as `dind`, but built on `docker:dind-rootless` so the bundled daemon and the runner run as an unprivileged user (`rootless`, UID 1000) rather than `root`. `DOCKER_HOST` is preset to `unix:///run/user/1000/docker.sock` so the runner talks to the rootless daemon. This reduces the blast radius compared to the privileged `dind` flavour, but rootless Docker carries the usual rootless limitations (networking, cgroups, storage drivers, and some operations that need additional host configuration such as `/etc/subuid` / `/etc/subgid` mappings and unprivileged user-namespace support).
+| Tag | Docker daemon for jobs |
+| --- | --- |
+| `latest-dind` (recommended) | Bundled, needs `--privileged`. |
+| `latest-dind-rootless` | Bundled, runs as a non-root user (UID 1000) for stronger isolation. Needs `--privileged` and [rootless Docker](https://docs.docker.com/engine/security/rootless/) support on the host. Keeps its image cache in `/home/rootless/.local/share/docker`. |
+| `latest` | None. Mount the host's socket with `-v /var/run/docker.sock:/var/run/docker.sock`, or set `DOCKER_HOST`. |
 
-> **The UID is fixed at 1000.** It comes from the `rootless` user baked into the upstream `docker:dind-rootless` base image, and the bundled daemon always listens on `/run/user/1000/docker.sock` inside the container, so running this flavour as a different user (`--user 1001`) does not work. If you need the runner to talk to a *host* rootless daemon that runs under some other UID, use the `basic` flavour instead and bind-mount that daemon's socket (see [examples/vm/rootless-docker.md](examples/vm/rootless-docker.md)); pointing `DOCKER_HOST` at a host socket from inside `dind-rootless` will not work. Changing the UID otherwise means rebuilding the image from a base with a different `rootless` user.
-
-> **Note on Podman:** these images target the Docker daemon. The bundled `dind`/`dind-rootless` daemons are `dockerd`, not Podman, and the `basic` flavour expects a Docker-compatible socket. Running them under rootless Podman is not a supported configuration, though pointing the `basic` flavour at a Podman socket that emulates the Docker API may work for some workloads.
+Versioned and `nightly` tags carry the same suffixes, for example `nightly-dind`. The images target Docker, not Podman.
 
 ### Configuration
 
@@ -201,10 +172,10 @@ A label is written as:
 | Part | Meaning |
 | --- | --- |
 | `name` | The name a workflow refers to in `runs-on`, e.g. `ubuntu-latest`. |
-| `schema` | Either `docker` or `host`. Defaults to `host` when omitted. |
-| `args` | Only used by the `docker` schema: the image to run the job in. |
+| `schema` | `docker`, `kubernetes` or `host`. Defaults to `host` when omitted. |
+| `args` | Only used by the `docker` and `kubernetes` schemas: the image to run the job in. |
 
-Two schemas are supported:
+Three schemas are supported:
 
 - **`docker://<image>`** — the job runs inside a container created from `<image>`:
 
@@ -212,6 +183,12 @@ Two schemas are supported:
   ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest
   ```
 
+- **`kubernetes://<image>`** — the job runs as a Kubernetes pod created from `<image>`, see **[docs/kubernetes.md](docs/kubernetes.md)**:
+
+  ```text
+  ubuntu-latest:kubernetes://docker.gitea.com/runner-images:ubuntu-latest
+  ```
+
 - **`host`** — the job's steps run directly on the machine the runner is on, using the tools installed there:
 
   ```text
@@ -226,9 +203,9 @@ ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,macos:host
 
 a workflow with `runs-on: ubuntu-latest` is executed in the `runner-images:ubuntu-latest` container, and one with `runs-on: macos` is executed directly on the host.
 
-Names may themselves contain a colon (for example `pool:e57e18d4-10d4-406f-93bf-60f127221bdd`); only `host` and `docker` are treated as schemas.
+Names may themselves contain a colon, for example `pool:e57e18d4-10d4-406f-93bf-60f127221bdd`. Only `host`, `docker` and `kubernetes` are treated as schemas.
 
-If a job's `runs-on` matches none of the runner's labels, or sets no `runs-on` at all, it still runs: in `runner.default_image` where docker is available, on the host where it is not. Images maintained for this purpose are listed at [gitea/runner-images](https://gitea.com/gitea/runner-images).
+If a job's `runs-on` matches none of the runner's labels, or sets no `runs-on` at all, it still runs in `runner.default_image`: as a container when the runner has `docker` labels, as a pod when it has `kubernetes` labels, else as a container where docker is available and on the host where it is not. Images maintained for this purpose are listed at [gitea/runner-images](https://gitea.com/gitea/runner-images).
 
 Labels are chosen at registration time (`--labels`, or the interactive prompt) and can be changed afterwards by editing `runner.labels` in the config file, or in the Gitea UI under the runner's settings.
 
@@ -266,6 +243,17 @@ A job in a container reaches a service by its id on the job network, on the port
 
 Unlike GitHub, a job whose steps run on the host (a `host` label without `container:`) starts no service containers, so `job.services` and `job.container` stay empty. Give such a job a `container:` when it needs services.
 
+#### Docker from a job (`GITEA_DOCKER_WORKSPACE`)
+
+Containers a job starts through the Docker socket can bind-mount the workspace by the job's own path, as on a host, for example `docker run -v "$PWD:/src"`. Without the Docker proxy, for example with a remote `DOCKER_HOST`, use `GITEA_DOCKER_WORKSPACE`, the path the daemon sees, as the prefix of workspace binds, with `.` as the fallback for local use:
+
+```yaml
+volumes:
+  - ${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data
+```
+
+Linux container jobs use a Docker proxy when socket sharing and permissions allow it. Other setups use the daemon socket directly. The proxy removes containers, networks and volumes after post steps and the completed hook. Named volumes created through it are job-scoped. To retain resources, mount the daemon socket explicitly in `container.options`. Host jobs use their existing Docker access, where `.` works.
+
 #### Proxy
 
 Set these variables in the runner's environment, with systemd `Environment=`, `docker run -e`, or Kubernetes `env:`:
@@ -280,14 +268,14 @@ The runner uses them for its own requests and gives them to every job, in lower
 
 These hosts are added to `no_proxy` for jobs, so they are always reached directly:
 
-- the cache server
+- the built-in cache server, whose address is assigned at startup
 - `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.
+For one step, set it in the step's `env:`, for the rest of a job, write it to `$GITHUB_ENV`. Setting it at workflow or job level or in `container.env` 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.
 
@@ -295,63 +283,68 @@ Dockerfile actions are built with these variables as build arguments, so their `
 
 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.
 
+#### Built-in actions (`uses: builtin:<name>`)
+
+Use `uses: builtin:checkout` to check out a repository without downloading `actions/checkout` or needing Node in the job image, see **[docs/builtin-actions.md](docs/builtin-actions.md)**.
+
 #### 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.
+Each runner starts its own cache server, so runners do not share cached entries. A runner in a container on the jobs' Docker daemon attaches itself to each job network, so jobs reach its cache without extra setup.
 
-**Eviction**
+**Sharing a cache between runners**
 
-An entry nothing has read or written for `retention` is removed, and a repository past `repo_size_limit` loses its least recently accessed entries until it fits; `size_limit` caps the whole cache the same way. Age alone never retires an entry still in use, and whatever these allow, the cache keeps free space above `health_check.min_free_disk_space_mb` when health checks are enabled.
+Run one `gitea-runner cache-server` and point every runner at it, using the same secret everywhere, for example from `openssl rand -hex 32`:
 
-These apply where the cache server runs, so on a shared server they belong in *its* config, not the runners'. See `retention`, `repo_size_limit`, `size_limit` and `sweep_interval` in [config.example.yaml](internal/pkg/config/config.example.yaml) for units and defaults.
+```yaml
+# cache-server.yaml
+cache:
+  dir: /data/actcache
+  port: 8088
+  external_secret: "<secret>" # or external_secret_file: /path/to/secret
+```
 
-**Cache service v2**
+```bash
+gitea-runner -c cache-server.yaml cache-server
+```
 
-`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
+# each runner's config
+cache:
+  external_server: "http://<cache-server-host>:8088/"
+  external_secret: "<secret>"
+```
+
+`--dir`, `--host` and `--port` override the matching `cache` keys. Eviction settings take effect on the cache server, not on the runners.
+
+Runners can also share one `cache.dir` on a file system with working file locks, at the cost of slower cache requests.
+
+**Storing the cache in an S3-compatible bucket**
+
+The cache can also be stored in an S3-compatible bucket such as AWS S3, MinIO or RustFS, with no cache server. Runners with the same settings use the same cache:
 
 ```yaml
 cache:
-  v2: false
+  s3:
+    endpoint: "http://minio:9000"
+    region: "us-east-1"
+    bucket: "runner-cache"
+    prefix: "gitea-runner-cache"
+    path_style: true
+    access_key_file: "/run/secrets/cache-s3-access-key"
+    secret_key_file: "/run/secrets/cache-s3-secret-key"
 ```
 
-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 on its way into the job, undone whenever the action is downloaded again. 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, so it is made whatever `v2` says: that setting only governs the API the runner advertises. Set `runner.patch_actions: false` to leave every bundle exactly as shipped, an escape hatch for an action the edit breaks. The artifact actions then refuse again and the cache client keeps to v1.
+A cache saved on one runner can be restored on the others within 30 seconds. The eviction settings below do not apply to the bucket, so add lifecycle rules to it that expire old caches and abort incomplete multipart uploads.
 
-**Shared cache across multiple runners**
+**Eviction**
 
-Run one dedicated `gitea-runner cache-server` that all runners point at.
+Entries not read or written within `retention` (default `168h`) are removed. A repository over `repo_size_limit` (default `10GB`) loses its least recently used entries, and `size_limit` (off by default) caps the whole cache the same way. Entries in use are never removed. The cache also keeps 1024 MiB free on its volume, or `health_check.min_free_disk_space_mb` when health checks are enabled. See [config.example.yaml](internal/pkg/config/config.example.yaml) for all options.
 
-1. Create a config file for the cache server host:
+**Cache service v2**
 
-   ```yaml
-   cache:
-     dir: /data/actcache
-     port: 8088
-     external_secret: "replace-with-a-strong-random-secret"
-     # external_secret_file: /path/to/secret # secret can also be passed via a file
-   ```
+`actions/cache` v3.4.0, v4.2.0 and later use the cache service v2 API, which the runner serves by default. These actions fall back to v1 on hosts they do not recognize as GitHub, so the runner removes that check from them while a job runs. This also lets the stock `actions/upload-artifact` v4.4.0 and `actions/download-artifact` v4.1.8 and later work without the `gitea-upload-artifact` fork. With `runner.patch_actions: false`, the cache stays on v1 and the artifact actions fail.
 
-2. Start the server:
-
-   ```bash
-   gitea-runner -c cache-server-config.yaml cache-server
-   ```
-
-3. On every runner:
-
-   ```yaml
-   cache:
-     external_server: "http://<cache-server-host>:8088/"
-     external_secret: "replace-with-a-strong-random-secret"  # must match the server
-     # external_secret_file: /path/to/secret # secret can also be passed via a file
-   ```
-
-Jobs reach the cache server at `external_server`, so when a reverse proxy fronts the server, point `external_server` at the proxy. The cache server itself needs no extra configuration.
-
-Alternatively, mount the same NFS/CIFS share on every runner and point `cache.dir` at it — simpler, but with weaker isolation between repositories.
-
-**S3 / MinIO** — mount object storage as a FUSE filesystem (e.g. [s3fs](https://github.com/s3fs-fuse/s3fs-fuse) or [goofys](https://github.com/kahing/goofys)) and set `cache.dir` to the mount point.
-
-Flags `--dir`, `--host`, and `--port` on `cache-server` override the corresponding `cache.*` YAML keys; all other settings, including `external_secret`, require the config file.
+With v2, artifact calls also go through the cache server, so jobs must be able to reach it. `cache.v2: false` sends them to Gitea directly, unless the Gitea URL has a path or `runner.insecure` is set with HTTPS.
 
 #### Official Docker image
 
@@ -364,6 +357,7 @@ While the runner is idle it cleans up after earlier jobs:
 - 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
+- on runners with `kubernetes` labels, job pods with that label older than `runner.workdir_cleanup_age` are removed the same way, together with their Secrets
 - 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`)
@@ -386,6 +380,10 @@ Both hooks are synchronous and block the job while they run. Either one exiting
 
 See **[docs/job-hooks.md](docs/job-hooks.md)** for the execution order, environment, and platform notes.
 
+#### OpenTelemetry (`OTEL_*`)
+
+Set `OTEL_EXPORTER_OTLP_ENDPOINT` in the runner's environment to send a trace of every job, and the runner's metrics, to an OpenTelemetry collector. See **[docs/telemetry.md](docs/telemetry.md)**.
+
 #### Local job logs (`log.job.dir`)
 
 Set `log.job.dir` to a path and the runner writes a copy of every task's log there as `<start time>-task-<id>.log`: the rows exactly as Gitea received them, with the same secrets masked and the job's result on the last line. Off by default, and what Gitea shows does not change.

act/artifactcache/handler.go

@@ -10,6 +10,7 @@ import (
 	"crypto/hmac"
 	"crypto/rand"
 	"crypto/sha256"
+	"encoding/binary"
 	"encoding/hex"
 	"encoding/json/v2"
 	"errors"
@@ -17,10 +18,10 @@ import (
 	"io"
 	"net"
 	"net/http"
+	"net/http/httputil"
 	"net/url"
 	"os"
 	"path/filepath"
-	"regexp"
 	"slices"
 	"strconv"
 	"strings"
@@ -58,10 +59,9 @@ type JobCredential struct {
 	Repo string `json:"repo"`
 
 	// Results is the instance whose artifact service this server forwards for the job, and
-	// InsecureTLS how the runner reaches it; see results.go. The tags are the wire format a
-	// remote runner registers with.
-	Results     string `json:"results"`
-	InsecureTLS bool   `json:"insecure_tls"`
+	// InsecureTLS how the runner reaches it; see results.go.
+	Results     string `json:"-"`
+	InsecureTLS bool   `json:"-"`
 
 	// PublicURL is this server as a reverse proxy makes the job reach it, not the listen address.
 	PublicURL string `json:"public_url"`
@@ -79,7 +79,8 @@ type credEntry struct {
 
 type Handler struct {
 	dir      string
-	storage  *Storage
+	storage  cacheStorage
+	s3       *s3Storage
 	router   *httprouter.Router
 	listener net.Listener
 	port     int
@@ -89,6 +90,9 @@ type Handler struct {
 	gcing atomic.Bool
 	gcAt  time.Time
 
+	stopSync context.CancelFunc
+	syncing  sync.WaitGroup
+
 	outboundIP string
 
 	// internalSecret guards /_internal/{register,revoke}. When set, a remote
@@ -118,6 +122,8 @@ type Options struct {
 	Dir        string
 	OutboundIP string
 	Port       uint16
+	S3         *S3Options
+	Upstream   string
 
 	// InternalSecret, when non-empty, enables a control-plane API at
 	// /_internal/{register,revoke} that lets a remote runner pre-register the
@@ -130,7 +136,7 @@ type Options struct {
 	Logger logrus.FieldLogger
 }
 
-// StartHandler opens the on-disk cache store and starts the HTTP server.
+// StartHandler starts an embedded cache or forwards cache requests to Upstream.
 func StartHandler(opts Options) (*Handler, error) {
 	dir, logger := opts.Dir, opts.Logger
 	h := &Handler{
@@ -148,6 +154,25 @@ func StartHandler(opts Options) (*Handler, error) {
 	logger = logger.WithField("module", "artifactcache")
 	h.logger = logger
 
+	if opts.OutboundIP != "" {
+		h.outboundIP = opts.OutboundIP
+	} else if ip := common.GetOutboundIP(); ip == nil {
+		return nil, errors.New("unable to determine outbound IP address")
+	} else {
+		h.outboundIP = ip.String()
+	}
+
+	if opts.Upstream != "" {
+		handler, err := h.cacheForwarder(opts.Upstream)
+		if err != nil {
+			return nil, err
+		}
+		if err := h.serve(opts.Port, handler); err != nil {
+			return nil, err
+		}
+		return h, nil
+	}
+
 	if dir == "" {
 		home, err := os.UserHomeDir()
 		if err != nil {
@@ -166,13 +191,11 @@ func StartHandler(opts Options) (*Handler, error) {
 		return nil, err
 	}
 	h.storage = storage
-
-	if opts.OutboundIP != "" {
-		h.outboundIP = opts.OutboundIP
-	} else if ip := common.GetOutboundIP(); ip == nil {
-		return nil, errors.New("unable to determine outbound IP address")
-	} else {
-		h.outboundIP = ip.String()
+	if opts.S3 != nil {
+		if h.s3, err = newS3Storage(storage, *opts.S3); err != nil {
+			return nil, err
+		}
+		h.storage = h.s3
 	}
 
 	secret, err := loadOrCreateSecret(dir)
@@ -202,39 +225,79 @@ func StartHandler(opts Options) (*Handler, error) {
 
 	h.gcCache()
 
+	if err := h.serve(opts.Port, router); err != nil {
+		return nil, err
+	}
+	if h.s3 != nil {
+		ctx, cancel := context.WithCancel(context.Background())
+		h.stopSync = cancel
+		h.syncing.Go(func() { h.syncMetadata(ctx) })
+	}
+	return h, nil
+}
+
+func (h *Handler) serve(port uint16, handler http.Handler) error {
 	// Listen on all interfaces. Binding to outboundIP only would give no real
 	// security benefit (it is the LAN/internet-facing address either way) and
 	// can break Docker Desktop variants where the host's outbound IP is not
 	// routable from inside the container network. Authentication is enforced
 	// by the bearer middleware and per-repo scoping, not by reachability.
-	listener, err := net.Listen("tcp", fmt.Sprintf(":%d", opts.Port))
+	listener, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
 	if err != nil {
-		return nil, err
+		return 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())
+		return 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,
+		Handler:           handler,
 	}
 	go func() {
 		if err := server.Serve(listener); err != nil && errors.Is(err, net.ErrClosed) {
-			logger.Errorf("http serve: %v", err)
+			h.logger.Errorf("http serve: %v", err)
 		}
 	}()
 	h.listener = listener
 	h.server = server
 
-	return h, nil
+	return nil
+}
+
+func (h *Handler) cacheForwarder(upstream string) (http.Handler, error) {
+	target, err := url.Parse(strings.TrimRight(upstream, "/"))
+	if err != nil {
+		return nil, fmt.Errorf("parse cache upstream: %w", err)
+	}
+	transport, _ := http.DefaultTransport.(*http.Transport)
+	transport = transport.Clone()
+	transport.MaxIdleConnsPerHost = 64 // parallel block uploads would otherwise redial past the default 2
+	proxy := &httputil.ReverseProxy{
+		Transport: transport,
+		Rewrite: func(r *httputil.ProxyRequest) {
+			r.SetURL(target)
+			r.Out.URL.RawQuery = r.In.URL.RawQuery // Rewrite drops unparsable query params, and signed URLs must pass verbatim.
+		},
+		ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
+			h.logger.Warnf("cache forward %s %s: %v", r.Method, r.URL.Path, err)
+			h.twirpError(w, r, twirpUnavailable, errors.New("cache upstream is unavailable"))
+		},
+	}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, apiPath+"/") || strings.HasPrefix(r.URL.Path, cacheServiceV2Path+"/") {
+			proxy.ServeHTTP(w, r)
+		} else {
+			h.forwardOrNotFound(w, r)
+		}
+	}), nil
 }
 
 func (h *Handler) ExternalURL() string {
 	// TODO: make the external url configurable if necessary
-	return fmt.Sprintf("http://%s:%d", h.outboundIP, h.port)
+	return "http://" + net.JoinHostPort(h.outboundIP, strconv.Itoa(h.port))
 }
 
 func (h *Handler) baseURL(cred JobCredential) string {
@@ -334,6 +397,10 @@ func (h *Handler) Close() error {
 	if h == nil {
 		return nil
 	}
+	if h.stopSync != nil {
+		h.stopSync()
+		h.syncing.Wait()
+	}
 	var retErr error
 	if h.server != nil {
 		err := h.server.Close()
@@ -367,6 +434,72 @@ func (h *Handler) openDB() (*bolthold.Store, error) {
 	})
 }
 
+// syncMetadata mirrors the bucket into the store until ctx ends, so no request waits on S3 for it.
+func (h *Handler) syncMetadata(ctx context.Context) {
+	ticker := time.NewTicker(metadataSyncInterval)
+	defer ticker.Stop()
+	for {
+		if err := h.importMetadata(ctx); err != nil && ctx.Err() == nil {
+			h.logger.Warnf("sync S3 cache: %v", err)
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+	}
+}
+
+// importMetadata lists after snapshotting the store, so an entry committed meanwhile, published before it is stored, stays.
+func (h *Handler) importMetadata(ctx context.Context) error {
+	db, err := h.openDB()
+	if err != nil {
+		return err
+	}
+	local := h.caches(db, bolthold.Where("Complete").Eq(true).Index("Complete"))
+	db.Close()
+
+	published, err := h.s3.published(ctx)
+	if err != nil {
+		return err
+	}
+	var gone []*Cache
+	for _, cache := range local {
+		if !published[cache.ID] {
+			gone = append(gone, cache)
+		}
+		delete(published, cache.ID)
+	}
+	added := make([]*Cache, 0, len(published))
+	for id := range published {
+		cache, err := h.s3.fetch(ctx, id)
+		if err != nil {
+			return err
+		}
+		added = append(added, cache)
+	}
+
+	db, err = h.openDB()
+	if err != nil {
+		return err
+	}
+	defer db.Close()
+	return db.Bolt().Update(func(tx *bbolt.Tx) error {
+		for _, cache := range added {
+			if err := db.TxUpsert(tx, cache.ID, cache); err != nil {
+				return err
+			}
+		}
+		for _, cache := range gone {
+			_ = h.s3.Storage.Remove(cache.ID) // a blob kept on disk before the runner used S3
+			if err := db.TxDelete(tx, cache.ID, cache); err != nil && !errors.Is(err, bolthold.ErrNotFound) {
+				return err
+			}
+		}
+		return nil
+	})
+}
+
 // GET /_apis/artifactcache/cache
 func (h *Handler) find(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
 	cred := credFromContext(r.Context())
@@ -409,7 +542,7 @@ func (h *Handler) lookupCache(db *bolthold.Store, repo string, keys []string, ve
 		return nil, err
 	}
 	if !ok {
-		_ = db.Delete(cache.ID, cache)
+		h.deleteCache(db, cache)
 		return nil, nil //nolint:nilnil // absence is not an error here
 	}
 	// Handing out a download URL counts as access, or eviction could drop the entry between
@@ -441,7 +574,7 @@ func (h *Handler) reserve(w http.ResponseWriter, r *http.Request, _ httprouter.P
 	now := time.Now().Unix()
 	cache.CreatedAt = now
 	cache.UsedAt = now
-	if err := insertCache(db, cache); err != nil {
+	if err := h.insertCache(db, cache); err != nil {
 		h.responseJSON(w, r, 500, err)
 		return
 	}
@@ -555,6 +688,12 @@ func (h *Handler) commitCache(cache *Cache) error {
 	cache.Size = written
 	cache.Complete = true
 	cache.UsedAt = time.Now().Unix() // a just-written entry counts as accessed, so it cannot be its own eviction victim
+	if h.s3 != nil {
+		if err := h.s3.publish(cache); err != nil {
+			_ = h.storage.Remove(cache.ID)
+			return err
+		}
+	}
 
 	db, err := h.openDB()
 	if err != nil {
@@ -564,6 +703,9 @@ func (h *Handler) commitCache(cache *Cache) error {
 	if err := db.Update(cache.ID, cache); err != nil {
 		return err
 	}
+	if h.s3 != nil {
+		return nil // lifecycle rules on the bucket bound its size
+	}
 	// A commit is the only thing that grows the store, so the only thing that can push the
 	// volume under the floor.
 	h.evictRepo(db, cache.Repo)
@@ -603,12 +745,12 @@ func (h *Handler) bearerAuth(handler httprouter.Handle) httprouter.Handle {
 		h.logger.Debugf("%s %s", r.Method, r.URL.Path)
 		token := bearerToken(r)
 		if token == "" {
-			h.responseJSON(w, r, http.StatusUnauthorized, errors.New("missing bearer token"))
+			h.unauthorized(w, r, errors.New("missing bearer token"))
 			return
 		}
 		cred, ok := h.lookupCredential(token)
 		if !ok {
-			h.responseJSON(w, r, http.StatusUnauthorized, errors.New("unknown bearer token"))
+			h.unauthorized(w, r, errors.New("unknown bearer token"))
 			return
 		}
 		ctx := context.WithValue(r.Context(), credKey{}, cred)
@@ -617,6 +759,14 @@ func (h *Handler) bearerAuth(handler httprouter.Handle) httprouter.Handle {
 	}
 }
 
+func (h *Handler) unauthorized(w http.ResponseWriter, r *http.Request, err error) {
+	if strings.HasPrefix(r.URL.Path, cacheServiceV2Path) {
+		h.twirpError(w, r, twirpUnauthenticated, err)
+		return
+	}
+	h.responseJSON(w, r, http.StatusUnauthorized, err)
+}
+
 // 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 {
@@ -701,8 +851,7 @@ func (h *Handler) internalRegister(w http.ResponseWriter, r *http.Request, _ htt
 		return
 	}
 	h.RegisterJob(body.Token, body.JobCredential)
-	// A server too old to forward answers without this, which is how the caller knows.
-	h.responseJSON(w, r, http.StatusOK, map[string]any{"results_url": h.ResultsURL(body.JobCredential)})
+	h.responseJSON(w, r, http.StatusOK)
 }
 
 // POST /_internal/revoke
@@ -720,6 +869,12 @@ func (h *Handler) internalRevoke(w http.ResponseWriter, r *http.Request, _ httpr
 	h.responseJSON(w, r, http.StatusOK)
 }
 
+// hashedToken fingerprints a job's bearer, so a reservation can tell its own retry from another job.
+func hashedToken(token string) string {
+	sum := sha256.Sum256([]byte(token))
+	return hex.EncodeToString(sum[:])
+}
+
 func bearerToken(r *http.Request) string {
 	auth := r.Header.Get("Authorization")
 	const prefix = "Bearer "
@@ -770,14 +925,9 @@ func findCache(db *bolthold.Store, repo string, keys []string, version string) (
 		if exact != nil {
 			return exact, nil
 		}
-		prefixPattern := "^" + regexp.QuoteMeta(prefix)
-		re, err := regexp.Compile(prefixPattern)
-		if err != nil {
-			continue
-		}
 		if err := db.FindOne(cache,
-			bolthold.Where("Repo").Eq(repo).
-				And("Key").RegExp(re).
+			bolthold.Where("Repo").Eq(repo).Index("Repo").
+				And("Key").MatchFunc(func(key string) (bool, error) { return strings.HasPrefix(key, prefix), nil }).
 				And("Version").Eq(version).
 				And("Complete").Eq(true).
 				SortBy("CreatedAt").Reverse()); err != nil {
@@ -805,8 +955,8 @@ func findExactCache(db *bolthold.Store, repo, key, version string, complete bool
 	}
 	cache := &Cache{}
 	err := db.FindOne(cache,
-		bolthold.Where("Repo").Eq(repo).
-			And("Key").Eq(key).
+		bolthold.Where("Key").Eq(key).Index("Key").
+			And("Repo").Eq(repo).
 			And("Version").Eq(version).
 			And("Complete").Eq(complete).
 			SortBy(sortBy).Reverse())
@@ -819,15 +969,23 @@ func findExactCache(db *bolthold.Store, repo, key, version string, complete bool
 	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)
+func (h *Handler) insertCache(db *bolthold.Store, cache *Cache) error {
+	if h.s3 != nil {
+		var id [8]byte
+		_, _ = rand.Read(id[:])
+		cache.ID = binary.BigEndian.Uint64(id[:]) >> 11 // IDs must be unique across runners, and v1 clients parse an ID as a JS number
+		return db.Insert(cache.ID, cache)
 	}
-	// write back id to db
-	if err := db.Update(cache.ID, cache); err != nil {
-		return fmt.Errorf("write back id to db: %w", err)
-	}
-	return nil
+	return db.Bolt().Update(func(tx *bbolt.Tx) error {
+		if err := db.TxInsert(tx, bolthold.NextSequence(), cache); err != nil {
+			return fmt.Errorf("insert cache: %w", err)
+		}
+		// write back id to db
+		if err := db.TxUpdate(tx, cache.ID, cache); err != nil {
+			return fmt.Errorf("write back id to db: %w", err)
+		}
+		return nil
+	})
 }
 
 // touchCache stamps UsedAt so gcCache does not reap an entry mid-upload. With requireIncomplete
@@ -852,6 +1010,9 @@ func (h *Handler) touchCache(id uint64, requireIncomplete bool) error {
 	if requireIncomplete && cache.Complete {
 		return fmt.Errorf("cache %d: already complete", id)
 	}
+	if !touchNeeded(cache) {
+		return nil
+	}
 	cache.UsedAt = time.Now().Unix()
 	return db.Update(cache.ID, cache)
 }
@@ -861,15 +1022,19 @@ const (
 
 	defaultSweepInterval = time.Hour
 
-	// inUseGrace matches artifactURLTTL so an entry outlives every signed URL still usable
-	// for it, and no sweep cuts off a download in progress.
-	inUseGrace = artifactURLTTL
+	touchStale = time.Minute // how stale a completed entry's UsedAt may get before an access rewrites it, sparing hits the fsync
+
+	// inUseGrace covers artifactURLTTL plus the touchStale lag so an entry outlives every signed URL
+	// still usable for it, and no sweep cuts off a download in progress.
+	inUseGrace = artifactURLTTL + touchStale
 
 	// uploadStallTimeout is how long a reservation may sit without a chunk before it counts
 	// as abandoned. Widening it also widens the window for findExactCache to hand a finalize
 	// a stale reservation.
 	uploadStallTimeout = 5 * time.Minute
 
+	metadataSyncInterval = 30 * time.Second
+
 	defaultMinFreeDisk = 1024 * miB
 )
 
@@ -917,6 +1082,9 @@ func (h *Handler) gcCache() {
 	defer db.Close()
 
 	h.evictIncomplete(db)
+	if h.s3 != nil {
+		return // lifecycle rules on the bucket expire its entries
+	}
 	h.evictExpired(db)
 	h.evictSuperseded(db)
 	h.evictOversized(db)
@@ -957,7 +1125,7 @@ func (h *Handler) evictExpired(db *bolthold.Store) {
 		return
 	}
 	// Never below inUseGrace, or a short retention would outrun a signed URL already issued.
-	window := max(h.policy.Retention, inUseGrace)
+	window := max(h.policy.Retention+touchStale, inUseGrace)
 	h.sweep(db, bolthold.Where("UsedAt").Lt(time.Now().Add(-window).Unix()).Index("UsedAt"))
 }
 
@@ -1058,10 +1226,18 @@ func inUse(cache *Cache) bool {
 	return time.Since(time.Unix(cache.UsedAt, 0)) < inUseGrace
 }
 
+// touchNeeded skips a write that would not change the second, and completed entries fresher than touchStale.
+func touchNeeded(cache *Cache) bool {
+	return cache.UsedAt < time.Now().Unix() && (!cache.Complete || time.Since(time.Unix(cache.UsedAt, 0)) >= touchStale)
+}
+
 // touch stamps UsedAt through the caller's store, a bolt write on the read path. It cannot
 // go through touchCache, which opens its own store and would block on the exclusive lock
 // for as long as the caller holds one.
 func (h *Handler) touch(db *bolthold.Store, cache *Cache) {
+	if !touchNeeded(cache) {
+		return
+	}
 	cache.UsedAt = time.Now().Unix()
 	if err := db.Update(cache.ID, cache); err != nil {
 		h.logger.Warnf("touch cache: %v", err)
@@ -1106,7 +1282,11 @@ func totalSize(caches []*Cache) int64 {
 // deleteCache drops an entry and its bytes, reporting whether it went fully. The blob goes
 // first, so a failed unlink leaves the row for the next sweep instead of orphaning bytes.
 func (h *Handler) deleteCache(db *bolthold.Store, cache *Cache) bool {
-	if err := h.storage.Remove(cache.ID); err != nil {
+	storage := h.storage
+	if h.s3 != nil && !cache.Complete {
+		storage = h.s3.Storage // an upload not yet committed has nothing in the bucket
+	}
+	if err := storage.Remove(cache.ID); err != nil {
 		h.logger.Warnf("remove cache blob: %v", err)
 		return false
 	}

act/artifactcache/handler_test.go

@@ -12,6 +12,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
@@ -52,6 +53,59 @@ func signArtifactURL(h *Handler, id int64) string {
 	return h.signedArtifactURL(JobCredential{}, uint64(id), time.Now().Add(artifactURLTTL))
 }
 
+func TestHandler_ExternalURL(t *testing.T) {
+	assert.Equal(t, "http://[2001:db8::1]:8080", (&Handler{outboundIP: "2001:db8::1", port: 8080}).ExternalURL())
+}
+
+func TestHandler_Upstream(t *testing.T) {
+	var upstream *httptest.Server
+	upstream = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPut, r.Method)
+		assert.Equal(t, "/cache%20server"+blobPath+"/%34%32", r.URL.EscapedPath())
+		assert.Equal(t, "sig=opaque%2Fvalue&raw=a;b", r.URL.RawQuery)
+		assert.Equal(t, strings.TrimPrefix(upstream.URL, "http://"), r.Host)
+		assert.Equal(t, "Bearer unregistered", r.Header.Get("Authorization"))
+		_, err := io.Copy(w, r.Body)
+		assert.NoError(t, err)
+	}))
+	t.Cleanup(upstream.Close)
+	dir := filepath.Join(t.TempDir(), "artifactcache")
+	handler, err := StartHandler(Options{
+		Dir:        dir,
+		OutboundIP: "127.0.0.1",
+		Upstream:   upstream.URL + "/cache%20server//",
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, handler.Close()) })
+
+	req, err := http.NewRequestWithContext(t.Context(), http.MethodPut,
+		handler.ExternalURL()+blobPath+"/%34%32?sig=opaque%2Fvalue&raw=a;b", strings.NewReader("cache content"))
+	require.NoError(t, err)
+	req.Header.Set("Authorization", "Bearer unregistered")
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	forwarded, err := io.ReadAll(resp.Body)
+	resp.Body.Close()
+	require.NoError(t, err)
+	assert.Equal(t, "cache content", string(forwarded))
+
+	resp, err = http.Post(handler.ExternalURL()+internalPath+"/register", "application/json", nil)
+	require.NoError(t, err)
+	resp.Body.Close()
+	assert.Equal(t, http.StatusNotFound, resp.StatusCode)
+
+	upstream.Close()
+	resp, err = http.Post(handler.ExternalURL()+cacheServiceV2Path+"/CreateCacheEntry", "application/json", strings.NewReader(`{}`))
+	require.NoError(t, err)
+	var failure map[string]string
+	err = json.UnmarshalRead(resp.Body, &failure)
+	resp.Body.Close()
+	require.NoError(t, err)
+	assert.Equal(t, http.StatusServiceUnavailable, resp.StatusCode)
+	assert.Equal(t, map[string]string{"code": "unavailable", "msg": "cache upstream is unavailable"}, failure)
+	assert.NoDirExists(t, dir)
+}
+
 func TestHandler(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
 	handler, err := StartHandler(Options{Dir: dir})
@@ -767,7 +821,7 @@ func TestHandler_gcCache(t *testing.T) {
 				Key:       "test_key_3",
 				Version:   "test_version",
 				Complete:  true,
-				UsedAt:    now.Add(-(testRetention + time.Second)).Unix(),
+				UsedAt:    now.Add(-(testRetention + touchStale + time.Second)).Unix(),
 				CreatedAt: now.Add(-(testRetention + time.Hour)).Unix(),
 			},
 			Kept: false,
@@ -810,7 +864,7 @@ func TestHandler_gcCache(t *testing.T) {
 	db, err := handler.openDB()
 	require.NoError(t, err)
 	for _, c := range cases {
-		require.NoError(t, insertCache(db, c.Cache))
+		require.NoError(t, handler.insertCache(db, c.Cache))
 	}
 	require.NoError(t, db.Close())
 
@@ -982,7 +1036,7 @@ func TestHandler_SweepKeepsEntryWhenBlobSurvives(t *testing.T) {
 	handler := newTestHandler(t, Policy{Retention: testRetention}, cache)
 
 	// A non-empty directory where the blob belongs makes os.Remove fail on every platform.
-	blob := handler.storage.filename(cache.ID)
+	blob := handler.storage.(*Storage).filename(cache.ID)
 	require.NoError(t, os.MkdirAll(blob, 0o755))
 	require.NoError(t, os.WriteFile(filepath.Join(blob, "held"), []byte("x"), 0o600))
 
@@ -1042,27 +1096,51 @@ func TestHandler_gcCacheInterval(t *testing.T) {
 	assert.Empty(t, keptKeys(t, handler, []*Cache{cache}))
 }
 
+func TestHandler_touchCacheSkipsFreshCompletedEntries(t *testing.T) {
+	fresh := &Cache{Repo: testRepo, Key: "fresh", Version: "v", Complete: true, UsedAt: time.Now().Unix()}
+	pending := &Cache{Repo: testRepo, Key: "pending", Version: "v", UsedAt: time.Now().Add(-time.Second).Unix()}
+	handler := newTestHandler(t, Policy{}, fresh, pending)
+	txID := func() int {
+		db, err := handler.openDB()
+		require.NoError(t, err)
+		defer db.Close()
+		var id int
+		require.NoError(t, db.Bolt().View(func(tx *bbolt.Tx) error { id = tx.ID(); return nil }))
+		return id
+	}
+
+	before := txID()
+	require.NoError(t, handler.touchCache(fresh.ID, false))
+	assert.Equal(t, before, txID())
+	require.NoError(t, handler.touchCache(pending.ID, false))
+	assert.Greater(t, txID(), before)
+}
+
 // newTestHandler starts a handler with testToken registered, seeded with entries.
 func newTestHandler(t *testing.T, policy Policy, entries ...*Cache) *Handler {
 	t.Helper()
-	handler, err := StartHandler(Options{
-		Dir:        filepath.Join(t.TempDir(), "artifactcache"),
-		OutboundIP: "127.0.0.1",
-		Policy:     policy,
-	})
-	require.NoError(t, err)
-	t.Cleanup(func() { require.NoError(t, handler.Close()) })
-	handler.RegisterJob(testToken, JobCredential{Repo: testRepo})
+	handler := startTestHandler(t, Options{Policy: policy})
 
 	db, err := handler.openDB()
 	require.NoError(t, err)
 	for _, e := range entries {
-		require.NoError(t, insertCache(db, e))
+		require.NoError(t, handler.insertCache(db, e))
 	}
 	require.NoError(t, db.Close())
 	return handler
 }
 
+func startTestHandler(t *testing.T, opts Options) *Handler {
+	t.Helper()
+	opts.Dir = filepath.Join(t.TempDir(), "artifactcache")
+	opts.OutboundIP = "127.0.0.1"
+	handler, err := StartHandler(opts)
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, handler.Close()) })
+	handler.RegisterJob(testToken, JobCredential{Repo: testRepo})
+	return handler
+}
+
 // keptKeys reports which of entries are still in the store.
 func keptKeys(t *testing.T, handler *Handler, entries []*Cache) []string {
 	t.Helper()
@@ -1403,8 +1481,8 @@ func TestHandler_GC_PerRepoDedup(t *testing.T) {
 	stale := time.Now().Add(-inUseGrace - time.Minute).Unix()
 	a := &Cache{Repo: "owner/repoA", Key: key, Version: version, Complete: true, CreatedAt: stale, UsedAt: stale, Size: 1}
 	b := &Cache{Repo: "owner/repoB", Key: key, Version: version, Complete: true, CreatedAt: now, UsedAt: now, Size: 1}
-	require.NoError(t, insertCache(db, a))
-	require.NoError(t, insertCache(db, b))
+	require.NoError(t, handler.insertCache(db, a))
+	require.NoError(t, handler.insertCache(db, b))
 	// Write the backing blobs so the dedup deletion has something to remove.
 	require.NoError(t, handler.storage.Write(a.ID, 0, strings.NewReader("a")))
 	_, err = handler.storage.Commit(a.ID, 1)
@@ -1498,7 +1576,10 @@ func TestHandler_InternalAPI_AuthAndUsage(t *testing.T) {
 		}
 
 		assert.Equal(t, http.StatusUnauthorized, probe("via-internal-api"))
-		assert.Equal(t, http.StatusOK, post("/_internal/register", secret, `{"token":"via-internal-api","repo":"owner/repo"}`))
+		assert.Equal(t, http.StatusOK, post("/_internal/register", secret, `{"token":"via-internal-api","repo":"owner/repo","public_url":"http://runner.example","results":"https://gitea.example","insecure_tls":true}`))
+		cred, ok := handler.lookupCredential("via-internal-api")
+		require.True(t, ok)
+		assert.Equal(t, JobCredential{Repo: testRepo, PublicURL: "http://runner.example"}, cred)
 		assert.NotEqual(t, http.StatusUnauthorized, probe("via-internal-api"))
 		assert.Equal(t, http.StatusOK, post("/_internal/revoke", secret, `{"token":"via-internal-api"}`))
 		assert.Equal(t, http.StatusUnauthorized, probe("via-internal-api"))

act/artifactcache/handler_v2.go

@@ -39,8 +39,9 @@ const (
 
 	blobUploadURLTTL = time.Hour
 
-	// twirpInternal is the only error code that is not the client's fault.
-	twirpInternal = "internal"
+	twirpInternal        = "internal"
+	twirpUnavailable     = "unavailable"
+	twirpUnauthenticated = "unauthenticated"
 )
 
 func (h *Handler) registerV2Routes(router *httprouter.Router) {
@@ -56,7 +57,7 @@ func (h *Handler) v2CreateCacheEntry(w http.ResponseWriter, r *http.Request, _ h
 	cred := credFromContext(r.Context())
 	req, err := decodeTwirpRequest[v2CreateRequest](r)
 	if err != nil {
-		h.twirpError(w, r, "malformed_request", err)
+		h.twirpError(w, r, "malformed", err)
 		return
 	}
 	if req.Key == "" || req.Version == "" {
@@ -83,16 +84,35 @@ func (h *Handler) v2CreateCacheEntry(w http.ResponseWriter, r *http.Request, _ h
 		return
 	}
 
+	// A second live reservation is finalized by whichever job calls last, against the other's upload.
+	owner := hashedToken(bearerToken(r))
+	if pending, err := findExactCache(db, cred.Repo, req.Key, req.Version, false); err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	} else if pending != nil && pending.UsedAt > time.Now().Add(-uploadStallTimeout).Unix() {
+		if pending.Owner != owner {
+			h.twirpNotOK(w, r)
+			return
+		}
+		h.touch(db, pending)                                // still uploading, so it must not go stale under the sweep
+		h.responseJSON(w, r, http.StatusOK, map[string]any{ // this job retrying its own reservation
+			"ok":                true,
+			"signed_upload_url": h.signedURL(cred, blobPath, blobUploadPurpose, pending.ID, time.Now().Add(blobUploadURLTTL)),
+		})
+		return
+	}
+
 	now := time.Now().Unix()
 	cache := &Cache{
 		Repo:      cred.Repo,
 		Key:       req.Key,
 		Version:   req.Version,
+		Owner:     owner,
 		Size:      -1, // the size is only known at finalize time
 		CreatedAt: now,
 		UsedAt:    now,
 	}
-	if err := insertCache(db, cache); err != nil {
+	if err := h.insertCache(db, cache); err != nil {
 		h.twirpError(w, r, twirpInternal, err)
 		return
 	}
@@ -107,7 +127,7 @@ func (h *Handler) v2FinalizeCacheEntryUpload(w http.ResponseWriter, r *http.Requ
 	cred := credFromContext(r.Context())
 	req, err := decodeTwirpRequest[v2FinalizeRequest](r)
 	if err != nil {
-		h.twirpError(w, r, "malformed_request", err)
+		h.twirpError(w, r, "malformed", err)
 		return
 	}
 
@@ -119,6 +139,13 @@ func (h *Handler) v2FinalizeCacheEntryUpload(w http.ResponseWriter, r *http.Requ
 	defer db.Close()
 
 	cache, err := findExactCache(db, cred.Repo, req.Key, req.Version, false)
+	if err == nil && cache != nil && cache.Owner != hashedToken(bearerToken(r)) {
+		cache = nil // not the reservation this job made, so not this job's to commit
+	}
+	if err == nil && cache == nil {
+		// A retry whose first response was lost finds the entry already committed.
+		cache, err = findExactCache(db, cred.Repo, req.Key, req.Version, true)
+	}
 	if err != nil {
 		h.twirpError(w, r, twirpInternal, err)
 		return
@@ -127,13 +154,15 @@ func (h *Handler) v2FinalizeCacheEntryUpload(w http.ResponseWriter, r *http.Requ
 		h.twirpNotOK(w, r)
 		return
 	}
-	db.Close() // commitCache needs the store closed
 
-	cache.Size = int64(cmp.Or(req.SizeBytes, req.SizeBytesCamel))
-	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
+	if !cache.Complete {
+		db.Close() // commitCache needs the store closed
+		cache.Size = int64(cmp.Or(req.SizeBytes, req.SizeBytesCamel))
+		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{
@@ -147,7 +176,7 @@ func (h *Handler) v2GetCacheEntryDownloadURL(w http.ResponseWriter, r *http.Requ
 	cred := credFromContext(r.Context())
 	req, err := decodeTwirpRequest[v2DownloadRequest](r)
 	if err != nil {
-		h.twirpError(w, r, "malformed_request", err)
+		h.twirpError(w, r, "malformed", err)
 		return
 	}
 
@@ -230,8 +259,13 @@ func (h *Handler) twirpNotOK(w http.ResponseWriter, r *http.Request) {
 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 {
+	switch code {
+	case twirpInternal:
 		status = http.StatusInternalServerError
+	case twirpUnavailable:
+		status = http.StatusServiceUnavailable
+	case twirpUnauthenticated:
+		status = http.StatusUnauthorized
 	}
 	h.responseJSON(w, r, status, map[string]any{"code": code, "msg": err.Error()})
 }

act/artifactcache/handler_v2_test.go

@@ -10,6 +10,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"strconv"
 	"strings"
 	"testing"
@@ -141,6 +142,17 @@ func TestCacheServiceV2BlockUpload(t *testing.T) {
 	}
 	list.WriteString(`</BlockList>`)
 	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL+"&comp=blocklist", list.Bytes()))
+	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL+"&comp=blocklist", list.Bytes()),
+		"a client that lost the first answer retries the list it already sent")
+
+	var reordered bytes.Buffer
+	reordered.WriteString(`<?xml version="1.0" encoding="utf-8"?><BlockList>`)
+	for _, blockID := range []string{order[1], order[0], order[2]} {
+		fmt.Fprintf(&reordered, "<Latest>%s</Latest>", blockID)
+	}
+	reordered.WriteString(`</BlockList>`)
+	assert.Equal(t, http.StatusInternalServerError, putBlob(t, uploadURL+"&comp=blocklist", reordered.Bytes()),
+		"the blocks are already assembled, so a different order would silently disagree with them")
 
 	finalized := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
 		"key": "blocks", "version": "v1", "size_bytes": len("hello world!"),
@@ -241,3 +253,101 @@ func TestCacheServiceV2Lookups(t *testing.T) {
 		assert.Equal(t, false, got["ok"])
 	})
 }
+
+func TestCacheServiceV2RefusalsAreTwirp(t *testing.T) {
+	handler := newTestHandler(t, Policy{})
+
+	tests := []struct {
+		name   string
+		token  string
+		body   string
+		status int
+		code   string
+	}{
+		{"no bearer at all", "", `{"key":"k","version":"v"}`, http.StatusUnauthorized, twirpUnauthenticated},
+		{"a bearer nobody registered", "not-a-job", `{"key":"k","version":"v"}`, http.StatusUnauthorized, twirpUnauthenticated},
+		{"a body that is not the request", testToken, `{`, http.StatusBadRequest, "malformed"},
+		{"a request missing its key", testToken, `{"version":"v"}`, http.StatusBadRequest, "invalid_argument"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req, err := http.NewRequestWithContext(t.Context(), http.MethodPost,
+				handler.ExternalURL()+cacheServiceV2Path+"/CreateCacheEntry", strings.NewReader(tt.body))
+			require.NoError(t, err)
+			if tt.token != "" {
+				req.Header.Set("Authorization", "Bearer "+tt.token)
+			}
+			resp, err := http.DefaultClient.Do(req)
+			require.NoError(t, err)
+			defer resp.Body.Close()
+
+			require.Equal(t, tt.status, resp.StatusCode)
+			got := map[string]string{}
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
+			assert.Equal(t, tt.code, got["code"])
+			assert.NotEmpty(t, got["msg"])
+		})
+	}
+}
+
+func TestCacheServiceV2ConcurrentSaveAndRetries(t *testing.T) {
+	handler := newTestHandler(t, Policy{})
+	content := []byte("the cached archive")
+
+	const otherJob = "another-jobs-token"
+	defer handler.RegisterJob(otherJob, JobCredential{Repo: testRepo})()
+	reserve := func(client *http.Client) map[string]any {
+		return v2Call(t, handler, client, "CreateCacheEntry", map[string]any{"key": "shared", "version": "v1"})
+	}
+	first := reserve(testClient)
+	require.Equal(t, true, first["ok"])
+	retry := reserve(testClient)
+	assert.Equal(t, true, retry["ok"], "a job retrying its own reservation is not a conflict")
+	entryOf := func(reserved map[string]any) string {
+		parsed, err := url.Parse(reserved["signed_upload_url"].(string))
+		require.NoError(t, err)
+		return parsed.Path
+	}
+	assert.Equal(t, entryOf(first), entryOf(retry), "the same reservation, however freshly its URL is signed")
+	assert.Equal(t, false, reserve(&http.Client{Transport: &bearerTransport{token: otherJob}})["ok"],
+		"another job's reservation would be finalized against the first upload")
+
+	otherClient := &http.Client{Transport: &bearerTransport{token: otherJob}}
+	reserved := v2Call(t, handler, otherClient, "CreateCacheEntry", map[string]any{"key": "owned", "version": "v1"})
+	require.Equal(t, true, reserved["ok"])
+	require.Equal(t, http.StatusCreated, putBlob(t, reserved["signed_upload_url"].(string), content))
+	assert.Equal(t, false, v2Call(t, handler, testClient, "FinalizeCacheEntryUpload",
+		map[string]any{"key": "owned", "version": "v1", "size_bytes": strconv.Itoa(len(content))})["ok"],
+		"another job's upload is not this job's to finalize")
+
+	base := handler.ExternalURL() + apiPath
+	reserveV1, err := json.Marshal(&Request{Key: "v1-made", Version: "v1", Size: int64(len(content))})
+	require.NoError(t, err)
+	resp, err := testClient.Post(base+"/caches", "application/json", bytes.NewReader(reserveV1))
+	require.NoError(t, err)
+	var madeByV1 struct {
+		CacheID uint64 `json:"cacheId"`
+	}
+	require.NoError(t, json.UnmarshalRead(resp.Body, &madeByV1))
+	resp.Body.Close()
+	upload, err := http.NewRequestWithContext(t.Context(), http.MethodPatch,
+		fmt.Sprintf("%s/caches/%d", base, madeByV1.CacheID), bytes.NewReader(content))
+	require.NoError(t, err)
+	upload.Header.Set("Content-Range", fmt.Sprintf("bytes 0-%d/*", len(content)-1))
+	resp, err = testClient.Do(upload)
+	require.NoError(t, err)
+	resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	assert.Equal(t, false, v2Call(t, handler, testClient, "FinalizeCacheEntryUpload",
+		map[string]any{"key": "v1-made", "version": "v1", "size_bytes": strconv.Itoa(len(content))})["ok"],
+		"a reservation this job did not make through v2 is not its to commit")
+
+	finalized, _ := saveV2(t, handler, "deps", "v1", content)
+	require.Equal(t, true, finalized["ok"])
+	again := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+		"key": "deps", "version": "v1", "size_bytes": strconv.Itoa(len(content)),
+	})
+	assert.Equal(t, true, again["ok"], "a retry whose first answer was lost must not report a failed save")
+	assert.Equal(t, finalized["entry_id"], again["entry_id"])
+}

act/artifactcache/model.go

@@ -16,6 +16,7 @@ type Cache struct {
 	Key       string `json:"key" boltholdIndex:"Key"`
 	Version   string `json:"version" boltholdIndex:"Version"`
 	Size      int64  `json:"cacheSize"`
+	Owner     string `json:"owner"` // hashed bearer, so a job's own retry is not another job's reservation
 	Complete  bool   `json:"complete" boltholdIndex:"Complete"`
 	UsedAt    int64  `json:"usedAt" boltholdIndex:"UsedAt"`
 	CreatedAt int64  `json:"createdAt" boltholdIndex:"CreatedAt"`

act/artifactcache/results.go

@@ -5,6 +5,8 @@ package artifactcache
 
 import (
 	"crypto/tls"
+	"errors"
+	"fmt"
 	"net/http"
 	"net/http/httputil"
 	"net/url"
@@ -15,23 +17,38 @@ import (
 // Gitea implements only the artifact half of it. Forwarding that half from here makes this origin
 // the whole service, so ACTIONS_RESULTS_URL can point at it truthfully, which is what the clients
 // this runner cannot patch need, docker buildx among them.
-//
-// The instance to forward to travels with the job registration rather than with configuration, so
-// a cache server shared between runners serves each of their instances.
 const artifactServicePath = "/twirp/github.actions.results.api.v1.ArtifactService/"
 
 // forwardOrNotFound is the router's fallback: the artifact service of the instance the job
 // registered with, and the 404 the router would have written otherwise.
 func (h *Handler) forwardOrNotFound(w http.ResponseWriter, r *http.Request) {
-	cred, ok := h.lookupCredential(bearerToken(r))
-	if !ok || cred.Results == "" || !strings.HasPrefix(r.URL.Path, artifactServicePath) {
+	if !strings.HasPrefix(r.URL.Path, artifactServicePath) {
 		http.NotFound(w, r)
 		return
 	}
+	cred, ok := h.lookupCredential(bearerToken(r))
+	if !ok {
+		h.twirpError(w, r, twirpUnauthenticated, errors.New("unknown bearer token"))
+		return
+	}
+	if cred.Results == "" {
+		h.twirpError(w, r, twirpInternal, errors.New("no instance is registered for this job"))
+		return
+	}
 	target, err := url.Parse(strings.TrimSuffix(cred.Results, "/"))
+	if err == nil && (target.Hostname() == "" || (target.Scheme != "http" && target.Scheme != "https")) {
+		err = errors.New("not an absolute http or https URL the job could use")
+	}
 	if err != nil {
 		h.logger.Errorf("artifact service forward to %q: %v", cred.Results, err)
-		w.WriteHeader(http.StatusBadGateway)
+		h.twirpError(w, r, twirpInternal, fmt.Errorf("artifact service address %q is unusable: %w", cred.Results, err))
+		return
+	}
+	if !h.mustProxy(r, cred, target) {
+		redirect := target.JoinPath(r.URL.EscapedPath())
+		redirect.RawQuery = mergeQuery(target.RawQuery, r.URL.RawQuery)
+		h.logger.Debugf("%s %s: redirecting to %s", r.Method, r.URL.Path, target)
+		http.Redirect(w, r, redirect.String(), http.StatusTemporaryRedirect)
 		return
 	}
 	h.logger.Debugf("%s %s: forwarding to %s", r.Method, r.URL.Path, target)
@@ -44,9 +61,9 @@ func (h *Handler) forwardOrNotFound(w http.ResponseWriter, r *http.Request) {
 			// directly and never through here.
 			r.Out.Host = target.Host
 		},
-		ErrorHandler: func(w http.ResponseWriter, _ *http.Request, err error) {
+		ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
 			h.logger.Warnf("artifact service forward to %s: %v", target, err)
-			w.WriteHeader(http.StatusBadGateway)
+			h.twirpError(w, r, twirpInternal, fmt.Errorf("cache server cannot reach the artifact service at %s: %w", target, err))
 		},
 	}
 	if cred.InsecureTLS {
@@ -55,5 +72,24 @@ func (h *Handler) forwardOrNotFound(w http.ResponseWriter, r *http.Request) {
 	proxy.ServeHTTP(w, r)
 }
 
+// A protocol switch loses the bearer or the agent, and an untrusted instance needs skipped verification.
+func (h *Handler) mustProxy(r *http.Request, cred JobCredential, target *url.URL) bool {
+	if cred.InsecureTLS && target.Scheme == "https" {
+		return true
+	}
+	scheme := r.Header.Get("X-Forwarded-Proto")
+	if scheme == "" {
+		scheme = "http"
+	}
+	return scheme != target.Scheme
+}
+
+func mergeQuery(target, request string) string {
+	if target == "" || request == "" {
+		return target + request
+	}
+	return target + "&" + request
+}
+
 // insecureTransport is shared, because a transport per request would pool no connections.
-var insecureTransport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}} //nolint:gosec // the runner reaches its instance on the operator's say-so
+var insecureTransport = &http.Transport{Proxy: http.ProxyFromEnvironment, TLSClientConfig: &tls.Config{InsecureSkipVerify: true}} //nolint:gosec // the runner reaches its instance on the operator's say-so

act/artifactcache/results_test.go

@@ -4,6 +4,8 @@
 package artifactcache
 
 import (
+	"cmp"
+	"encoding/json/v2"
 	"io"
 	"net/http"
 	"net/http/httptest"
@@ -14,8 +16,6 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-// The artifact half is forwarded under the Host Gitea knows itself by, so the URLs it hands back
-// still point at Gitea, and nothing else is proxied.
 func TestFrontResultsService(t *testing.T) {
 	var gotHost, gotPath, gotProto string
 	gitea := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -23,34 +23,112 @@ func TestFrontResultsService(t *testing.T) {
 		_, _ = io.WriteString(w, `{"ok":true}`)
 	}))
 	defer gitea.Close()
+	selfSigned := httptest.NewTLSServer(gitea.Config.Handler)
+	defer selfSigned.Close()
 
 	handler, err := StartHandler(Options{Dir: t.TempDir(), OutboundIP: "127.0.0.1"})
 	require.NoError(t, err)
 	defer handler.Close()
-	const token = "forward-token"
+	const token, rpc = "forward-token", artifactServicePath + "CreateArtifact"
 
-	client := &http.Client{Transport: &bearerTransport{token: token}}
-	post := func(path string) int {
+	noRedirect := func(token string) *http.Client {
+		return &http.Client{
+			Transport:     &bearerTransport{token: token},
+			CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
+		}
+	}
+	post := func(path string) (int, map[string]string) {
 		req, err := http.NewRequestWithContext(t.Context(), http.MethodPost, handler.ExternalURL()+path, nil)
 		require.NoError(t, err)
-		resp, err := client.Do(req)
+		resp, err := noRedirect(token).Do(req)
 		require.NoError(t, err)
-		resp.Body.Close()
-		return resp.StatusCode
+		defer resp.Body.Close()
+		body := map[string]string{}
+		_ = json.UnmarshalRead(resp.Body, &body)
+		return resp.StatusCode, body
 	}
 
-	assert.Equal(t, http.StatusNotFound, post(artifactServicePath+"CreateArtifact"),
-		"an unregistered token is forwarded nowhere")
+	status, body := post(rpc)
+	assert.Equal(t, http.StatusUnauthorized, status, "an unregistered token is told so, not left to parse a 404 page")
+	assert.Equal(t, twirpUnauthenticated, body["code"])
+	assert.Contains(t, body["msg"], "bearer")
+	assert.NotEmpty(t, body["msg"])
 
-	defer handler.RegisterJob(token, JobCredential{Repo: "owner/repo", Results: gitea.URL})()
+	defer handler.RegisterJob(token, JobCredential{Repo: "owner/repo", Results: selfSigned.URL, InsecureTLS: true})()
 
-	assert.Equal(t, http.StatusOK, post(artifactServicePath+"CreateArtifact"))
-	assert.Equal(t, strings.TrimPrefix(gitea.URL, "http://"), gotHost, "Gitea must see the host it mints its URLs from")
+	status, _ = post(rpc)
+	require.Equal(t, http.StatusOK, status, "an http job reaching an https instance must proxy")
+	assert.Equal(t, strings.TrimPrefix(selfSigned.URL, "https://"), gotHost, "Gitea must see the host it mints its URLs from")
 	assert.Empty(t, gotProto, "a forwarded scheme would make an https Gitea mint http URLs")
-	assert.Equal(t, artifactServicePath+"CreateArtifact", gotPath)
+	assert.Equal(t, rpc, gotPath)
 
 	gotPath = ""
-	assert.Equal(t, http.StatusNotFound, post("/twirp/github.actions.results.api.v1.OtherService/Do"))
-	assert.Equal(t, http.StatusNotFound, post("/api/v1/repos/owner/repo"))
+	status, _ = post("/twirp/github.actions.results.api.v1.OtherService/Do")
+	assert.Equal(t, http.StatusNotFound, status)
+	status, _ = post("/api/v1/repos/owner/repo")
+	assert.Equal(t, http.StatusNotFound, status)
 	assert.Empty(t, gotPath, "only the artifact service is forwarded")
+
+	tests := []struct {
+		name           string
+		cred           JobCredential
+		forwardedProto string
+		reqQuery       string
+		want           int
+		location       string
+		wantMsg        string
+	}{
+		{name: "an instance the job reaches itself", cred: JobCredential{Results: gitea.URL}, want: http.StatusTemporaryRedirect},
+		{name: "a sub-path instance keeps its prefix", cred: JobCredential{Results: gitea.URL + "/sub"}, want: http.StatusTemporaryRedirect},
+		{name: "an instance with no certificate to distrust", cred: JobCredential{Results: gitea.URL, InsecureTLS: true}, want: http.StatusTemporaryRedirect},
+		{
+			name: "both queries survive", cred: JobCredential{Results: gitea.URL + "?tenant=one"}, reqQuery: "?run=7",
+			want: http.StatusTemporaryRedirect, location: gitea.URL + rpc + "?tenant=one&run=7",
+		},
+		{
+			name: "a trusted https instance is reached by the job itself",
+			cred: JobCredential{Results: selfSigned.URL}, forwardedProto: "https", want: http.StatusTemporaryRedirect,
+		},
+		{
+			name: "the job does not share this server's disregard for the certificate",
+			cred: JobCredential{Results: selfSigned.URL, InsecureTLS: true}, forwardedProto: "https", want: http.StatusOK,
+		},
+		{name: "an http job is not redirected to an https instance", cred: JobCredential{Results: selfSigned.URL}, want: http.StatusInternalServerError},
+		{
+			name: "a forwarded https scheme onto an http instance is proxied",
+			cred: JobCredential{Results: gitea.URL}, forwardedProto: "https", want: http.StatusOK,
+		},
+		{
+			name: "a scheme the job could not use is refused before it is sent one",
+			cred: JobCredential{Results: "ftp://gitea.example"}, want: http.StatusInternalServerError, wantMsg: "unusable",
+		},
+		{
+			name: "an address with no host is refused before it is sent one",
+			cred: JobCredential{Results: "http://:3000"}, want: http.StatusInternalServerError, wantMsg: "unusable",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			defer handler.RegisterJob(tt.name, tt.cred)()
+			req, err := http.NewRequestWithContext(t.Context(), http.MethodPost, handler.ExternalURL()+rpc+tt.reqQuery, nil)
+			require.NoError(t, err)
+			if tt.forwardedProto != "" {
+				req.Header.Set("X-Forwarded-Proto", tt.forwardedProto)
+			}
+			resp, err := noRedirect(tt.name).Do(req)
+			require.NoError(t, err)
+			defer resp.Body.Close()
+
+			require.Equal(t, tt.want, resp.StatusCode)
+			switch tt.want {
+			case http.StatusTemporaryRedirect:
+				assert.Equal(t, cmp.Or(tt.location, tt.cred.Results+rpc), resp.Header.Get("Location"))
+			case http.StatusInternalServerError:
+				body := map[string]string{}
+				require.NoError(t, json.UnmarshalRead(resp.Body, &body))
+				assert.Equal(t, twirpInternal, body["code"])
+				assert.Contains(t, body["msg"], cmp.Or(tt.wantMsg, tt.cred.Results))
+			}
+		})
+	}
 }

act/artifactcache/s3_storage.go

@@ -0,0 +1,326 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifactcache
+
+import (
+	"bytes"
+	"cmp"
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/json/v2"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"maps"
+	"net/http"
+	"net/url"
+	"os"
+	"path"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// S3Options configures the bucket that stores completed cache entries.
+type S3Options struct {
+	Endpoint  string
+	Region    string
+	Bucket    string
+	Prefix    string
+	PathStyle *bool // nil uses virtual-hosted requests on AWS and path-style ones elsewhere
+	AccessKey string
+	SecretKey string
+}
+
+type cacheStorage interface {
+	Exist(uint64) (bool, error)
+	Write(uint64, int64, io.Reader) error
+	WriteBlock(uint64, string, io.Reader) error
+	OrderBlocks(uint64, []string) error
+	Commit(uint64, int64) (int64, error)
+	Serve(http.ResponseWriter, *http.Request, uint64)
+	Remove(uint64) error
+}
+
+const s3PartSize = 5 << 30 // the largest part S3 accepts
+
+// s3Storage stages uploads on disk and keeps completed entries and their metadata in a bucket.
+type s3Storage struct {
+	*Storage
+	client    *http.Client
+	bucketURL *url.URL
+	opts      S3Options
+}
+
+type s3Part struct {
+	PartNumber int
+	ETag       string
+}
+
+func newS3Storage(staging *Storage, opts S3Options) (*s3Storage, error) {
+	endpoint, err := url.Parse(opts.Endpoint)
+	if err != nil || endpoint.Host == "" || (endpoint.Scheme != "http" && endpoint.Scheme != "https") {
+		return nil, fmt.Errorf("invalid S3 endpoint %q", opts.Endpoint)
+	}
+	transport, _ := http.DefaultTransport.(*http.Transport)
+	transport = transport.Clone()
+	transport.ResponseHeaderTimeout = time.Minute // a stalled endpoint must not hold the store forever
+	pathStyle := !strings.HasSuffix(endpoint.Hostname(), ".amazonaws.com")
+	if opts.PathStyle != nil {
+		pathStyle = *opts.PathStyle
+	}
+	if pathStyle {
+		endpoint.Path = "/" + opts.Bucket
+	} else {
+		endpoint.Host = opts.Bucket + "." + endpoint.Host
+		endpoint.Path = "/"
+	}
+	opts.Region = cmp.Or(opts.Region, "us-east-1")
+	return &s3Storage{Storage: staging, client: &http.Client{Transport: transport}, bucketURL: endpoint, opts: opts}, nil
+}
+
+func (s *s3Storage) blobKey(id uint64) string {
+	return path.Join(s.opts.Prefix, "blobs", strconv.FormatUint(id, 10))
+}
+
+func (s *s3Storage) metadataDir() string {
+	return path.Join(s.opts.Prefix, "metadata") + "/"
+}
+
+func (s *s3Storage) metadataKey(id uint64) string {
+	return s.metadataDir() + strconv.FormatUint(id, 10) + ".json"
+}
+
+func (s *s3Storage) url(key string, query url.Values) *url.URL {
+	u := *s.bucketURL
+	u.Path = path.Join(u.Path, key)
+	u.RawPath = strings.NewReplacer("+", "%20", "%2F", "/").Replace(url.QueryEscape(u.Path)) // SigV4 encoding
+	u.RawQuery = strings.ReplaceAll(query.Encode(), "+", "%20")
+	return &u
+}
+
+// sign authorizes req with AWS Signature Version 4, leaving the payload unsigned so bodies can stream.
+// https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-header-based-auth.html
+func (s *s3Storage) sign(req *http.Request, now time.Time) {
+	date := now.UTC().Format("20060102T150405Z")
+	req.Header.Set("X-Amz-Date", date)
+	if req.Header.Get("X-Amz-Content-Sha256") == "" {
+		req.Header.Set("X-Amz-Content-Sha256", "UNSIGNED-PAYLOAD")
+	}
+	headers := map[string]string{"host": req.URL.Host}
+	for name, values := range req.Header {
+		if name = strings.ToLower(name); strings.HasPrefix(name, "x-amz-") {
+			headers[name] = strings.Join(values, ",")
+		}
+	}
+	names := slices.Sorted(maps.Keys(headers))
+	canonical := []string{req.Method, req.URL.EscapedPath(), req.URL.RawQuery}
+	for _, name := range names {
+		canonical = append(canonical, name+":"+headers[name])
+	}
+	canonical = append(canonical, "", strings.Join(names, ";"), req.Header.Get("X-Amz-Content-Sha256"))
+	scope := date[:8] + "/" + s.opts.Region + "/s3/aws4_request"
+	signature := []byte("AWS4" + s.opts.SecretKey)
+	for _, data := range []string{date[:8], s.opts.Region, "s3", "aws4_request", fmt.Sprintf("AWS4-HMAC-SHA256\n%s\n%s\n%x", date, scope, sha256.Sum256([]byte(strings.Join(canonical, "\n"))))} { // key derivation, the last round signs
+		mac := hmac.New(sha256.New, signature)
+		_, _ = mac.Write([]byte(data))
+		signature = mac.Sum(nil)
+	}
+	req.Header.Set("Authorization", fmt.Sprintf("AWS4-HMAC-SHA256 Credential=%s/%s,SignedHeaders=%s,Signature=%x", s.opts.AccessKey, scope, strings.Join(names, ";"), signature))
+}
+
+// do returns the response to a signed request when it succeeded, fs.ErrNotExist for a missing key.
+func (s *s3Storage) do(ctx context.Context, method, key string, query url.Values, header http.Header, body io.Reader) (*http.Response, error) {
+	var size int64
+	if sized, ok := body.(interface{ Size() int64 }); ok {
+		size = sized.Size()
+	}
+	if size == 0 {
+		body = nil
+	}
+	req, err := http.NewRequestWithContext(ctx, method, s.url(key, query).String(), body)
+	if err != nil {
+		return nil, err
+	}
+	req.ContentLength = size
+	maps.Copy(req.Header, header)
+	s.sign(req, time.Now())
+	resp, err := s.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode < http.StatusMultipleChoices {
+		return resp, nil
+	}
+	defer drain(resp)
+	var failure struct{ Code, Message string }
+	_ = xml.NewDecoder(resp.Body).Decode(&failure)
+	if resp.StatusCode == http.StatusNotFound && (failure.Code == "NoSuchKey" || failure.Code == "" && method == http.MethodHead) {
+		return nil, fs.ErrNotExist
+	}
+	return nil, fmt.Errorf("S3 %s %s: %s", method, key, cmp.Or(strings.TrimSpace(failure.Code+" "+failure.Message), resp.Status))
+}
+
+func (s *s3Storage) call(ctx context.Context, method, key string, query url.Values, body io.Reader, result any) (http.Header, error) {
+	resp, err := s.do(ctx, method, key, query, nil, body)
+	if err != nil {
+		return nil, err
+	}
+	defer drain(resp)
+	if result == nil {
+		return resp.Header, nil
+	}
+	return resp.Header, xml.NewDecoder(resp.Body).Decode(result)
+}
+
+// drain reads a response to its end before closing it, so its connection gets reused.
+func drain(resp *http.Response) {
+	_, _ = io.Copy(io.Discard, resp.Body)
+	_ = resp.Body.Close()
+}
+
+func (s *s3Storage) Exist(id uint64) (bool, error) {
+	_, err := s.call(context.Background(), http.MethodHead, s.blobKey(id), nil, nil, nil)
+	if errors.Is(err, fs.ErrNotExist) {
+		return false, nil
+	}
+	return err == nil, err
+}
+
+func (s *s3Storage) Commit(id uint64, size int64) (int64, error) {
+	written, err := s.Storage.Commit(id, size)
+	if err != nil {
+		return 0, err
+	}
+	defer func() { _ = s.Storage.Remove(id) }()
+	file, err := os.Open(s.filename(id))
+	if err != nil {
+		return 0, err
+	}
+	defer file.Close()
+	if err := s.upload(context.Background(), s.blobKey(id), file, written); err != nil {
+		return 0, fmt.Errorf("upload cache to S3: %w", err)
+	}
+	return written, nil
+}
+
+// upload always goes in parts, the only way S3 takes an object over 5 GiB.
+func (s *s3Storage) upload(ctx context.Context, key string, file io.ReaderAt, size int64) error {
+	var created struct {
+		UploadID string `xml:"UploadId"`
+	}
+	if _, err := s.call(ctx, http.MethodPost, key, url.Values{"uploads": {""}}, nil, &created); err != nil {
+		return err
+	}
+	var completion struct {
+		XMLName xml.Name `xml:"CompleteMultipartUpload"`
+		Parts   []s3Part `xml:"Part"`
+	}
+	for offset := int64(0); offset == 0 || offset < size; offset += s3PartSize {
+		number, length := len(completion.Parts)+1, min(s3PartSize, size-offset)
+		query := url.Values{"partNumber": {strconv.Itoa(number)}, "uploadId": {created.UploadID}}
+		header, err := s.call(ctx, http.MethodPut, key, query, io.NewSectionReader(file, offset, length), nil)
+		if err != nil {
+			return err
+		}
+		completion.Parts = append(completion.Parts, s3Part{number, header.Get("ETag")})
+	}
+	body, err := xml.Marshal(completion)
+	if err != nil {
+		return err
+	}
+	var result struct{ Code, Message string } // a completion can fail after its 200 status
+	if _, err := s.call(ctx, http.MethodPost, key, url.Values{"uploadId": {created.UploadID}}, bytes.NewReader(body), &result); err != nil {
+		return err
+	}
+	if result.Code != "" {
+		return fmt.Errorf("S3 complete upload %s: %s %s", key, result.Code, result.Message)
+	}
+	return nil
+}
+
+func (s *s3Storage) Serve(w http.ResponseWriter, r *http.Request, id uint64) {
+	header := http.Header{}
+	if byteRange := r.Header.Get("Range"); byteRange != "" {
+		header.Set("Range", byteRange)
+	}
+	resp, err := s.do(r.Context(), http.MethodGet, s.blobKey(id), nil, header, nil)
+	if errors.Is(err, fs.ErrNotExist) {
+		http.NotFound(w, r)
+		return
+	} else if err != nil {
+		http.Error(w, "read cache from S3", http.StatusBadGateway)
+		return
+	}
+	defer resp.Body.Close()
+	for _, name := range []string{"Content-Length", "Content-Range"} {
+		if value := resp.Header.Get(name); value != "" {
+			w.Header().Set(name, value)
+		}
+	}
+	w.WriteHeader(resp.StatusCode)
+	_, _ = io.Copy(w, resp.Body)
+}
+
+// Remove unpublishes an entry before deleting its blob, so no runner imports it without its bytes.
+func (s *s3Storage) Remove(id uint64) error {
+	for _, key := range []string{s.metadataKey(id), s.blobKey(id)} {
+		if _, err := s.call(context.Background(), http.MethodDelete, key, nil, nil, nil); err != nil && !errors.Is(err, fs.ErrNotExist) {
+			return fmt.Errorf("remove %s from S3: %w", key, err)
+		}
+	}
+	return s.Storage.Remove(id)
+}
+
+func (s *s3Storage) publish(cache *Cache) error {
+	data, err := json.Marshal(cache)
+	if err != nil {
+		return err
+	}
+	if _, err := s.call(context.Background(), http.MethodPut, s.metadataKey(cache.ID), nil, bytes.NewReader(data), nil); err != nil {
+		return fmt.Errorf("publish cache to S3: %w", err)
+	}
+	return nil
+}
+
+func (s *s3Storage) published(ctx context.Context) (map[uint64]bool, error) {
+	ids := make(map[uint64]bool)
+	query := url.Values{"list-type": {"2"}, "prefix": {s.metadataDir()}}
+	for {
+		var page struct {
+			Contents              []struct{ Key string }
+			IsTruncated           bool
+			NextContinuationToken string
+		}
+		if _, err := s.call(ctx, http.MethodGet, "", query, nil, &page); err != nil {
+			return nil, fmt.Errorf("list S3 cache metadata: %w", err)
+		}
+		for _, object := range page.Contents {
+			if id, err := strconv.ParseUint(strings.TrimSuffix(strings.TrimPrefix(object.Key, s.metadataDir()), ".json"), 10, 64); err == nil {
+				ids[id] = true
+			}
+		}
+		if !page.IsTruncated {
+			return ids, nil
+		}
+		query.Set("continuation-token", page.NextContinuationToken)
+	}
+}
+
+func (s *s3Storage) fetch(ctx context.Context, id uint64) (*Cache, error) {
+	resp, err := s.do(ctx, http.MethodGet, s.metadataKey(id), nil, nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	cache := &Cache{}
+	if err := json.UnmarshalRead(resp.Body, cache); err != nil {
+		return nil, fmt.Errorf("read S3 cache metadata %d: %w", id, err)
+	}
+	return cache, nil
+}

act/artifactcache/s3_storage_test.go

@@ -0,0 +1,46 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifactcache
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/johannesboyne/gofakes3"
+	"github.com/johannesboyne/gofakes3/backend/s3mem"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestHandler_S3SharesEntriesAndDropsExpiredOnes(t *testing.T) {
+	backend := s3mem.New()
+	require.NoError(t, backend.CreateBucket("cache"))
+	server := httptest.NewServer(gofakes3.New(backend).Server())
+	t.Cleanup(server.Close)
+	opts := Options{S3: &S3Options{Endpoint: server.URL, Bucket: "cache", Prefix: "runners", AccessKey: "key", SecretKey: "secret"}}
+	saver, restorer := startTestHandler(t, opts), startTestHandler(t, opts)
+	entry := map[string]any{"key": "deps", "version": "v1"}
+
+	finalized, _ := saveV2(t, saver, "deps", "v1", []byte("archive"))
+	require.Equal(t, true, finalized["ok"])
+	require.NoError(t, restorer.importMetadata(t.Context()))
+	found := v2Call(t, restorer, testClient, "GetCacheEntryDownloadURL", entry)
+	require.Equal(t, true, found["ok"])
+	assert.Equal(t, []byte("archive"), getURL(t, found["signed_download_url"].(string)))
+
+	require.NoError(t, backend.ForceDeleteBucket("cache"))
+	require.NoError(t, backend.CreateBucket("cache"))
+	require.NoError(t, restorer.importMetadata(t.Context()))
+	assert.Equal(t, true, v2Call(t, restorer, testClient, "CreateCacheEntry", entry)["ok"])
+}
+
+func TestS3StorageSignsLikeAWS(t *testing.T) {
+	storage := &s3Storage{opts: S3Options{Region: "us-east-1", AccessKey: "AKIAIOSFODNN7EXAMPLE", SecretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}
+	req := httptest.NewRequest(http.MethodGet, "https://examplebucket.s3.amazonaws.com/?max-keys=2&prefix=J", nil)
+	req.Header.Set("X-Amz-Content-Sha256", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
+	storage.sign(req, time.Date(2013, 5, 24, 0, 0, 0, 0, time.UTC))
+	assert.Equal(t, "AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7", req.Header.Get("Authorization"))
+}

act/artifactcache/storage.go

@@ -5,8 +5,10 @@
 package artifactcache
 
 import (
+	"bytes"
 	"crypto/sha256"
 	"encoding/hex"
+	"encoding/json/v2"
 	"fmt"
 	"io"
 	"net/http"
@@ -66,6 +68,18 @@ func (s *Storage) WriteBlock(id uint64, blockID string, reader io.Reader) error
 // 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 {
+	wanted, err := json.Marshal(blockIDs) // a block id is client-chosen, so it cannot be a separator
+	if err != nil {
+		return err
+	}
+	list := filepath.Join(s.tempDir(id), blockFilePrefix+"list")
+	if recorded, err := os.ReadFile(list); err == nil {
+		// A retry repeats the list it already sent; another one would reorder what is now staged.
+		if !bytes.Equal(recorded, wanted) {
+			return fmt.Errorf("cache %d was already assembled from a different block list", id)
+		}
+		return nil
+	}
 	for i, blockID := range blockIDs {
 		if err := os.Rename(s.blockName(id, blockID), s.tempName(id, int64(i))); err != nil {
 			if os.IsNotExist(err) {
@@ -74,7 +88,7 @@ func (s *Storage) OrderBlocks(id uint64, blockIDs []string) error {
 			return err
 		}
 	}
-	return nil
+	return os.WriteFile(list, wanted, 0o600)
 }
 
 func (s *Storage) Commit(id uint64, size int64) (int64, error) {

act/artifacts/server.go

@@ -11,6 +11,7 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"net"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -220,14 +221,14 @@ func Serve(ctx context.Context, artifactPath, addr, port string) context.CancelF
 	downloads(router, artifactPath)
 
 	server := &http.Server{
-		Addr:              fmt.Sprintf("%s:%s", addr, port),
+		Addr:              net.JoinHostPort(addr, port),
 		ReadHeaderTimeout: 2 * time.Second,
 		Handler:           router,
 	}
 
 	// run server
 	go func() {
-		logger.Infof("Start server on http://%s:%s", addr, port)
+		logger.Infof("Start server on http://%s", server.Addr)
 		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 			logger.Fatal(err)
 		}

act/common/git/git.go

@@ -9,11 +9,13 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	nethttp "net/http"
 	"os"
 	"path"
 	"regexp"
 	"strings"
 	"sync"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 	"gitea.com/gitea/runner/internal/pkg/lock"
@@ -22,6 +24,8 @@ import (
 	"github.com/go-git/go-git/v5/config"
 	"github.com/go-git/go-git/v5/plumbing"
 	"github.com/go-git/go-git/v5/plumbing/storer"
+	"github.com/go-git/go-git/v5/plumbing/transport"
+	"github.com/go-git/go-git/v5/plumbing/transport/client"
 	"github.com/go-git/go-git/v5/plumbing/transport/http"
 	"github.com/mattn/go-isatty"
 	log "github.com/sirupsen/logrus"
@@ -38,6 +42,20 @@ var (
 	ErrShortRef = errors.New("short SHA references are not supported")
 )
 
+func init() {
+	httpClient := newHTTPClient(&nethttp.HTTP2Config{SendPingTimeout: 30 * time.Second})
+	client.InstallProtocol("http", httpClient)
+	client.InstallProtocol("https", httpClient)
+}
+
+// newHTTPClient pings idle HTTP/2 connections to drop stalled ones.
+func newHTTPClient(h2 *nethttp.HTTP2Config) transport.Transport {
+	defaultTransport, _ := nethttp.DefaultTransport.(*nethttp.Transport)
+	httpTransport := defaultTransport.Clone()
+	httpTransport.HTTP2 = h2
+	return http.NewClient(&nethttp.Client{Transport: httpTransport})
+}
+
 // AcquireCloneLock returns an unlock function after locking the per-directory mutex for dir.
 // Only concurrent operations targeting the same directory are serialized; clones into different directories run in parallel.
 // Callers reading files inside dir (e.g. tarring a checked-out action into a job container) must hold this lock too,
@@ -325,33 +343,6 @@ func CloneIfRequired(ctx context.Context, refName plumbing.ReferenceName, input
 	return r, false, nil
 }
 
-func gitOptions(token string) (fetchOptions git.FetchOptions, pullOptions git.PullOptions) {
-	fetchOptions.RefSpecs = []config.RefSpec{"refs/*:refs/*", "HEAD:refs/heads/HEAD"}
-	fetchOptions.Force = true
-	pullOptions.Force = true
-
-	if token != "" {
-		auth := &http.BasicAuth{
-			Username: "token",
-			Password: token,
-		}
-		fetchOptions.Auth = auth
-		pullOptions.Auth = auth
-	}
-
-	return fetchOptions, pullOptions
-}
-
-// staleRefreshErr reports why a failed refresh must abort: the resolve and
-// checkout that follow are local and succeed on a cancelled context, which
-// would hand back the cached revision as if it were fresh.
-func staleRefreshErr(ctx context.Context, err error) error {
-	if err == nil || errors.Is(err, git.NoErrAlreadyUpToDate) {
-		return nil
-	}
-	return ctx.Err()
-}
-
 // NewGitCloneExecutor creates an executor to clone git repos
 func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
@@ -373,25 +364,34 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 
 		isOfflineMode := input.OfflineMode
 
-		// fetch latest changes
-		fetchOptions, pullOptions := gitOptions(input.Token)
-
-		if input.InsecureSkipTLS { // For Gitea
-			fetchOptions.InsecureSkipTLS = true
-			pullOptions.InsecureSkipTLS = true
+		fetchOptions := git.FetchOptions{
+			RefSpecs:        []config.RefSpec{"refs/*:refs/*", "HEAD:refs/heads/HEAD", "refs/heads/*:refs/remotes/origin/*"},
+			Force:           true,
+			InsecureSkipTLS: input.InsecureSkipTLS,
+		}
+		if input.Token != "" {
+			fetchOptions.Auth = &http.BasicAuth{
+				Username: "token",
+				Password: input.Token,
+			}
 		}
 
 		// Action clones only ever need the tip commit, so keep a shallow cache cheap on update at depth 1 regardless of its original depth
 		// Turning action_shallow_clone off does not convert an existing shallow cache; evict it for a full clone.
-		shallow := isShallow(r)
-		if shallow {
+		if isShallow(r) {
 			fetchOptions.Depth = 1
 			if spec, ok := shallowFetchRefSpec(r, input.Ref); ok {
 				fetchOptions.RefSpecs = []config.RefSpec{spec}
 			}
 		}
 
-		if !isOfflineMode {
+		// A just-cloned ref is as current as a fetch would make it, and a commit hash never moves.
+		// TODO: revalidate a mutable ref with a conditional archive request instead, once every
+		// supported Gitea sends an ETag for them: https://github.com/go-gitea/gitea/pull/39289
+		_, present := refRevision(r, input.Ref)
+		refresh := !isOfflineMode && (!present || (reused && !plumbing.IsHash(input.Ref)))
+
+		if refresh {
 			err = r.FetchContext(ctx, &fetchOptions)
 			if err != nil && !errors.Is(err, git.NoErrAlreadyUpToDate) {
 				return err
@@ -411,23 +411,7 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 			}
 		}
 
-		// At this point we need to know if it's a tag or a branch
-		// And the easiest way to do it is duck typing
-		//
-		// If err is nil, it's a tag so let's proceed with that hash like we would if
-		// it was a sha
-		refType := "tag"
-		rev = plumbing.Revision(path.Join("refs", "tags", input.Ref))
-		if _, err := r.Tag(input.Ref); errors.Is(err, git.ErrTagNotFound) {
-			rName := plumbing.ReferenceName(path.Join("refs", "remotes", "origin", input.Ref))
-			if _, err := r.Reference(rName, false); errors.Is(err, plumbing.ErrReferenceNotFound) {
-				refType = "sha"
-				rev = plumbing.Revision(input.Ref)
-			} else {
-				refType = "branch"
-				rev = plumbing.Revision(rName)
-			}
-		}
+		rev, _ = refRevision(r, input.Ref)
 
 		if hash, err = r.ResolveRevision(rev); err != nil {
 			logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
@@ -439,47 +423,13 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 			return err
 		}
 
-		// If the hash resolved doesn't match the ref provided in a workflow then we're
-		// using a branch or tag ref, not a sha
-		//
-		// Repos on disk point to commit hashes, and need to checkout input.Ref before
-		// we try and pull down any changes
-		if hash.String() != input.Ref && refType == "branch" {
-			logger.Debugf("Provided ref is not a sha. Checking out branch before pulling changes")
-			sourceRef := plumbing.ReferenceName(path.Join("refs", "remotes", "origin", input.Ref))
-			if err = w.Checkout(&git.CheckoutOptions{
-				Branch: sourceRef,
-				Force:  true,
-			}); err != nil {
-				logger.Errorf("Unable to checkout %s: %v", sourceRef, err)
-				return err
-			}
-		}
-
 		reusedMsg := ""
-
-		switch {
-		case !isOfflineMode && !shallow:
-			// In shallow mode the depth-limited fetch above already advanced the ref.
-			if err = w.PullContext(ctx, &pullOptions); err != nil && !errors.Is(err, git.NoErrAlreadyUpToDate) {
-				logger.Debugf("Unable to pull %s: %v", refName, err)
-			}
-			if err := staleRefreshErr(ctx, err); err != nil {
-				return err
-			}
-		case isOfflineMode && reused:
+		if isOfflineMode && reused {
 			reusedMsg = " (reused in offline mode)"
 		}
 
 		logger.Debugf("Cloned %s to %s%s", input.URL, input.Dir, reusedMsg)
 
-		if hash.String() != input.Ref && refType == "branch" {
-			logger.Debugf("Provided ref is not a sha. Updating branch ref after pull")
-			if hash, err = r.ResolveRevision(rev); err != nil {
-				logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
-				return err
-			}
-		}
 		if err = w.Checkout(&git.CheckoutOptions{
 			Hash:  *hash,
 			Force: true,
@@ -488,40 +438,43 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 			return err
 		}
 
-		if err = w.Reset(&git.ResetOptions{
-			Mode:   git.HardReset,
-			Commit: *hash,
-		}); err != nil {
-			logger.Errorf("Unable to reset to %s: %v", hash.String(), err)
-			return err
-		}
-
 		logger.Debugf("Checked out %s", input.Ref)
 		return nil
 	}
 }
 
-// cloneAtDepth clones input.URL into input.Dir using opts.
-// With input.Depth > 0 it first tries a shallow, single-branch clone of input.Ref, falling back when error.
+// cloneAtDepth falls back to a full clone when the shallow attempt fails.
 func cloneAtDepth(ctx context.Context, input NewGitCloneExecutorInput, opts git.CloneOptions, logger log.FieldLogger) (*git.Repository, error) {
 	if input.Depth > 0 {
-		for _, refName := range []plumbing.ReferenceName{
-			plumbing.NewBranchReferenceName(input.Ref),
-			plumbing.NewTagReferenceName(input.Ref),
-		} {
-			shallowOpts := opts
-			shallowOpts.Depth = input.Depth
-			shallowOpts.SingleBranch = true
-			shallowOpts.ReferenceName = refName
-			shallowOpts.Tags = git.NoTags
-
-			r, err := git.PlainCloneContext(ctx, input.Dir, false, &shallowOpts)
+		if plumbing.IsHash(input.Ref) {
+			r, err := fetchPinnedSHA(ctx, input, opts)
 			if err == nil {
 				return r, nil
 			}
-			logger.Debugf("Shallow clone of %s as %s failed: %v", input.URL, refName, err)
-			if rmErr := os.RemoveAll(input.Dir); rmErr != nil {
-				return nil, fmt.Errorf("remove partial clone %s: %w", input.Dir, rmErr)
+			logger.Debugf("Shallow fetch of %s at %s failed: %v", input.URL, input.Ref, err)
+			if err := removePartialClone(input.Dir); err != nil {
+				return nil, err
+			}
+		} else {
+			refNames := []plumbing.ReferenceName{plumbing.NewBranchReferenceName(input.Ref), plumbing.NewTagReferenceName(input.Ref)}
+			if input.Ref == plumbing.HEAD.String() || strings.HasPrefix(input.Ref, "refs/") {
+				refNames = []plumbing.ReferenceName{plumbing.ReferenceName(input.Ref)} // HEAD is the remote's default branch
+			}
+			for _, refName := range refNames {
+				shallowOpts := opts
+				shallowOpts.Depth = input.Depth
+				shallowOpts.SingleBranch = true
+				shallowOpts.ReferenceName = refName
+				shallowOpts.Tags = git.NoTags
+
+				r, err := git.PlainCloneContext(ctx, input.Dir, false, &shallowOpts)
+				if err == nil {
+					return r, nil
+				}
+				logger.Debugf("Shallow clone of %s as %s failed: %v", input.URL, refName, err)
+				if err := removePartialClone(input.Dir); err != nil {
+					return nil, err
+				}
 			}
 		}
 		logger.Debugf("Falling back to a full clone of %s for ref %q", input.URL, input.Ref)
@@ -530,14 +483,65 @@ func cloneAtDepth(ctx context.Context, input NewGitCloneExecutorInput, opts git.
 	return git.PlainCloneContext(ctx, input.Dir, false, &opts)
 }
 
+func removePartialClone(dir string) error {
+	if err := os.RemoveAll(dir); err != nil {
+		return fmt.Errorf("remove partial clone %s: %w", dir, err)
+	}
+	return nil
+}
+
+func fetchPinnedSHA(ctx context.Context, input NewGitCloneExecutorInput, opts git.CloneOptions) (*git.Repository, error) {
+	r, err := git.PlainInit(input.Dir, false)
+	if err != nil {
+		return nil, err
+	}
+	if _, err := r.CreateRemote(&config.RemoteConfig{Name: "origin", URLs: []string{input.URL}}); err != nil {
+		return nil, err
+	}
+	if err := r.FetchContext(ctx, &git.FetchOptions{
+		RefSpecs:        []config.RefSpec{pinnedRefSpec(input.Ref)},
+		Depth:           input.Depth,
+		Tags:            git.NoTags,
+		Auth:            opts.Auth,
+		Progress:        opts.Progress,
+		InsecureSkipTLS: opts.InsecureSkipTLS,
+	}); err != nil {
+		return nil, err
+	}
+	return r, nil
+}
+
+// pinnedRefSpec keeps a hash-shaped name out of refs/heads and refs/tags.
+func pinnedRefSpec(sha string) config.RefSpec {
+	return config.RefSpec(fmt.Sprintf("+%s:refs/pinned/%s", sha, sha))
+}
+
+// refRevision picks the revision to check out and reports whether it resolves locally.
+func refRevision(r *git.Repository, ref string) (plumbing.Revision, bool) {
+	if plumbing.IsHash(ref) {
+		// git ignores a ref named as 40 hex digits, so a full hash always denotes the commit itself.
+		_, err := r.CommitObject(plumbing.NewHash(ref))
+		return plumbing.Revision(ref), err == nil
+	}
+	if _, err := r.Tag(ref); err == nil {
+		return plumbing.Revision(path.Join("refs", "tags", ref)), true
+	}
+	remoteRef := plumbing.ReferenceName(path.Join("refs", "remotes", "origin", ref))
+	if _, err := r.Reference(remoteRef, false); err == nil {
+		return plumbing.Revision(remoteRef), true
+	}
+	rev := plumbing.Revision(ref)
+	_, err := r.ResolveRevision(rev)
+	return rev, err == nil
+}
+
 // isShallow reports whether the local repository was cloned with a limited depth.
 func isShallow(r *git.Repository) bool {
 	shallows, err := r.Storer.Shallow()
 	return err == nil && len(shallows) > 0
 }
 
-// shallowFetchRefSpec returns the single refspec that updates only input.Ref, keeping a shallow clone from re-downloading every branch's history.
-// ok is false when the ref is not present locally as a tag or remote-tracking branch, in which case the broad default refspec is used.
+// shallowFetchRefSpec limits a shallow update to the requested ref, falling back to the broad refspec when it is not present locally.
 func shallowFetchRefSpec(r *git.Repository, ref string) (config.RefSpec, bool) {
 	tagRef := plumbing.NewTagReferenceName(ref)
 	if _, err := r.Reference(tagRef, false); err == nil {
@@ -548,5 +552,9 @@ func shallowFetchRefSpec(r *git.Repository, ref string) (config.RefSpec, bool) {
 		branchRef := plumbing.NewBranchReferenceName(ref)
 		return config.RefSpec(fmt.Sprintf("+%s:%s", branchRef, remoteRef)), true
 	}
+	if plumbing.IsHash(ref) {
+		// The broad refspec carries only advertised tips, never a pinned commit.
+		return pinnedRefSpec(ref), true
+	}
 	return "", false
 }

act/common/git/git_test.go

@@ -6,8 +6,9 @@ package git
 
 import (
 	"context"
-	"errors"
+	"crypto/tls"
 	"fmt"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -16,6 +17,7 @@ import (
 	"strconv"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"syscall"
 	"testing"
 	"time"
@@ -24,6 +26,9 @@ import (
 
 	gogit "github.com/go-git/go-git/v5"
 	gogitconfig "github.com/go-git/go-git/v5/config"
+	"github.com/go-git/go-git/v5/plumbing/transport"
+	gogitclient "github.com/go-git/go-git/v5/plumbing/transport/client"
+	gogitfile "github.com/go-git/go-git/v5/plumbing/transport/file"
 	log "github.com/sirupsen/logrus"
 	logrustest "github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
@@ -435,7 +440,7 @@ func TestGitCloneExecutorShallow(t *testing.T) {
 		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", m))
 	}
 	require.NoError(t, gitCmd("-C", workDir, "tag", "v1"))
-	sha := gitRevParse(t, workDir, "HEAD~1") // c2, a SHA that go-git cannot shallow-clone
+	unadvertisedSHA := gitRevParse(t, workDir, "HEAD~1")
 	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
 	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "v1"))
 
@@ -461,14 +466,43 @@ func TestGitCloneExecutorShallow(t *testing.T) {
 		assert.Equal(t, "c3", gitHeadSubject(t, dir))
 	})
 
-	t.Run("SHA falls back to a full clone", func(t *testing.T) {
+	unadvertisedRemote := func(t *testing.T, allowUnadvertised bool) string {
+		remote := filepath.Join(t.TempDir(), "remote.git")
+		require.NoError(t, gitCmd("clone", "--bare", remoteDir, remote))
+		require.NoError(t, gitCmd("-C", remote, "config", "uploadpack.allowAnySHA1InWant", strconv.FormatBool(allowUnadvertised)))
+		return remote
+	}
+
+	t.Run("commit hash falls back to a full clone when the remote refuses unadvertised objects", func(t *testing.T) {
 		dir := t.TempDir()
 		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
-			URL: remoteDir, Ref: sha, Dir: dir, Depth: 1,
+			URL: unadvertisedRemote(t, false), Ref: unadvertisedSHA, Dir: dir, Depth: 1,
 		})(t.Context()))
-		// go-git cannot shallow-clone a raw SHA, so it falls back to a full clone; the absence of a shallow marker proves the fallback happened.
-		assert.NoFileExists(t, shallowMarker(dir), "a SHA ref must not produce a shallow clone")
-		assert.Equal(t, sha, gitRevParse(t, dir, "HEAD"))
+		assert.NoFileExists(t, shallowMarker(dir))
+		assert.Equal(t, unadvertisedSHA, gitRevParse(t, dir, "HEAD"))
+	})
+
+	t.Run("commit hash is fetched shallowly, moved to another hash, then reused without reaching the remote", func(t *testing.T) {
+		remote := unadvertisedRemote(t, true)
+		dir := t.TempDir()
+		cloneAt := func(ref string) error {
+			return NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: remote, Ref: ref, Dir: dir, Depth: 1,
+			})(t.Context())
+		}
+
+		require.NoError(t, cloneAt(unadvertisedSHA))
+		assert.FileExists(t, shallowMarker(dir))
+		assert.Equal(t, 1, gitRevCount(t, dir))
+		assert.Equal(t, unadvertisedSHA, gitRevParse(t, dir, "HEAD"))
+
+		olderSHA := gitRevParse(t, workDir, "HEAD~2")
+		require.NoError(t, cloneAt(olderSHA))
+		assert.Equal(t, olderSHA, gitRevParse(t, dir, "HEAD"))
+
+		require.NoError(t, os.RemoveAll(remote))
+		require.NoError(t, cloneAt(olderSHA))
+		assert.Equal(t, olderSHA, gitRevParse(t, dir, "HEAD"))
 	})
 
 	t.Run("moving branch updates while staying shallow", func(t *testing.T) {
@@ -491,6 +525,98 @@ func TestGitCloneExecutorShallow(t *testing.T) {
 	})
 }
 
+func TestGitCloneExecutorTransportSessions(t *testing.T) {
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--initial-branch=main", workDir))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "c1"))
+	require.NoError(t, gitCmd("-C", workDir, "tag", "v1"))
+	require.NoError(t, gitCmd("-C", workDir, "tag", "-a", "v2", "-m", "v2"))
+
+	for name, tt := range map[string]struct {
+		Ref   string
+		Depth int
+	}{
+		"shallow branch":       {"main", 1},
+		"full clone branch":    {"main", 0},
+		"full lightweight tag": {"v1", 0},
+		"full annotated tag":   {"v2", 0},
+	} {
+		t.Run(name, func(t *testing.T) {
+			counter := installCountingTransport(t)
+			dir := t.TempDir()
+			clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: workDir, Ref: tt.Ref, Dir: dir, Depth: tt.Depth,
+			})
+			require.NoError(t, clone(t.Context()))
+			assert.Equal(t, int64(1), counter.sessions.Swap(0), "cold clone")
+			assert.Equal(t, gitRevParse(t, workDir, tt.Ref+"^{commit}"), gitRevParse(t, dir, "HEAD"))
+
+			require.NoError(t, clone(t.Context()))
+			assert.Equal(t, int64(1), counter.sessions.Swap(0), "unchanged warm cache")
+
+			require.NoError(t, os.WriteFile(filepath.Join(workDir, "action.yml"), []byte(name), 0o644))
+			require.NoError(t, gitCmd("-C", workDir, "add", "action.yml"))
+			require.NoError(t, gitCmd("-C", workDir, "commit", "-m", name))
+			require.NoError(t, gitCmd("-C", workDir, "tag", "--force", "v1"))
+			require.NoError(t, gitCmd("-C", workDir, "tag", "--force", "-a", "v2", "-m", "v2"))
+
+			require.NoError(t, os.WriteFile(filepath.Join(dir, "action.yml"), []byte("staged"), 0o644))
+			require.NoError(t, gitCmd("-C", dir, "add", "action.yml"))
+			require.NoError(t, os.WriteFile(filepath.Join(dir, "action.yml"), []byte("unstaged"), 0o644))
+
+			require.NoError(t, clone(t.Context()))
+			assert.Equal(t, int64(1), counter.sessions.Load(), "updated warm cache")
+			assert.Equal(t, gitRevParse(t, workDir, "HEAD"), gitRevParse(t, dir, "HEAD"))
+			status, err := exec.Command("git", "-C", dir, "status", "--porcelain").Output()
+			require.NoError(t, err)
+			assert.Empty(t, string(status))
+		})
+	}
+}
+
+func TestGitCloneExecutorPinnedHashIgnoresShadowingRef(t *testing.T) {
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "pinned"))
+	pinned := gitRevParse(t, workDir, "HEAD")
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "decoy"))
+	require.NoError(t, gitCmd("-C", workDir, "tag", pinned))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", pinned))
+
+	for name, depth := range map[string]int{"shallow": 1, "full clone": 0} {
+		t.Run(name, func(t *testing.T) {
+			dir := t.TempDir()
+			require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: remoteDir, Ref: pinned, Dir: dir, Depth: depth,
+			})(t.Context()))
+			assert.Equal(t, pinned, gitRevParse(t, dir, "HEAD"))
+		})
+	}
+}
+
+type countingTransport struct {
+	transport.Transport
+	sessions atomic.Int64
+}
+
+func (c *countingTransport) NewUploadPackSession(ep *transport.Endpoint, auth transport.AuthMethod) (transport.UploadPackSession, error) {
+	c.sessions.Add(1)
+	return c.Transport.NewUploadPackSession(ep, auth)
+}
+
+func installCountingTransport(t *testing.T) *countingTransport {
+	t.Helper()
+	counter := &countingTransport{Transport: gogitfile.DefaultClient}
+	gogitclient.InstallProtocol("file", counter)
+	t.Cleanup(func() { gogitclient.InstallProtocol("file", gogitfile.DefaultClient) })
+
+	return counter
+}
+
 func gitRevParse(t *testing.T, dir, rev string) string {
 	t.Helper()
 	out, err := exec.Command("git", "-C", dir, "rev-parse", rev).Output()
@@ -633,11 +759,24 @@ func TestNewGitCloneExecutorFetchHonoursContext(t *testing.T) {
 	}
 }
 
-func TestStaleRefreshErr(t *testing.T) {
-	ctx, cancel := context.WithCancel(t.Context())
-	require.NoError(t, staleRefreshErr(ctx, errors.New("remote hung up")))
+func TestNewGitCloneExecutorFailsOnSilentHTTP2Connection(t *testing.T) {
+	server := httptest.NewUnstartedServer(nil)
+	server.EnableHTTP2 = true
+	server.Config.TLSNextProto = map[string]func(*http.Server, *tls.Conn, http.Handler){
+		"h2": func(_ *http.Server, conn *tls.Conn, _ http.Handler) { _, _ = io.Copy(io.Discard, conn) },
+	}
+	server.StartTLS()
+	t.Cleanup(server.Close)
 
-	cancel()
-	require.ErrorIs(t, staleRefreshErr(ctx, errors.New("remote hung up")), context.Canceled)
-	require.NoError(t, staleRefreshErr(ctx, gogit.NoErrAlreadyUpToDate))
+	previous := gogitclient.Protocols["https"]
+	gogitclient.InstallProtocol("https", newHTTPClient(&http.HTTP2Config{SendPingTimeout: 50 * time.Millisecond, PingTimeout: 50 * time.Millisecond}))
+	t.Cleanup(func() { gogitclient.InstallProtocol("https", previous) })
+
+	ctx, cancel := context.WithTimeout(t.Context(), 10*time.Second)
+	defer cancel()
+	err := NewGitCloneExecutor(NewGitCloneExecutorInput{
+		URL: server.URL + "/action", Ref: "main", Dir: filepath.Join(t.TempDir(), "action"), InsecureSkipTLS: true,
+	})(ctx)
+	require.Error(t, err)
+	require.NoError(t, ctx.Err())
 }

act/common/outbound_ip.go

@@ -10,6 +10,11 @@ import (
 	"strings"
 )
 
+type interfaceIP struct {
+	net.IP
+	net.Interface
+}
+
 // GetOutboundIP returns an outbound IP address of this machine.
 // It tries to access the internet and returns the local IP address of the connection.
 // If the machine cannot access the internet, it returns a preferred IP address from network interfaces.
@@ -26,11 +31,7 @@ func GetOutboundIP() net.IP {
 
 	// So the machine cannot access the internet. Pick an IP address from network interfaces.
 	if ifs, err := net.Interfaces(); err == nil {
-		type IP struct {
-			net.IP
-			net.Interface
-		}
-		var ips []IP
+		var ips []interfaceIP
 		for _, i := range ifs {
 			if addrs, err := i.Addrs(); err == nil {
 				for _, addr := range addrs {
@@ -42,40 +43,45 @@ func GetOutboundIP() net.IP {
 						ip = v.IP
 					}
 					if ip.IsGlobalUnicast() {
-						ips = append(ips, IP{ip, i})
+						ips = append(ips, interfaceIP{ip, i})
 					}
 				}
 			}
 		}
-		if len(ips) > 1 {
-			sort.Slice(ips, func(i, j int) bool {
-				ifi := ips[i].Interface
-				ifj := ips[j].Interface
-
-				// ethernet is preferred
-				if vi, vj := strings.HasPrefix(ifi.Name, "e"), strings.HasPrefix(ifj.Name, "e"); vi != vj {
-					return vi
-				}
-
-				ipi := ips[i].IP
-				ipj := ips[j].IP
-
-				// IPv4 is preferred
-				if vi, vj := ipi.To4() != nil, ipj.To4() != nil; vi != vj {
-					return vi
-				}
-
-				// en0 is preferred to en1
-				if ifi.Name != ifj.Name {
-					return ifi.Name < ifj.Name
-				}
-
-				// fallback
-				return ipi.String() < ipj.String()
-			})
-			return ips[0].IP
-		}
+		return preferredIP(ips)
 	}
 
 	return nil
 }
+
+func preferredIP(ips []interfaceIP) net.IP {
+	if len(ips) == 0 {
+		return nil
+	}
+	sort.Slice(ips, func(i, j int) bool {
+		ifi := ips[i].Interface
+		ifj := ips[j].Interface
+
+		// ethernet is preferred
+		if vi, vj := strings.HasPrefix(ifi.Name, "e"), strings.HasPrefix(ifj.Name, "e"); vi != vj {
+			return vi
+		}
+
+		ipi := ips[i].IP
+		ipj := ips[j].IP
+
+		// IPv4 is preferred
+		if vi, vj := ipi.To4() != nil, ipj.To4() != nil; vi != vj {
+			return vi
+		}
+
+		// en0 is preferred to en1
+		if ifi.Name != ifj.Name {
+			return ifi.Name < ifj.Name
+		}
+
+		// fallback
+		return ipi.String() < ipj.String()
+	})
+	return ips[0].IP
+}

act/common/outbound_ip_test.go

@@ -0,0 +1,20 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"net"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPreferredIP(t *testing.T) {
+	assert.Nil(t, preferredIP(nil))
+	assert.Equal(t, net.ParseIP("2001:db8::1"), preferredIP([]interfaceIP{{IP: net.ParseIP("2001:db8::1")}}))
+	assert.Equal(t, net.ParseIP("2001:db8::1"), preferredIP([]interfaceIP{
+		{IP: net.ParseIP("192.0.2.1"), Name: "wlan0"},
+		{IP: net.ParseIP("2001:db8::1"), Name: "eth0"},
+	}))
+}

act/container/container_types.go

@@ -9,6 +9,10 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"path"
+	"strings"
+	"sync"
+	"sync/atomic"
 
 	"gitea.com/gitea/runner/act/common"
 
@@ -71,10 +75,31 @@ const (
 	HealthUnhealthy = string(container.Unhealthy)
 )
 
+// marks what a runner creates for its jobs, telling its leftovers from another runner's
+const runnerUUIDLabel = "com.gitea.runner.uuid"
+
 // ErrContainerNotFound reports a container the daemon no longer knows. Its text is a
 // fragment, missingContainerError composes it into the message every operation shares.
 var ErrContainerNotFound = errors.New("does not exist")
 
+// DockerProxy is a job's docker socket, fronting the daemon's for the job's lifetime.
+type DockerProxy struct {
+	Socket    string
+	close     func(context.Context) error
+	closeOnce sync.Once
+	closeErr  error
+	mounts    atomic.Value
+}
+
+func (p *DockerProxy) SetMounts(mounts map[string]string) {
+	p.mounts.Store(mounts)
+}
+
+func (p *DockerProxy) Close(ctx context.Context) error {
+	p.closeOnce.Do(func() { p.closeErr = p.close(ctx) })
+	return p.closeErr
+}
+
 // Info is a snapshot of a container, as of one inspect.
 type Info struct {
 	ID       string
@@ -84,13 +109,24 @@ type Info struct {
 	// HealthOutput is the last healthcheck probe's output.
 	HealthOutput string
 	Ports        map[string]string // container port ("5432") to the host port it is published on
+	Mounts       map[string]string // container path to its source on the daemon
+}
+
+// DaemonPath maps target to its daemon path through the nearest mount with a source, empty without one.
+func (info *Info) DaemonPath(target string) string {
+	for dir := target; dir != "/" && dir != "."; dir = path.Dir(dir) {
+		if source := info.Mounts[dir]; source != "" {
+			return path.Join(source, strings.TrimPrefix(target, dir))
+		}
+	}
+	return ""
 }
 
 // Container for managing docker run containers
 type Container interface {
 	Create(capAdd, capDrop []string) common.Executor
 	Copy(destPath string, files ...*FileEntry) common.Executor
-	CopyDir(destPath, srcPath string, useGitIgnore bool) common.Executor
+	CopyDir(destPath, srcPath string, useGitIgnore, skipGitDir bool) common.Executor
 	GetContainerArchive(ctx context.Context, srcPath string) (io.ReadCloser, error)
 	Inspect(ctx context.Context) (*Info, error)
 	DumpLogs(ctx context.Context) error

act/container/docker_cli.go

@@ -4,9 +4,10 @@
 
 //go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
 
-// This file is exact copy of https://github.com/docker/cli/blob/dfc4efb1e2ab8c06d70d2a1366ad448d2f917e90/cli/command/container/opts.go with:
+// This file is exact copy of https://github.com/docker/cli/blob/4a63305d74332de5ceba7fcbccbc3cbb7412f5ba/cli/command/container/opts.go with:
 // * appended with license information
 // * regexp and loader.ParseVolume in place of the import-restricted internal/lazyregexp and internal/volumespec
+// * jsontext in place of json.Compact for the seccomp profile
 // * invalidParameter from the package's errors.go, and convertPortSet/convertPortMap for the callers in docker_run.go
 //
 // docker/cli is licensed under the Apache License, Version 2.0.
@@ -152,6 +153,7 @@ type containerOptions struct {
 	runtime             string
 	autoRemove          bool
 	init                bool
+	umask               opts.UmaskOpt
 	annotations         *opts.MapOpts
 
 	Image string
@@ -326,6 +328,9 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
 	flags.Var(&copts.shmSize, "shm-size", "Size of /dev/shm")
 	flags.StringVar(&copts.utsMode, "uts", "", "UTS namespace to use")
 	flags.StringVar(&copts.runtime, "runtime", "", "Runtime to use for this container")
+	flags.Var(&copts.umask, "umask", "Set umask for the container")
+	flags.SetAnnotation("umask", "version", []string{"1.56"})
+	flags.SetAnnotation("umask", "ostype", []string{"linux"})
 
 	flags.BoolVar(&copts.init, "init", false, "Run an init inside the container that forwards signals and reaps processes")
 	flags.SetAnnotation("init", "version", []string{"1.25"})
@@ -721,6 +726,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 		MaskedPaths:    maskedPaths,
 		ReadonlyPaths:  readonlyPaths,
 		Annotations:    copts.annotations.GetAll(),
+		Umask:          copts.umask.Value(),
 	}
 
 	if copts.autoRemove && !hostConfig.RestartPolicy.IsNone() {

act/container/docker_cli_test.go

@@ -2,7 +2,7 @@
 // Copyright 2022 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-// This file is exact copy of https://github.com/docker/cli/blob/dfc4efb1e2ab8c06d70d2a1366ad448d2f917e90/cli/command/container/opts_test.go with:
+// This file is exact copy of https://github.com/docker/cli/blob/4a63305d74332de5ceba7fcbccbc3cbb7412f5ba/cli/command/container/opts_test.go with:
 // * appended with license information
 // * added tests for the locally changed parseDevice, validateDevice and invalidParameter
 //
@@ -167,6 +167,19 @@ func TestParseRunLinks(t *testing.T) {
 	}
 }
 
+func TestParseRunWithoutUmask(t *testing.T) {
+	_, hostConfig, _, err := parseRun([]string{"ubuntu", "bash"})
+	assert.NilError(t, err)
+	assert.Assert(t, hostConfig.Umask == nil)
+}
+
+func TestParseRunUmask(t *testing.T) {
+	_, hostConfig, _, err := parseRun([]string{"--umask", "0022", "ubuntu", "bash"})
+	assert.NilError(t, err)
+	assert.Assert(t, hostConfig.Umask != nil)
+	assert.Equal(t, uint32(0o22), *hostConfig.Umask)
+}
+
 func TestParseRunAttach(t *testing.T) {
 	tests := []struct {
 		input    string

act/container/docker_images.go

@@ -46,14 +46,13 @@ func RemoveImage(ctx context.Context, imageName string, force, pruneChildren boo
 	}
 	defer cli.Close()
 
-	inspectImage, err := cli.ImageInspect(ctx, imageName)
-	if cerrdefs.IsNotFound(err) {
+	if _, err := cli.ImageInspect(ctx, imageName); cerrdefs.IsNotFound(err) {
 		return false, nil
 	} else if err != nil {
 		return false, err
 	}
 
-	if _, err = cli.ImageRemove(ctx, inspectImage.ID, client.ImageRemoveOptions{
+	if _, err = cli.ImageRemove(ctx, imageName, client.ImageRemoveOptions{
 		Force:         force,
 		PruneChildren: pruneChildren,
 	}); err != nil {

act/container/docker_network.go

@@ -10,21 +10,20 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"net/netip"
 	"strings"
 	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
+	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/types/network"
 	"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
@@ -32,17 +31,17 @@ const (
 // 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 {
+func RemoveOrphanNetworks(ctx context.Context, runnerUUID, detach 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)
+	return removeOrphanNetworks(ctx, cli, runnerUUID, detach, createdBefore)
 }
 
-func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID string, createdBefore time.Time) error {
+func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID, detach string, createdBefore time.Time) error {
 	networks, err := cli.NetworkList(ctx, client.NetworkListOptions{
 		Filters: make(client.Filters).Add("label", runnerUUIDLabel+"="+runnerUUID),
 	})
@@ -51,6 +50,7 @@ func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID
 	}
 
 	var errs []error
+networks:
 	for _, n := range networks.Items {
 		result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
 		if err != nil {
@@ -59,9 +59,18 @@ func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID
 		}
 		// 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) {
+		if len(result.Network.Containers) > 1 || result.Network.Created.After(createdBefore) {
 			continue
 		}
+		for containerID := range result.Network.Containers {
+			if detach == "" || !strings.HasPrefix(containerID, detach) {
+				continue networks
+			}
+			if err := disconnectNetwork(ctx, cli, n.ID, containerID); err != nil {
+				errs = append(errs, fmt.Errorf("failed to disconnect container from network %s: %w", n.Name, err))
+				continue networks
+			}
+		}
 		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
@@ -134,6 +143,50 @@ func isAddressPoolExhausted(err error) bool {
 		strings.Contains(msg, "could not find an available, non-overlapping IPv4 address pool among the defaults") // docker 24 and older
 }
 
+func NewDockerNetworkConnectExecutor(networkName, container string) common.Executor {
+	return func(ctx context.Context) error {
+		cli, err := GetDockerClient(ctx)
+		if err != nil {
+			return err
+		}
+		defer cli.Close()
+		if err := connectNetwork(ctx, cli, networkName, container); err != nil {
+			common.Logger(ctx).Warnf("cannot connect %s to network %s, so jobs on it cannot reach the cache: %v", container, networkName, err)
+		}
+		return nil
+	}
+}
+
+func connectNetwork(ctx context.Context, cli client.APIClient, networkName, container string) error {
+	_, err := cli.NetworkConnect(ctx, networkName, client.NetworkConnectOptions{
+		Container:      container,
+		EndpointConfig: &network.EndpointSettings{Aliases: []string{container}},
+	})
+	if err != nil && (strings.Contains(err.Error(), "already exists in network") || strings.Contains(err.Error(), "already connected")) {
+		return nil
+	}
+	return err
+}
+
+func NewDockerNetworkDisconnectExecutor(networkName, container string) common.Executor {
+	return func(ctx context.Context) error {
+		cli, err := GetDockerClient(ctx)
+		if err != nil {
+			return err
+		}
+		defer cli.Close()
+		return disconnectNetwork(ctx, cli, networkName, container)
+	}
+}
+
+func disconnectNetwork(ctx context.Context, cli client.APIClient, networkName, container string) error {
+	_, err := cli.NetworkDisconnect(ctx, networkName, client.NetworkDisconnectOptions{Container: container, Force: true})
+	if cerrdefs.IsNotFound(err) || (err != nil && strings.Contains(err.Error(), "is not connected")) {
+		return nil
+	}
+	return err
+}
+
 func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 	return func(ctx context.Context) error {
 		cli, err := GetDockerClient(ctx)
@@ -172,3 +225,49 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 		return errors.Join(errs...)
 	}
 }
+
+// IsolatedCacheContainer returns the container holding addr, when jobs on jobNetwork cannot reach it there.
+func IsolatedCacheContainer(ctx context.Context, addr netip.Addr, jobNetwork string) (string, error) {
+	cli, err := GetDockerClient(ctx)
+	if err != nil {
+		return "", err
+	}
+	defer cli.Close()
+	return isolatedCacheContainer(ctx, cli, addr, jobNetwork)
+}
+
+func isolatedCacheContainer(ctx context.Context, cli client.APIClient, addr netip.Addr, jobNetwork string) (string, error) {
+	if jobNetwork == "host" || strings.HasPrefix(jobNetwork, "container:") {
+		return "", nil
+	}
+	containers, err := cli.ContainerList(ctx, client.ContainerListOptions{})
+	if err != nil {
+		return "", err
+	}
+	var holderID, holderContainer string
+	for _, summary := range containers.Items {
+		if summary.NetworkSettings == nil {
+			continue
+		}
+		for _, endpoint := range summary.NetworkSettings.Networks {
+			if endpoint != nil && (endpoint.IPAddress == addr || endpoint.GlobalIPv6Address == addr) {
+				holderID = endpoint.NetworkID
+				holderContainer = summary.ID[:12]
+			}
+		}
+	}
+	if holderID == "" {
+		return "", nil
+	}
+	holder, err := cli.NetworkInspect(ctx, holderID, client.NetworkInspectOptions{})
+	if err != nil || holder.Network.Driver != "bridge" {
+		return "", err
+	}
+	if jobNetwork != "" {
+		job, err := cli.NetworkInspect(ctx, jobNetwork, client.NetworkInspectOptions{})
+		if err != nil || job.Network.ID == holderID {
+			return "", err
+		}
+	}
+	return holderContainer, nil
+}

act/container/docker_network_test.go

@@ -6,25 +6,95 @@ package container
 import (
 	"context"
 	"errors"
+	"net/netip"
 	"testing"
 	"time"
 
 	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/types/container"
 	"github.com/moby/moby/api/types/network"
 	mobyclient "github.com/moby/moby/client"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
+func TestIsolatedCacheContainer(t *testing.T) {
+	ctx := context.Background()
+	cache, lan := netip.MustParseAddr("172.18.0.3"), netip.MustParseAddr("192.168.1.20")
+	client := &mockDockerClient{}
+	client.On("ContainerList", ctx, mobyclient.ContainerListOptions{}).Return(mobyclient.ContainerListResult{Items: []container.Summary{{}, {
+		ID: "0123456789abcdef",
+		NetworkSettings: &container.NetworkSettingsSummary{Networks: map[string]*network.EndpointSettings{
+			"compose": {NetworkID: "c0ffee", IPAddress: cache},
+			"lan":     {NetworkID: "beef", IPAddress: lan},
+		}},
+	}}}, nil)
+	for ref, inspected := range map[string]network.Network{
+		"c0ffee": {ID: "c0ffee", Name: "compose", Driver: "bridge"},
+		"beef":   {ID: "beef", Name: "lan", Driver: "macvlan"},
+		"c0f":    {ID: "c0ffee"},
+		"jobs":   {ID: "f00d"},
+	} {
+		client.On("NetworkInspect", ctx, ref, mobyclient.NetworkInspectOptions{}).
+			Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Network: inspected}}, nil)
+	}
+	check := func(addr netip.Addr, jobNetwork, want string) {
+		got, err := isolatedCacheContainer(ctx, client, addr, jobNetwork)
+		require.NoError(t, err)
+		assert.Equal(t, want, got, jobNetwork)
+	}
+	check(cache, "", "0123456789ab")
+	check(cache, "jobs", "0123456789ab")
+	check(cache, "c0f", "")
+	check(cache, "host", "")
+	check(lan, "", "")
+	check(netip.MustParseAddr("10.0.0.5"), "", "")
+}
+
 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 (m *mockDockerClient) NetworkConnect(ctx context.Context, id string, opts mobyclient.NetworkConnectOptions) (mobyclient.NetworkConnectResult, error) {
+	return mobyclient.NetworkConnectResult{}, m.Called(ctx, id, opts).Error(0)
+}
+
+func (m *mockDockerClient) NetworkDisconnect(ctx context.Context, id string, opts mobyclient.NetworkDisconnectOptions) (mobyclient.NetworkDisconnectResult, error) {
+	return mobyclient.NetworkDisconnectResult{}, m.Called(ctx, id, opts).Error(0)
+}
+
+func TestConnectAndDisconnectNetwork(t *testing.T) {
+	ctx := context.Background()
+	connect := func(answer error) error {
+		client := &mockDockerClient{}
+		client.On("NetworkConnect", ctx, "jobs", mobyclient.NetworkConnectOptions{
+			Container:      "0123456789ab",
+			EndpointConfig: &network.EndpointSettings{Aliases: []string{"0123456789ab"}},
+		}).Return(answer).Once()
+		return connectNetwork(ctx, client, "jobs", "0123456789ab")
+	}
+	require.NoError(t, connect(nil))
+	require.NoError(t, connect(errors.New("endpoint with name runner already exists in network jobs")))
+	require.NoError(t, connect(errors.New("container runner already connected to network jobs")))
+	require.ErrorIs(t, connect(context.Canceled), context.Canceled)
+
+	disconnect := func(answer error) error {
+		client := &mockDockerClient{}
+		client.On("NetworkDisconnect", ctx, "jobs", mobyclient.NetworkDisconnectOptions{
+			Container: "0123456789ab", Force: true,
+		}).Return(answer).Once()
+		return disconnectNetwork(ctx, client, "jobs", "0123456789ab")
+	}
+	require.NoError(t, disconnect(cerrdefs.ErrNotFound))
+	require.NoError(t, disconnect(errors.New("container runner is not connected to the network jobs")))
+	require.ErrorIs(t, disconnect(context.Canceled), context.Canceled)
+}
+
+// Of this runner's networks, only the ones nothing but its own cache container 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)
@@ -35,16 +105,29 @@ func TestRemoveOrphanNetworks(t *testing.T) {
 		{ID: "orphan"},
 		{ID: "busy"},
 		{ID: "starting"},
+		{ID: "cached"},
+		{ID: "shared"},
 	}}, 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)
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{
+			Network:    network.Network{Created: cutoff.Add(time.Second)},
+			Containers: map[string]network.EndpointResource{"0123456789abcdef": {}},
+		}}, nil)
+	client.On("NetworkInspect", ctx, "cached", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Containers: map[string]network.EndpointResource{"0123456789abcdef": {}}}}, nil)
+	client.On("NetworkInspect", ctx, "shared", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Containers: map[string]network.EndpointResource{"0123456789abcdef": {}, "job": {}}}}, nil)
 	client.On("NetworkRemove", ctx, "orphan", mobyclient.NetworkRemoveOptions{}).
 		Return(mobyclient.NetworkRemoveResult{}, nil)
+	client.On("NetworkDisconnect", ctx, "cached", mobyclient.NetworkDisconnectOptions{Container: "0123456789abcdef", Force: true}).
+		Return(nil).Once()
+	client.On("NetworkRemove", ctx, "cached", mobyclient.NetworkRemoveOptions{}).
+		Return(mobyclient.NetworkRemoveResult{}, nil).Once()
 
-	require.NoError(t, removeOrphanNetworks(ctx, client, "runner-1", cutoff))
+	require.NoError(t, removeOrphanNetworks(ctx, client, "runner-1", "0123456789ab", cutoff))
 	client.AssertExpectations(t)
 }

act/container/docker_proxy_unix.go

@@ -0,0 +1,48 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !WITHOUT_DOCKER && (linux || darwin || netbsd)
+
+package container
+
+import (
+	"encoding/binary"
+	"errors"
+	"io/fs"
+	"math"
+	"os"
+	"path/filepath"
+	"syscall"
+
+	"golang.org/x/sys/unix"
+)
+
+func copyDockerSocketPermissions(daemonSocket, socket string, info os.FileInfo) error {
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return errors.New("docker socket ownership is unavailable")
+	}
+	groupErr := os.Chown(socket, int(stat.Uid), int(stat.Gid))
+	if groupErr != nil && (!errors.Is(groupErr, fs.ErrPermission) || int(stat.Uid) != os.Geteuid()) {
+		return groupErr
+	}
+	if err := os.Chown(filepath.Dir(socket), int(stat.Uid), -1); err != nil {
+		return err
+	}
+	mode := uint16(info.Mode().Perm())
+	if err := os.Chmod(socket, fs.FileMode(mode)); err != nil || groupErr == nil {
+		return err
+	}
+	if size, err := unix.Getxattr(daemonSocket, "system.posix_acl_access", nil); err == nil && size > 0 {
+		return groupErr
+	}
+	owner, group, other := mode>>6, mode>>3&7, mode&7
+	acl := binary.LittleEndian.AppendUint32(nil, 2)
+	for _, entry := range []struct {
+		tag, perm uint16
+		id        uint32
+	}{{1, owner, math.MaxUint32}, {4, other, math.MaxUint32}, {8, group, stat.Gid}, {16, group | other, math.MaxUint32}, {32, other, math.MaxUint32}} {
+		acl = binary.LittleEndian.AppendUint32(binary.LittleEndian.AppendUint16(binary.LittleEndian.AppendUint16(acl, entry.tag), entry.perm), entry.id)
+	}
+	return unix.Setxattr(socket, "system.posix_acl_access", acl, 0) // names the group a rootless runner cannot chown to, its own group keeps what others had
+}

act/container/docker_proxy_windows.go

@@ -0,0 +1,15 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !WITHOUT_DOCKER
+
+package container
+
+import (
+	"errors"
+	"os"
+)
+
+func copyDockerSocketPermissions(_, _ string, _ os.FileInfo) error {
+	return errors.New("docker socket ownership cannot be preserved on Windows")
+}

act/container/docker_run.go

@@ -7,13 +7,13 @@
 package container
 
 import (
-	"archive/tar"
 	"bytes"
 	"context"
 	"errors"
 	"fmt"
 	"io"
 	"os"
+	"path"
 	"path/filepath"
 	"reflect"
 	"regexp"
@@ -24,16 +24,12 @@ import (
 	"time"
 
 	"gitea.com/gitea/runner/act/common"
-	"gitea.com/gitea/runner/act/filecollector"
 
 	"dario.cat/mergo"
+	"github.com/bmatcuk/doublestar/v4"
 	cerrdefs "github.com/containerd/errdefs"
 	"github.com/docker/cli/cli/compose/loader"
 	"github.com/docker/cli/cli/connhelper"
-	"github.com/go-git/go-billy/v5/helper/polyfill"
-	"github.com/go-git/go-billy/v5/osfs"
-	"github.com/go-git/go-git/v5/plumbing/format/gitignore"
-	"github.com/gobwas/glob"
 	"github.com/joho/godotenv"
 	"github.com/moby/moby/api/pkg/stdcopy"
 	"github.com/moby/moby/api/types/container"
@@ -138,12 +134,12 @@ func (cr *containerReference) Copy(destPath string, files ...*FileEntry) common.
 	).IfNot(common.Dryrun)
 }
 
-func (cr *containerReference) CopyDir(destPath, srcPath string, useGitIgnore bool) common.Executor {
+func (cr *containerReference) CopyDir(destPath, srcPath string, useGitIgnore, skipGitDir bool) common.Executor {
 	return common.NewPipelineExecutor(
 		common.NewInfoExecutor("docker cp src=%s dst=%s", srcPath, destPath),
 		cr.connect(),
 		cr.find(),
-		cr.copyDir(destPath, srcPath, useGitIgnore),
+		cr.copyDir(destPath, srcPath, useGitIgnore, skipGitDir),
 		func(ctx context.Context) error {
 			// If this fails, then folders have wrong permissions on non root container
 			if cr.UID != 0 || cr.GID != 0 {
@@ -252,6 +248,31 @@ func containerInfoFromInspect(inspect container.InspectResponse) *Info {
 		ID:     inspect.ID,
 		Health: HealthNone,
 		Ports:  map[string]string{}, // an empty map, never null, in the expression context
+		Mounts: make(map[string]string, len(inspect.Mounts)),
+	}
+	for _, mountPoint := range inspect.Mounts {
+		info.Mounts[mountPoint.Destination] = mountPoint.Source
+	}
+	if hostConfig := inspect.HostConfig; hostConfig != nil { // Mounts omits --tmpfs targets and subpaths
+		for target := range hostConfig.Tmpfs {
+			info.Mounts[path.Clean(target)] = ""
+		}
+		for _, spec := range hostConfig.Mounts {
+			subpath := ""
+			if spec.VolumeOptions != nil {
+				subpath = spec.VolumeOptions.Subpath
+			} else if spec.ImageOptions != nil {
+				subpath = spec.ImageOptions.Subpath
+			}
+			if target := path.Clean(spec.Target); subpath != "" && info.Mounts[target] != "" {
+				info.Mounts[target] = path.Join(info.Mounts[target], subpath)
+			}
+		}
+	}
+	for _, target := range []string{"/etc/hosts", "/etc/hostname", "/etc/resolv.conf"} { // specific to the job's network namespace
+		if _, mounted := info.Mounts[target]; !mounted {
+			info.Mounts[target] = ""
+		}
 	}
 
 	if state := inspect.State; state != nil {
@@ -484,14 +505,11 @@ func (cr *containerReference) remove() common.Executor {
 			RemoveVolumes: true,
 			Force:         true,
 		})
-		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()
+		if cerrdefs.IsConflict(err) {
+			err = cr.waitForRemoval(ctx, idOrName)
+		}
+		if err != nil && !cerrdefs.IsNotFound(err) {
+			return fmt.Errorf("failed to remove container %s: %w", idOrName, err)
 		}
 
 		logger.Debugf("Removed container: %v", idOrName)
@@ -500,7 +518,7 @@ func (cr *containerReference) remove() common.Executor {
 	}
 }
 
-func (cr *containerReference) waitForRemoval(ctx context.Context, idOrName string) {
+func (cr *containerReference) waitForRemoval(ctx context.Context, idOrName string) error {
 	// 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)
@@ -510,18 +528,13 @@ func (cr *containerReference) waitForRemoval(ctx context.Context, idOrName strin
 		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)
+	case result := <-waitResult.Result:
+		if result.Error != nil {
+			return errors.New(result.Error.Message)
+		}
+		return nil
+	case err := <-waitResult.Error:
+		return err
 	}
 }
 
@@ -575,7 +588,8 @@ func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config
 
 	// If the `privileged` config has been disabled, `copts.privileged` need to be forced to false,
 	// even if the user specifies `--privileged` in the options string.
-	if !hostConfig.Privileged {
+	if !hostConfig.Privileged && copts.privileged {
+		logger.Warnf("container option %q is not allowed when privileged mode is disabled and will be ignored", "--privileged")
 		copts.privileged = false
 	}
 
@@ -583,6 +597,14 @@ func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config
 	if err != nil {
 		return nil, nil, fmt.Errorf("cannot process container options: '%s': '%w'", options, err)
 	}
+	// workflow aliases join the runner's own, deduped so a re-create cannot grow the input
+	for _, endpoint := range containerConfig.NetworkingConfig.EndpointsConfig {
+		for _, alias := range endpoint.Aliases {
+			if !slices.Contains(cr.input.NetworkAliases, alias) {
+				cr.input.NetworkAliases = append(cr.input.NetworkAliases, alias)
+			}
+		}
+	}
 
 	// For Gitea, forcing --privileged off is not enough, other options reach the host too
 	if !hostConfig.Privileged {
@@ -603,6 +625,7 @@ func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config
 
 	logger.Debugf("Custom container.HostConfig from options ==> %+v", containerConfig.HostConfig)
 
+	cr.sanitizeConfig(ctx, nil, containerConfig.HostConfig) // a dropped volume must not displace the runner's own
 	overlayVolumes(hostConfig, containerConfig.HostConfig)
 	binds := hostConfig.Binds
 	mounts := hostConfig.Mounts
@@ -932,7 +955,7 @@ func (cr *containerReference) waitForCommand(ctx context.Context, resp client.Hi
 	}
 }
 
-func (cr *containerReference) copyDir(dstPath, srcPath string, useGitIgnore bool) common.Executor {
+func (cr *containerReference) copyDir(dstPath, srcPath string, useGitIgnore, skipGitDir bool) common.Executor {
 	return func(ctx context.Context) error {
 		if cr.id == "" {
 			return cr.missingContainerError("copy directory to %s", dstPath)
@@ -954,41 +977,7 @@ func (cr *containerReference) copyDir(dstPath, srcPath string, useGitIgnore bool
 				logger.Error(err)
 			}
 		}(tarFile)
-		tw := tar.NewWriter(tarFile)
-
-		srcPrefix := filepath.Dir(srcPath)
-		if !strings.HasSuffix(srcPrefix, string(filepath.Separator)) {
-			srcPrefix += string(filepath.Separator)
-		}
-		logger.Debugf("Stripping prefix:%s src:%s", srcPrefix, srcPath)
-
-		var ignorer gitignore.Matcher
-		if useGitIgnore {
-			ps, err := gitignore.ReadPatterns(polyfill.New(osfs.New(srcPath)), nil)
-			if err != nil {
-				logger.Debugf("Error loading .gitignore: %v", err)
-			}
-
-			ignorer = gitignore.NewMatcher(ps)
-		}
-
-		fc := &filecollector.FileCollector{
-			Ignorer:   ignorer,
-			SrcPath:   srcPath,
-			SrcPrefix: srcPrefix,
-			Handler: &filecollector.TarCollector{
-				TarWriter: tw,
-				UID:       cr.UID,
-				GID:       cr.GID,
-				DstDir:    dstPath[1:],
-			},
-		}
-
-		err = filepath.Walk(srcPath, fc.CollectFiles(ctx, []string{}))
-		if err != nil {
-			return err
-		}
-		if err := tw.Close(); err != nil {
+		if err := writeDirTar(ctx, tarFile, dstPath, srcPath, useGitIgnore, skipGitDir, cr.UID, cr.GID); err != nil {
 			return err
 		}
 
@@ -1013,30 +1002,12 @@ func (cr *containerReference) copyContent(dstPath string, files ...*FileEntry) c
 		if cr.id == "" {
 			return cr.missingContainerError("copy to %s", dstPath)
 		}
-		logger := common.Logger(ctx)
 		var buf bytes.Buffer
-		tw := tar.NewWriter(&buf)
-		for _, file := range files {
-			logger.Debugf("Writing entry to tarball %s len:%d", file.Name, len(file.Body))
-			hdr := &tar.Header{
-				Name: file.Name,
-				Mode: file.Mode,
-				Size: int64(len(file.Body)),
-				Uid:  cr.UID,
-				Gid:  cr.GID,
-			}
-			if err := tw.WriteHeader(hdr); err != nil {
-				return err
-			}
-			if _, err := tw.Write([]byte(file.Body)); err != nil {
-				return err
-			}
-		}
-		if err := tw.Close(); err != nil {
+		if err := writeFilesTar(ctx, &buf, cr.UID, cr.GID, files...); err != nil {
 			return err
 		}
 
-		logger.Debugf("Extracting content to '%s'", dstPath)
+		common.Logger(ctx).Debugf("Extracting content to '%s'", dstPath)
 		_, err := cr.cli.CopyToContainer(ctx, cr.id, client.CopyToContainerOptions{
 			DestinationPath: dstPath,
 			Content:         &buf,
@@ -1234,6 +1205,12 @@ func (cr *containerReference) sanitizeConfig(ctx context.Context, config *contai
 	return config, hostConfig
 }
 
+func SanitizeBinds(ctx context.Context, validVolumes, binds []string) []string {
+	cr := &containerReference{input: &NewContainerInput{ValidVolumes: validVolumes}}
+	_, hostConfig := cr.sanitizeConfig(ctx, nil, &container.HostConfig{Binds: binds})
+	return hostConfig.Binds
+}
+
 // 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)
@@ -1264,15 +1241,15 @@ func overlayVolumes(dst, src *container.HostConfig) {
 
 type validVolumeMatcher struct {
 	allowAll bool
-	named    []glob.Glob
-	host     []glob.Glob
+	named    []string
+	host     []string
 }
 
 func newValidVolumeMatcher(ctx context.Context, validVolumes []string) validVolumeMatcher {
 	logger := common.Logger(ctx)
 	ret := validVolumeMatcher{
-		named: make([]glob.Glob, 0, len(validVolumes)),
-		host:  make([]glob.Glob, 0, len(validVolumes)),
+		named: make([]string, 0, len(validVolumes)),
+		host:  make([]string, 0, len(validVolumes)),
 	}
 
 	for _, v := range validVolumes {
@@ -1281,10 +1258,10 @@ func newValidVolumeMatcher(ctx context.Context, validVolumes []string) validVolu
 			continue
 		}
 		if !isHostVolumePattern(v) {
-			if g, err := glob.Compile(v); err != nil {
-				logger.Errorf("create glob from %s error: %v", v, err)
+			if doublestar.ValidatePattern(v) {
+				ret.named = append(ret.named, v)
 			} else {
-				ret.named = append(ret.named, g)
+				logger.Errorf("invalid volume pattern %s", v)
 			}
 			continue
 		}
@@ -1293,10 +1270,10 @@ func newValidVolumeMatcher(ctx context.Context, validVolumes []string) validVolu
 			logger.Errorf("normalize volume pattern %s error: %v", v, err)
 			continue
 		}
-		if g, err := glob.Compile(normalized); err != nil {
-			logger.Errorf("create glob from %s error: %v", normalized, err)
+		if doublestar.ValidatePathPattern(normalized) {
+			ret.host = append(ret.host, normalized)
 		} else {
-			ret.host = append(ret.host, g)
+			logger.Errorf("invalid volume pattern %s", normalized)
 		}
 	}
 
@@ -1312,15 +1289,15 @@ func (m validVolumeMatcher) isValid(source string, sourceType mount.Type) bool {
 		if err != nil {
 			return false
 		}
-		for _, g := range m.host {
-			if g.Match(normalized) {
+		for _, pattern := range m.host {
+			if doublestar.PathMatchUnvalidated(pattern, normalized) {
 				return true
 			}
 		}
 		return false
 	}
-	for _, g := range m.named {
-		if g.Match(source) {
+	for _, pattern := range m.named {
+		if doublestar.MatchUnvalidated(pattern, source) {
 			return true
 		}
 	}

act/container/docker_run_test.go

@@ -345,18 +345,22 @@ func TestDockerWaitFailure(t *testing.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) {
+	removeFailure := errors.New("driver failed to remove root filesystem")
 	removeOpts := mobyclient.ContainerRemoveOptions{RemoveVolumes: true, Force: true}
 	killOpts := mobyclient.ContainerKillOptions{Signal: "SIGKILL"}
 	for _, tc := range []struct {
-		name        string
-		err         error
-		wantWait    bool
-		wantFailure bool
+		name     string
+		err      error
+		wantWait bool
+		waitErr  error
+		wantErr  error
 	}{
 		{name: "removal in progress", err: cerrdefs.ErrConflict.WithMessage("removal of container abc is already in progress"), wantWait: true},
+		{name: "wait canceled", err: cerrdefs.ErrConflict, wantWait: true, waitErr: context.Canceled, wantErr: context.Canceled},
+		{name: "removed during wait", err: cerrdefs.ErrConflict, wantWait: true, waitErr: cerrdefs.ErrNotFound},
 		{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"), wantFailure: true},
+		{name: "real failure", err: removeFailure, wantErr: removeFailure},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			logger, hook := test.NewNullLogger()
@@ -366,21 +370,24 @@ func TestRemoveIgnoresAutoRemoveRace(t *testing.T) {
 			client.On("ContainerRemove", ctx, "abc", removeOpts).Return(mobyclient.ContainerRemoveResult{}, tc.err)
 			if tc.wantWait {
 				removed := make(chan container.WaitResponse, 1)
-				removed <- container.WaitResponse{}
+				waitErrors := make(chan error, 1)
+				if tc.waitErr == nil {
+					removed <- container.WaitResponse{}
+				} else {
+					waitErrors <- tc.waitErr
+				}
 				client.On("ContainerWait", mock.Anything, "abc", mobyclient.ContainerWaitOptions{Condition: container.WaitConditionRemoved}).
-					Return(mobyclient.ContainerWaitResult{Result: removed})
+					Return(mobyclient.ContainerWaitResult{Result: removed, Error: waitErrors})
 			}
 			cr := &containerReference{id: "abc", cli: client}
 
-			require.NoError(t, cr.remove()(ctx))
-			// a failure keeps the id, so a later Remove() can retry it
-			if tc.wantFailure {
+			require.ErrorIs(t, cr.remove()(ctx), tc.wantErr)
+			if tc.wantErr != nil {
 				assert.Equal(t, "abc", cr.id)
-				assert.Len(t, hook.AllEntries(), 1)
 			} else {
 				assert.Empty(t, cr.id)
-				assert.Empty(t, hook.AllEntries())
 			}
+			assert.Empty(t, hook.AllEntries())
 			client.AssertExpectations(t)
 		})
 	}
@@ -471,7 +478,7 @@ func TestRejectsMissingContainer(t *testing.T) {
 		assert.Contains(t, err.Error(), `container "job-1" does not exist`, op)
 	}
 	check("copyContent", cr.copyContent("/var/run/act", &FileEntry{Name: "x", Mode: 0o644})(ctx))
-	check("copyDir", cr.copyDir("/var/run/act", "/src", false)(ctx))
+	check("copyDir", cr.copyDir("/var/run/act", "/src", false, false)(ctx))
 	check("exec", cr.exec([]string{"echo"}, nil, "", "")(ctx))
 	_, err := cr.GetContainerArchive(ctx, "/var/run/act/x")
 	check("GetContainerArchive", err)
@@ -553,11 +560,14 @@ func TestCheckVolumes(t *testing.T) {
 				"shared_volume",
 				"/home/test/data",
 				"/etc/conf.d/*.json",
+				"/opt/**",
 			},
 			binds: []string{
 				"shared_volume:/shared_volume",
 				"/home/test/data:/test_data",
 				"/etc/conf.d/base.json:/config/base.json",
+				"/etc/conf.d/sub/nested.json:/config/nested.json",
+				"/opt/app/cache:/cache",
 				"sql_data:/sql_data",
 				"/secrets/keys:/keys",
 			},
@@ -565,6 +575,7 @@ func TestCheckVolumes(t *testing.T) {
 				"shared_volume:/shared_volume",
 				"/home/test/data:/test_data",
 				"/etc/conf.d/base.json:/config/base.json",
+				"/opt/app/cache:/cache",
 			},
 		},
 	}
@@ -671,6 +682,7 @@ func mergeOptions(t *testing.T, runnerOptions, workflowOptions string, privilege
 		WorkflowOptions: workflowOptions,
 		NetworkMode:     "bridge",
 		UsernsMode:      "private",
+		ValidVolumes:    []string{"**"},
 	}}
 
 	_, hostConfig, err := cr.mergeContainerConfigs(common.WithLogger(context.Background(), logger), &container.Config{}, &container.HostConfig{
@@ -801,6 +813,31 @@ func TestContainerInfoFromInspect(t *testing.T) {
 		assert.Equal(t, "abc123", info.ID)
 		assert.Equal(t, HealthNone, info.Health)
 	})
+
+	t.Run("reports the mount sources by container path", func(t *testing.T) {
+		info := containerInfoFromInspect(container.InspectResponse{
+			Mounts: []container.MountPoint{
+				{Type: mount.TypeVolume, Name: "job", Source: "/var/lib/docker/volumes/job/_data", Destination: "/workspace/owner/repo"},
+				{Type: mount.TypeBind, Source: "/var/run/docker.sock", Destination: "/var/run/docker.sock"},
+				{Type: mount.TypeVolume, Name: "cache", Source: "/var/lib/docker/volumes/cache/_data", Destination: "/cache"},
+				{Type: mount.TypeBind, Source: "/custom/resolv.conf", Destination: "/etc/resolv.conf"},
+			},
+			HostConfig: &container.HostConfig{
+				Tmpfs:  map[string]string{"/workspace/owner/repo//tmp/": "size=1m"},
+				Mounts: []mount.Mount{{Type: mount.TypeVolume, Source: "cache", Target: "/cache/", VolumeOptions: &mount.VolumeOptions{Subpath: "project"}}},
+			},
+		})
+
+		assert.Equal(t, map[string]string{
+			"/workspace/owner/repo":     "/var/lib/docker/volumes/job/_data",
+			"/workspace/owner/repo/tmp": "",
+			"/var/run/docker.sock":      "/var/run/docker.sock",
+			"/cache":                    "/var/lib/docker/volumes/cache/_data/project",
+			"/etc/resolv.conf":          "/custom/resolv.conf",
+			"/etc/hosts":                "",
+			"/etc/hostname":             "",
+		}, info.Mounts)
+	})
 }
 
 func TestMergeContainerConfigsVolumesReplaceRunnerMounts(t *testing.T) {
@@ -808,8 +845,10 @@ func TestMergeContainerConfigsVolumesReplaceRunnerMounts(t *testing.T) {
 	ctx := common.WithLogger(context.Background(), logger)
 	cr := &containerReference{
 		input: &NewContainerInput{
-			NetworkMode:   "bridge",
-			RunnerOptions: "--volume /host/tools:/opt/hostedtoolcache",
+			NetworkMode:     "bridge",
+			RunnerOptions:   "--volume /host/tools:/opt/hostedtoolcache",
+			WorkflowOptions: "--volume /unapproved:/var/run/docker.sock",
+			ValidVolumes:    []string{"/host/tools"},
 		},
 	}
 
@@ -831,6 +870,18 @@ func TestMergeContainerConfigsWarnsOnlyAboutOptionsThatWereGiven(t *testing.T) {
 	assert.Zero(t, warnings("--volume /host/tools:/opt/hostedtoolcache", ""))
 	assert.Zero(t, warnings("", "--shm-size 1g"))
 	assert.Equal(t, 1, warnings("--network host", ""))
+	assert.Equal(t, 1, warnings("", "--privileged"))
+}
+
+func TestMergeContainerConfigsKeepsNetworkAliasesFromOptions(t *testing.T) {
+	logger, _ := test.NewNullLogger()
+	cr := &containerReference{input: &NewContainerInput{
+		NetworkMode: "job-network", NetworkAliases: []string{"redis"}, WorkflowOptions: "--network-alias redis-primary",
+	}}
+
+	_, _, err := cr.mergeContainerConfigs(common.WithLogger(t.Context(), logger), &container.Config{}, &container.HostConfig{})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"redis", "redis-primary"}, cr.input.NetworkAliases)
 }
 
 // A dead daemon must fail the job, not panic through logrus and not silently

act/container/docker_stub.go

@@ -9,6 +9,7 @@ package container
 import (
 	"context"
 	"errors"
+	"net/netip"
 	"runtime"
 	"time"
 
@@ -17,6 +18,10 @@ import (
 	"github.com/moby/moby/api/types/system"
 )
 
+func IsolatedCacheContainer(context.Context, netip.Addr, string) (string, error) {
+	return "", nil
+}
+
 // ImageExistsLocally returns a boolean indicating if an image with the
 // requested name, tag and architecture exists in the local docker image store
 func ImageExistsLocally(ctx context.Context, imageName, platform string) (bool, error) {
@@ -29,6 +34,18 @@ func RemoveImage(ctx context.Context, imageName string, force, pruneChildren boo
 	return false, errors.New("Unsupported Operation")
 }
 
+func RemoveDockerJobResources(_ context.Context, _ string) error {
+	return nil
+}
+
+func NewDockerProxy(_ context.Context, _ string) *DockerProxy {
+	return nil
+}
+
+func StartDockerProxy(daemonSocket, dir, job string) (*DockerProxy, error) {
+	return nil, errors.New("Unsupported Operation")
+}
+
 // NewDockerBuildExecutor function to create a run executor for the container
 func NewDockerBuildExecutor(input NewDockerBuildExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
@@ -74,6 +91,30 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 	}
 }
 
-func RemoveOrphanNetworks(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
+func NewDockerNetworkConnectExecutor(_, _ string) common.Executor {
+	return func(_ context.Context) error {
+		return nil
+	}
+}
+
+func NewDockerNetworkDisconnectExecutor(_, _ string) common.Executor {
+	return func(_ context.Context) error {
+		return nil
+	}
+}
+
+func RemoveOrphanNetworks(_ context.Context, _, _ string, _ time.Time) error {
+	return nil
+}
+
+func SanitizeBinds(_ context.Context, _, binds []string) []string {
+	return binds
+}
+
+func CreateJobVolumes(ctx context.Context, runnerUUID string, volumeNames []string) error {
+	return nil
+}
+
+func RemoveOrphanJobVolumes(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
 	return nil
 }

act/container/docker_volume.go

@@ -8,40 +8,67 @@ package container
 
 import (
 	"context"
+	"errors"
+	"fmt"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
+	cerrdefs "github.com/containerd/errdefs"
 	"github.com/moby/moby/client"
 )
 
-func NewDockerVolumeRemoveExecutor(volumeName string, force bool) common.Executor {
-	return func(ctx context.Context) error {
-		cli, err := GetDockerClient(ctx)
-		if err != nil {
-			return err
-		}
-		defer cli.Close()
-
-		list, err := cli.VolumeList(ctx, client.VolumeListOptions{})
-		if err != nil {
-			return err
-		}
-
-		for _, vol := range list.Items {
-			if vol.Name == volumeName {
-				return removeExecutor(volumeName, force)(ctx)
-			}
-		}
-
-		// Volume not found - do nothing
-		return nil
+func CreateJobVolumes(ctx context.Context, runnerUUID string, volumeNames []string) error {
+	cli, err := GetDockerClient(ctx)
+	if err != nil {
+		return err
 	}
+	defer cli.Close()
+
+	for _, volumeName := range volumeNames {
+		if _, err := cli.VolumeCreate(ctx, client.VolumeCreateOptions{
+			Name:   volumeName,
+			Labels: runnerLabels(runnerUUID),
+		}); err != nil {
+			return err
+		}
+	}
+	return nil
 }
 
-func removeExecutor(volume string, force bool) common.Executor {
+func RemoveOrphanJobVolumes(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()
+
+	volumes, err := cli.VolumeList(ctx, client.VolumeListOptions{
+		Filters: make(client.Filters).Add("label", runnerUUIDLabel+"="+runnerUUID).Add("dangling", "true"),
+	})
+	if err != nil {
+		return err
+	}
+
+	var errs []error
+	for _, item := range volumes.Items {
+		created, err := time.Parse(time.RFC3339, item.CreatedAt)
+		// an unreadable or recent timestamp may belong to a job that is still starting up
+		if err != nil || created.After(createdBefore) || item.Labels[runnerUUIDLabel] != runnerUUID {
+			continue
+		}
+		if _, err := cli.VolumeRemove(ctx, item.Name, client.VolumeRemoveOptions{}); err != nil && !cerrdefs.IsNotFound(err) {
+			errs = append(errs, fmt.Errorf("failed to remove volume %s: %w", item.Name, err))
+			continue
+		}
+		common.Logger(ctx).Infof("removed docker volume %s left behind by an earlier job", item.Name)
+	}
+	return errors.Join(errs...)
+}
+
+func NewDockerVolumeRemoveExecutor(volumeName string, force bool) common.Executor {
 	return func(ctx context.Context) error {
-		logger := common.Logger(ctx)
-		logger.Debugf("docker volume rm %s", volume)
+		common.Logger(ctx).Debugf("docker volume rm %s", volumeName)
 
 		if common.Dryrun(ctx) {
 			return nil
@@ -53,7 +80,10 @@ func removeExecutor(volume string, force bool) common.Executor {
 		}
 		defer cli.Close()
 
-		_, err = cli.VolumeRemove(ctx, volume, client.VolumeRemoveOptions{Force: force})
+		_, err = cli.VolumeRemove(ctx, volumeName, client.VolumeRemoveOptions{Force: force})
+		if cerrdefs.IsNotFound(err) { // already gone is the outcome we wanted
+			return nil
+		}
 		return err
 	}
 }

act/container/host_environment.go

@@ -92,7 +92,7 @@ func (e *HostEnvironment) Copy(destPath string, files ...*FileEntry) common.Exec
 	}
 }
 
-func (e *HostEnvironment) CopyDir(destPath, srcPath string, useGitIgnore bool) common.Executor {
+func (e *HostEnvironment) CopyDir(destPath, srcPath string, useGitIgnore, skipGitDir bool) common.Executor {
 	return func(ctx context.Context) error {
 		logger := common.Logger(ctx)
 		srcPrefix := filepath.Dir(srcPath)
@@ -110,9 +110,10 @@ func (e *HostEnvironment) CopyDir(destPath, srcPath string, useGitIgnore bool) c
 			ignorer = gitignore.NewMatcher(ps)
 		}
 		fc := &filecollector.FileCollector{
-			Ignorer:   ignorer,
-			SrcPath:   srcPath,
-			SrcPrefix: srcPrefix,
+			Ignorer:    ignorer,
+			SrcPath:    srcPath,
+			SrcPrefix:  srcPrefix,
+			SkipGitDir: skipGitDir,
 			Handler: &filecollector.CopyCollector{
 				DstDir: destPath,
 			},
@@ -629,8 +630,11 @@ func (*HostEnvironment) JoinPathVariable(paths ...string) string {
 func goArchToActionArch(arch string) string {
 	archMapper := map[string]string{
 		"x86_64":  "X64",
+		"amd64":   "X64",
 		"386":     "X86",
+		"arm":     "ARM",
 		"aarch64": "ARM64",
+		"arm64":   "ARM64",
 	}
 	if arch, ok := archMapper[arch]; ok {
 		return arch
@@ -640,7 +644,9 @@ func goArchToActionArch(arch string) string {
 
 func goOsToActionOs(os string) string {
 	osMapper := map[string]string{
-		"darwin": "macOS",
+		"linux":   "Linux",
+		"darwin":  "macOS",
+		"windows": "Windows",
 	}
 	if os, ok := osMapper[os]; ok {
 		return os

act/container/host_environment_test.go

@@ -27,6 +27,11 @@ import (
 // Type assert HostEnvironment implements ExecutionsEnvironment
 var _ ExecutionsEnvironment = &HostEnvironment{}
 
+func TestActionPlatformNames(t *testing.T) {
+	assert.Equal(t, []string{"Linux", "macOS", "Windows"}, []string{goOsToActionOs("linux"), goOsToActionOs("darwin"), goOsToActionOs("windows")})
+	assert.Equal(t, []string{"X86", "X64", "ARM", "ARM64"}, []string{goArchToActionArch("386"), goArchToActionArch("amd64"), goArchToActionArch("arm"), goArchToActionArch("arm64")})
+}
+
 func TestCopyDir(t *testing.T) {
 	dir := t.TempDir()
 	ctx := context.Background()
@@ -42,10 +47,32 @@ func TestCopyDir(t *testing.T) {
 	_ = os.MkdirAll(e.TmpDir, 0o700)
 	_ = os.MkdirAll(e.ToolCache, 0o700)
 	_ = os.MkdirAll(e.ActPath, 0o700)
-	err := e.CopyDir(e.Workdir, e.Path, true)(ctx)
+	err := e.CopyDir(e.Workdir, e.Path, true, false)(ctx)
 	assert.NoError(t, err)
 }
 
+func TestCopyDirSkipGitDir(t *testing.T) {
+	for name, skipGitDir := range map[string]bool{"kept for a workspace copy": false, "skipped for an action copy": true} {
+		t.Run(name, func(t *testing.T) {
+			src := filepath.Join(t.TempDir(), "action")
+			require.NoError(t, os.MkdirAll(filepath.Join(src, ".git", "objects"), 0o700))
+			require.NoError(t, os.WriteFile(filepath.Join(src, ".git", "objects", "pack"), []byte("x"), 0o600))
+			require.NoError(t, os.WriteFile(filepath.Join(src, "action.yml"), []byte("name: x\n"), 0o600))
+
+			dest := filepath.Join(t.TempDir(), "dest")
+			e := &HostEnvironment{StdOut: os.Stdout}
+			require.NoError(t, e.CopyDir(dest, src+string(filepath.Separator), false, skipGitDir)(context.Background()))
+
+			assert.FileExists(t, filepath.Join(dest, "action.yml"))
+			if skipGitDir {
+				assert.NoDirExists(t, filepath.Join(dest, ".git"))
+			} else {
+				assert.FileExists(t, filepath.Join(dest, ".git", "objects", "pack"))
+			}
+		})
+	}
+}
+
 func TestGetContainerArchive(t *testing.T) {
 	dir := t.TempDir()
 	ctx := context.Background()

act/container/kubernetes_client.go

@@ -0,0 +1,400 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package container
+
+import (
+	"bytes"
+	"cmp"
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/coder/websocket"
+	"go.yaml.in/yaml/v4"
+)
+
+const (
+	serviceAccountDir = "/var/run/secrets/kubernetes.io/serviceaccount"
+	execProtocol      = "v5.channel.k8s.io"
+)
+
+type kubeClient struct {
+	server, namespace, token string
+	tokenFile                string // re-read on every request, service account tokens rotate
+	inCluster                bool
+	http                     *http.Client
+}
+
+type apiError struct {
+	code    int
+	message string
+}
+
+func (e *apiError) Error() string { return e.message }
+
+func isNotFound(err error) bool {
+	var apiErr *apiError
+	return errors.As(err, &apiErr) && apiErr.code == http.StatusNotFound
+}
+
+func newKubeClient(kubeconfig, namespace string) (*kubeClient, error) {
+	client := &kubeClient{namespace: namespace}
+	transport := &http.Transport{Proxy: http.ProxyFromEnvironment, TLSClientConfig: &tls.Config{MinVersion: tls.VersionTLS12}}
+	if host := os.Getenv("KUBERNETES_SERVICE_HOST"); host != "" && kubeconfig == "" {
+		if err := client.loadInCluster(host, transport.TLSClientConfig); err != nil {
+			return nil, err
+		}
+	} else if err := client.loadKubeconfig(kubeconfig, transport); err != nil {
+		return nil, err
+	}
+	client.http = &http.Client{Transport: transport}
+	return client, nil
+}
+
+func (c *kubeClient) loadInCluster(host string, tlsConfig *tls.Config) error {
+	c.server = "https://" + net.JoinHostPort(host, os.Getenv("KUBERNETES_SERVICE_PORT"))
+	c.tokenFile = serviceAccountDir + "/token"
+	ca, err := os.ReadFile(serviceAccountDir + "/ca.crt")
+	if err != nil {
+		return err
+	}
+	tlsConfig.RootCAs = x509.NewCertPool()
+	tlsConfig.RootCAs.AppendCertsFromPEM(ca)
+	if c.namespace == "" {
+		namespace, err := os.ReadFile(serviceAccountDir + "/namespace")
+		if err != nil {
+			return err
+		}
+		c.namespace = strings.TrimSpace(string(namespace))
+	}
+	c.inCluster = true
+	return nil
+}
+
+func (c *kubeClient) loadKubeconfig(path string, transport *http.Transport) error {
+	if paths := filepath.SplitList(os.Getenv("KUBECONFIG")); path == "" && len(paths) > 0 {
+		path = paths[0]
+	}
+	if path == "" {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return err
+		}
+		path = filepath.Join(home, ".kube", "config")
+	}
+	content, err := os.ReadFile(path)
+	if err != nil {
+		return fmt.Errorf("no in-cluster service account and no kubeconfig: %w", err)
+	}
+	var config struct {
+		CurrentContext string `yaml:"current-context"`
+		Contexts       []struct {
+			Name    string
+			Context struct{ Cluster, User, Namespace string }
+		}
+		Clusters []struct {
+			Name    string
+			Cluster struct {
+				Server                   string
+				TLSServerName            string `yaml:"tls-server-name"`
+				InsecureSkipTLSVerify    bool   `yaml:"insecure-skip-tls-verify"`
+				ProxyURL                 string `yaml:"proxy-url"`
+				CertificateAuthority     string `yaml:"certificate-authority"`
+				CertificateAuthorityData string `yaml:"certificate-authority-data"`
+			}
+		}
+		Users []struct {
+			Name string
+			User struct {
+				Token                 string
+				TokenFile             string `yaml:"tokenFile"`
+				ClientCertificate     string `yaml:"client-certificate"`
+				ClientCertificateData string `yaml:"client-certificate-data"`
+				ClientKey             string `yaml:"client-key"`
+				ClientKeyData         string `yaml:"client-key-data"`
+				Exec                  any
+				AuthProvider          any `yaml:"auth-provider"`
+			}
+		}
+	}
+	if err := yaml.Unmarshal(content, &config); err != nil {
+		return fmt.Errorf("parse kubeconfig %s: %w", path, err)
+	}
+	var current struct{ Cluster, User, Namespace string }
+	for _, entry := range config.Contexts {
+		if entry.Name == config.CurrentContext {
+			current = entry.Context
+		}
+	}
+	if current.Cluster == "" {
+		return fmt.Errorf("kubeconfig %s has no current context", path)
+	}
+	c.namespace = cmp.Or(c.namespace, current.Namespace, "default")
+
+	resolve := func(file string) string {
+		if file == "" || filepath.IsAbs(file) {
+			return file
+		}
+		return filepath.Join(filepath.Dir(path), file)
+	}
+	read := func(data, file string) ([]byte, error) {
+		if data != "" {
+			return base64.StdEncoding.DecodeString(data)
+		}
+		if file == "" {
+			return nil, nil
+		}
+		return os.ReadFile(resolve(file))
+	}
+
+	tlsConfig := transport.TLSClientConfig
+	for _, cluster := range config.Clusters {
+		if cluster.Name != current.Cluster {
+			continue
+		}
+		c.server = strings.TrimSuffix(cluster.Cluster.Server, "/")
+		tlsConfig.ServerName, tlsConfig.InsecureSkipVerify = cluster.Cluster.TLSServerName, cluster.Cluster.InsecureSkipTLSVerify
+		if cluster.Cluster.ProxyURL != "" {
+			proxy, err := url.Parse(cluster.Cluster.ProxyURL)
+			if err != nil {
+				return fmt.Errorf("kubeconfig %s: %w", path, err)
+			}
+			transport.Proxy = http.ProxyURL(proxy)
+		}
+		ca, err := read(cluster.Cluster.CertificateAuthorityData, cluster.Cluster.CertificateAuthority)
+		if err != nil {
+			return err
+		}
+		if ca != nil {
+			tlsConfig.RootCAs = x509.NewCertPool()
+			tlsConfig.RootCAs.AppendCertsFromPEM(ca)
+		}
+	}
+	for _, user := range config.Users {
+		if user.Name != current.User {
+			continue
+		}
+		if user.User.Exec != nil || user.User.AuthProvider != nil {
+			return fmt.Errorf("kubeconfig %s: user %q authenticates through a credential plugin, which the runner does not support, use a token or client certificate", path, user.Name)
+		}
+		c.token, c.tokenFile = user.User.Token, resolve(user.User.TokenFile)
+		cert, err := read(user.User.ClientCertificateData, user.User.ClientCertificate)
+		if err != nil {
+			return err
+		}
+		key, err := read(user.User.ClientKeyData, user.User.ClientKey)
+		if err != nil {
+			return err
+		}
+		if cert != nil {
+			pair, err := tls.X509KeyPair(cert, key)
+			if err != nil {
+				return err
+			}
+			tlsConfig.Certificates = []tls.Certificate{pair}
+		}
+	}
+	if c.server == "" {
+		return fmt.Errorf("kubeconfig %s names no server for context %q", path, config.CurrentContext)
+	}
+	return nil
+}
+
+func (c *kubeClient) authorize(header http.Header) error {
+	token := c.token
+	if c.tokenFile != "" {
+		content, err := os.ReadFile(c.tokenFile)
+		if err != nil {
+			return err
+		}
+		token = strings.TrimSpace(string(content))
+	}
+	if token != "" {
+		header.Set("Authorization", "Bearer "+token)
+	}
+	return nil
+}
+
+func (c *kubeClient) path(resource string) string {
+	return "/api/v1/namespaces/" + c.namespace + "/" + resource
+}
+
+func (c *kubeClient) do(ctx context.Context, method, path string, in, out any) error {
+	var body io.Reader
+	if in != nil {
+		content, err := json.Marshal(in)
+		if err != nil {
+			return err
+		}
+		body = bytes.NewReader(content)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, c.server+path, body)
+	if err != nil {
+		return err
+	}
+	if err := c.authorize(req.Header); err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= http.StatusMultipleChoices {
+		return statusError(resp)
+	}
+	if out == nil {
+		out = io.Discard // draining lets the connection be reused
+	}
+	if writer, ok := out.(io.Writer); ok {
+		_, err = io.Copy(writer, resp.Body)
+		return err
+	}
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+func (c *kubeClient) delete(ctx context.Context, resource, name string) error {
+	if name == "" {
+		return nil
+	}
+	if err := c.do(ctx, http.MethodDelete, c.path(resource+"/"+name), nil, nil); err != nil && !isNotFound(err) {
+		return fmt.Errorf("delete %s %s: %w", resource, name, err)
+	}
+	return nil
+}
+
+func statusError(resp *http.Response) error {
+	content, _ := io.ReadAll(resp.Body)
+	var status struct{ Message string }
+	if json.Unmarshal(content, &status) != nil || status.Message == "" {
+		status.Message = strings.TrimSpace(string(content))
+	}
+	return &apiError{code: resp.StatusCode, message: status.Message}
+}
+
+func (c *kubeClient) exec(ctx context.Context, pod, containerName string, command []string, stdin io.Reader, stdout, stderr io.Writer) error {
+	query := url.Values{"container": {containerName}, "command": command, "stdout": {"true"}, "stderr": {"true"}}
+	if stdin != nil {
+		query.Set("stdin", "true")
+	}
+	header := http.Header{}
+	if err := c.authorize(header); err != nil {
+		return err
+	}
+	ctx, cancel := context.WithCancelCause(ctx)
+	defer cancel(nil)
+	conn, resp, err := websocket.Dial(ctx, c.server+c.path("pods/"+pod+"/exec?")+query.Encode(), &websocket.DialOptions{
+		HTTPClient:   c.http,
+		HTTPHeader:   header,
+		Subprotocols: []string{execProtocol},
+	})
+	if err != nil {
+		if resp != nil && resp.StatusCode >= http.StatusMultipleChoices {
+			defer resp.Body.Close()
+			err = statusError(resp)
+		}
+		return fmt.Errorf("exec in pod %s: %w", pod, err)
+	}
+	defer func() { _ = conn.CloseNow() }()
+	if conn.Subprotocol() != execProtocol {
+		return fmt.Errorf("the Kubernetes API server does not speak %s, which needs Kubernetes 1.30 or later", execProtocol)
+	}
+	conn.SetReadLimit(-1)
+
+	if stdin != nil {
+		go func() {
+			if err := sendStdin(ctx, conn, stdin); err != nil {
+				cancel(err)
+			}
+		}()
+	}
+	go func() {
+		ticker := time.NewTicker(5 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				if conn.Ping(ctx) != nil {
+					return
+				}
+			}
+		}
+	}()
+
+	for {
+		_, frame, err := conn.Read(ctx)
+		if err != nil {
+			return cmp.Or(context.Cause(ctx), fmt.Errorf("exec in pod %s ended without an exit status: %w", pod, err))
+		}
+		if len(frame) < 2 {
+			continue
+		}
+		switch frame[0] {
+		case 1:
+			_, err = stdout.Write(frame[1:])
+		case 2:
+			_, err = stderr.Write(frame[1:])
+		case 3:
+			return cmp.Or(context.Cause(ctx), execStatus(frame[1:]))
+		}
+		if err != nil {
+			return err
+		}
+	}
+}
+
+func sendStdin(ctx context.Context, conn *websocket.Conn, stdin io.Reader) error {
+	frame := make([]byte, 1+32*1024) // frame[0] is the stdin channel, 0
+	for {
+		n, err := stdin.Read(frame[1:])
+		if n > 0 {
+			if err := conn.Write(ctx, websocket.MessageBinary, frame[:1+n]); err != nil {
+				return err
+			}
+		}
+		if errors.Is(err, io.EOF) {
+			return conn.Write(ctx, websocket.MessageBinary, []byte{255, 0}) // v5 close signal for stdin
+		}
+		if err != nil {
+			return err
+		}
+	}
+}
+
+func execStatus(content []byte) error {
+	var status struct {
+		Status, Message string
+		Details         struct {
+			Causes []struct{ Reason, Message string }
+		}
+	}
+	if err := json.Unmarshal(content, &status); err != nil {
+		return fmt.Errorf("decode exec status: %w", err)
+	}
+	if status.Status == "Success" {
+		return nil
+	}
+	for _, cause := range status.Details.Causes {
+		if code, err := strconv.Atoi(cause.Message); cause.Reason == "ExitCode" && err == nil {
+			return ExitCodeError(code)
+		}
+	}
+	return fmt.Errorf("exec failed: %s", status.Message)
+}

act/container/kubernetes_test.go

@@ -0,0 +1,290 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package container
+
+import (
+	"archive/tar"
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/coder/websocket"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type podManifest struct {
+	Metadata struct{ Labels map[string]string }
+	Spec     struct {
+		AutomountServiceAccountToken bool
+		EnableServiceLinks           bool
+		HostAliases                  []struct{ Hostnames []string }
+		Volumes                      []map[string]any
+		Containers                   []struct {
+			Name, ImagePullPolicy string
+			Resources             map[string]any
+			StartupProbe          *struct{ PeriodSeconds, TimeoutSeconds, FailureThreshold int }
+		}
+	}
+}
+
+type fakeCluster struct {
+	mu       sync.Mutex
+	requests map[string][]string
+}
+
+func (f *fakeCluster) record(request, content string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.requests[request] = append(f.requests[request], content)
+}
+
+func fakeKubernetes(t *testing.T, podStatus string) (string, *fakeCluster) {
+	cluster := &fakeCluster{requests: map[string][]string{}}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer test-token" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		body, err := io.ReadAll(r.Body)
+		assert.NoError(t, err)
+		cluster.record(r.Method+" "+r.URL.Path, string(body))
+		pods, secrets := "/api/v1/namespaces/ci/pods", "/api/v1/namespaces/ci/secrets"
+		switch {
+		case r.Method == http.MethodGet && r.URL.Path == pods:
+			cluster.record("list", r.URL.Query().Get("labelSelector"))
+			_, _ = io.WriteString(w, `{"items":[{"metadata":{"name":"old","creationTimestamp":"2020-01-01T00:00:00Z"}},{"metadata":{"name":"new","creationTimestamp":"2999-01-01T00:00:00Z"}}]}`)
+		case strings.HasSuffix(r.URL.Path, "/exec"):
+			cluster.record("exec", r.URL.RawQuery)
+			serveLocalExec(t, w, r)
+		case strings.HasSuffix(r.URL.Path, "/log"):
+			_, _ = io.WriteString(w, "log of "+r.URL.Query().Get("container"))
+		case r.Method == http.MethodGet && strings.HasPrefix(r.URL.Path, pods+"/"):
+			_, _ = io.WriteString(w, podStatus)
+		case r.Method == http.MethodPost && (r.URL.Path == pods || r.URL.Path == secrets), r.Method == http.MethodDelete:
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	t.Cleanup(server.Close)
+	kubeconfig := filepath.Join(t.TempDir(), "kubeconfig")
+	require.NoError(t, os.WriteFile(filepath.Join(filepath.Dir(kubeconfig), "token"), []byte("test-token\n"), 0o600))
+	require.NoError(t, os.WriteFile(kubeconfig, fmt.Appendf(nil, `
+current-context: test
+contexts: [{name: test, context: {cluster: test, user: test, namespace: ci}}]
+clusters: [{name: test, cluster: {server: "http://kubernetes.invalid", proxy-url: %q}}]
+users: [{name: test, user: {tokenFile: token}}]
+`, server.URL), 0o600))
+	return kubeconfig, cluster
+}
+
+func serveLocalExec(t *testing.T, w http.ResponseWriter, r *http.Request) {
+	conn, err := websocket.Accept(w, r, &websocket.AcceptOptions{Subprotocols: []string{execProtocol}})
+	if err != nil {
+		t.Error(err)
+		return
+	}
+	defer func() { _ = conn.CloseNow() }()
+	conn.SetReadLimit(-1)
+	command := r.URL.Query()["command"]
+	var stdin bytes.Buffer
+	for r.URL.Query().Get("stdin") == "true" {
+		_, frame, err := conn.Read(r.Context())
+		if err != nil {
+			t.Error(err)
+			return
+		}
+		if frame[0] == 255 {
+			break
+		}
+		stdin.Write(frame[1:])
+	}
+	cmd := exec.Command(command[0], command[1:]...)
+	cmd.Env = append(os.Environ(), "COPYFILE_DISABLE=1")
+	var stdout, stderr bytes.Buffer
+	cmd.Stdin, cmd.Stdout, cmd.Stderr = &stdin, &stdout, &stderr
+	status := `{"status":"Success"}`
+	var exitErr *exec.ExitError
+	if err := cmd.Run(); errors.As(err, &exitErr) {
+		status = fmt.Sprintf(`{"status":"Failure","reason":"NonZeroExitCode","details":{"causes":[{"reason":"ExitCode","message":"%d"}]}}`, exitErr.ExitCode())
+	} else {
+		assert.NoError(t, err)
+	}
+	for _, frame := range [][]byte{append([]byte{1}, stdout.Bytes()...), append([]byte{2}, stderr.Bytes()...), append([]byte{3}, status...)} {
+		_ = conn.Write(r.Context(), websocket.MessageBinary, frame)
+	}
+}
+
+func TestKubernetesPodRunsJobThroughAPI(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("uses POSIX shell")
+	}
+	ctx := t.Context()
+	kubeconfig, cluster := fakeKubernetes(t, `{"spec":{"containers":[{},{}]},"status":{"phase":"Running","containerStatuses":[
+		{"name":"job","ready":true,"state":{"running":{}}},
+		{"name":"my-db","ready":true,"state":{"running":{}}}]}}`)
+	workdir, err := filepath.EvalSymlinks(t.TempDir())
+	require.NoError(t, err)
+	options := KubernetesOptions{Kubeconfig: kubeconfig, RunnerUUID: "runner-uuid", PodTemplates: []map[string]any{
+		{"spec": map[string]any{
+			"automountServiceAccountToken": true,
+			"containers": []any{
+				map[string]any{"name": "job", "resources": map[string]any{"limits": map[string]any{"cpu": "2"}}},
+				map[string]any{
+					"name": "$services", "imagePullPolicy": "Always", "resources": map[string]any{"limits": map[string]any{"memory": "256Mi"}},
+					"env": []any{map[string]any{"name": "POSTGRES_PASSWORD", "value": "template"}},
+				},
+			},
+		}},
+		{"spec": map[string]any{
+			"volumes":    []any{map[string]any{"name": "workspace", "emptyDir": map[string]any{"sizeLimit": "1Gi"}}},
+			"containers": []any{map[string]any{"name": "job", "resources": map[string]any{"limits": map[string]any{"memory": "1Gi"}}}},
+		}},
+	}}
+	pod, err := NewKubernetesPod(options)
+	require.NoError(t, err)
+	var jobLog, serviceLog bytes.Buffer
+	job := pod.JobContainer(&NewContainerInput{Name: "Job-Name", Image: "node", WorkingDir: workdir, Stdout: &jobLog, Stderr: &jobLog})
+	service := pod.ServiceContainer("My_DB", &NewContainerInput{
+		Image:           "postgres",
+		Cmd:             []string{"postgres", "-D", "$(PGDATA)"},
+		Env:             []string{"POSTGRES_PASSWORD=service-secret"},
+		WorkflowOptions: "--health-cmd pg_isready --health-interval 2s --health-start-period 4s",
+		Stdout:          &serviceLog,
+	})
+
+	require.NoError(t, job.Create(nil, nil)(ctx))
+	var manifest podManifest
+	require.NoError(t, json.Unmarshal([]byte(cluster.requests["POST /api/v1/namespaces/ci/pods"][0]), &manifest))
+	assert.Equal(t, "gitea-runner", manifest.Metadata.Labels["app.kubernetes.io/managed-by"])
+	assert.Equal(t, "runner-uuid", manifest.Metadata.Labels[runnerUUIDLabel])
+	assert.True(t, manifest.Spec.AutomountServiceAccountToken)
+	assert.False(t, manifest.Spec.EnableServiceLinks)
+	assert.Equal(t, []string{"my-db"}, manifest.Spec.HostAliases[0].Hostnames)
+	require.Len(t, manifest.Spec.Containers, 2)
+	assert.Equal(t, map[string]any{"limits": map[string]any{"cpu": "2", "memory": "1Gi"}}, manifest.Spec.Containers[0].Resources)
+	assert.Empty(t, manifest.Spec.Containers[0].ImagePullPolicy)
+	assert.Equal(t, "my-db", manifest.Spec.Containers[1].Name)
+	assert.Equal(t, "Always", manifest.Spec.Containers[1].ImagePullPolicy)
+	assert.Equal(t, map[string]any{"limits": map[string]any{"memory": "256Mi"}}, manifest.Spec.Containers[1].Resources)
+	assert.Equal(t, []map[string]any{
+		{"name": "workspace", "emptyDir": map[string]any{"sizeLimit": "1Gi"}},
+		{"name": "act", "emptyDir": map[string]any{}},
+	}, manifest.Spec.Volumes)
+	assert.Equal(t, struct{ PeriodSeconds, TimeoutSeconds, FailureThreshold int }{2, 30, 5}, *manifest.Spec.Containers[1].StartupProbe)
+	assert.NotContains(t, cluster.requests["POST /api/v1/namespaces/ci/pods"][0], "service-secret")
+	assert.Contains(t, cluster.requests["POST /api/v1/namespaces/ci/secrets"][0], "service-secret")
+	assert.Contains(t, cluster.requests["POST /api/v1/namespaces/ci/secrets"][0], `"com.gitea.runner.uuid":"runner-uuid"`)
+	assert.Contains(t, cluster.requests["POST /api/v1/namespaces/ci/pods"][0], `{"name":"POSTGRES_PASSWORD","valueFrom":{"secretKeyRef":{"key":"my-db.0","name":"`+pod.secretName+`"}}}`)
+	assert.Equal(t, []any{"new"}, mergeManifest([]any{"old"}, []any{"new"}, ""))
+	mount := func(path string) any { return map[string]any{"name": "config", "mountPath": path} }
+	assert.Equal(t, []any{mount("/a"), mount("/b")}, mergeManifest([]any{mount("/a")}, []any{mount("/b")}, "volumeMounts"))
+	tmpfs := map[string]any{"name": "workspace", "emptyDir": map[string]any{"medium": "Memory"}}
+	ephemeral := map[string]any{"name": "workspace", "ephemeral": map[string]any{}}
+	assert.Equal(t, []any{ephemeral}, mergeManifest([]any{tmpfs}, []any{ephemeral}, "volumes"))
+	assert.Contains(t, cluster.requests["POST /api/v1/namespaces/ci/pods"][0], `"args":["postgres","-D","$$(PGDATA)"]`)
+
+	require.NoError(t, os.WriteFile(filepath.Join(workdir, "env"), []byte("#!/bin/sh\necho \"$@\" > \"$0-args\"\nexec /usr/bin/env \"$@\"\n"), 0o755))
+	t.Setenv("PATH", workdir+":"+os.Getenv("PATH"))
+	require.NoError(t, job.Start(false)(ctx))
+
+	stepEnv := map[string]string{"INPUT_WHO-TO-GREET": "it's\nme", "SECRET": "hunter2", "UID": "5"}
+	require.NoError(t, job.Exec([]string{"printenv", "SECRET"}, stepEnv, "", "")(ctx))
+	envArgs, err := os.ReadFile(filepath.Join(workdir, "env-args"))
+	require.NoError(t, err)
+	assert.NotContains(t, string(envArgs), "hunter2")
+	require.NoError(t, job.Exec([]string{"printenv", "INPUT_WHO-TO-GREET"}, stepEnv, "", "")(ctx))
+	require.NoError(t, job.Exec([]string{"printenv", "UID"}, stepEnv, "", "")(ctx))
+	require.NoError(t, job.Exec([]string{"pwd", "-P"}, nil, "", workdir)(ctx))
+	assert.Equal(t, "hunter2\nit's\nme\n5\n"+workdir+"\n", jobLog.String())
+	assert.Equal(t, ExitCodeError(3), job.Exec([]string{"sh", "-c", "echo failing >&2; exit 3"}, nil, "", "")(ctx))
+	assert.Contains(t, jobLog.String(), "failing\n")
+	for _, query := range cluster.requests["exec"] {
+		assert.NotContains(t, query, "hunter2")
+	}
+
+	require.NoError(t, job.Copy(workdir+"/act/", &FileEntry{Name: "workflow/event.json", Mode: 0o644, Body: `{"ref":"main"}`})(ctx))
+	archive, err := job.GetContainerArchive(ctx, workdir+"/act/workflow/event.json")
+	require.NoError(t, err)
+	reader := tar.NewReader(archive)
+	header, err := reader.Next()
+	require.NoError(t, err)
+	content, err := io.ReadAll(reader)
+	require.NoError(t, err)
+	assert.Equal(t, "event.json", header.Name)
+	assert.JSONEq(t, `{"ref":"main"}`, string(content))
+	require.NoError(t, archive.Close())
+	_, err = job.GetContainerArchive(ctx, workdir+"/missing")
+	require.Error(t, err)
+
+	pathEnv := map[string]string{}
+	require.NoError(t, job.UpdateFromImageEnv(&pathEnv)(ctx))
+	assert.Equal(t, os.Getenv("PATH"), pathEnv["PATH"])
+
+	info, err := service.Inspect(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, HealthHealthy, info.Health)
+	require.NoError(t, service.DumpLogs(ctx))
+	assert.Equal(t, "log of my-db", serviceLog.String())
+
+	require.NoError(t, job.Remove()(ctx))
+	assert.Len(t, cluster.requests["DELETE /api/v1/namespaces/ci/pods/"+pod.name], 1)
+	assert.Len(t, cluster.requests["DELETE /api/v1/namespaces/ci/secrets/"+pod.secretName], 1)
+
+	require.NoError(t, RemoveOrphanKubernetesResources(ctx, options, time.Now()))
+	assert.Equal(t, []string{runnerUUIDLabel + "=runner-uuid"}, cluster.requests["list"])
+	assert.Len(t, cluster.requests["DELETE /api/v1/namespaces/ci/pods/old"], 1)
+	assert.Len(t, cluster.requests["DELETE /api/v1/namespaces/ci/secrets/old"], 1)
+	assert.Empty(t, cluster.requests["DELETE /api/v1/namespaces/ci/pods/new"])
+	assert.Empty(t, cluster.requests["DELETE /api/v1/namespaces/ci/secrets/new"])
+}
+
+func TestKubernetesPodFailsBeforeSteps(t *testing.T) {
+	kubeconfig, _ := fakeKubernetes(t, `{"spec":{"containers":[{}]},"status":{"containerStatuses":[
+		{"name":"job","state":{"waiting":{"reason":"ErrImagePull","message":"no such image"}}}]}}`)
+	template := map[string]any{"spec": map[string]any{"containers": []any{map[string]any{"name": "sidecar"}}}}
+	for _, test := range []struct {
+		services     []string
+		options, err string
+	}{
+		{[]string{"db"}, "--hostname db", "only --health-* options are supported"},
+		{[]string{"sidecar"}, "", "named like another container"},
+		{[]string{"my_db", "My-DB"}, "", `service My-DB maps to container "my-db"`},
+	} {
+		pod, err := NewKubernetesPod(KubernetesOptions{Kubeconfig: kubeconfig, Namespace: "ci", PodTemplates: []map[string]any{template}})
+		require.NoError(t, err)
+		job := pod.JobContainer(&NewContainerInput{Image: "node"})
+		for _, service := range test.services {
+			pod.ServiceContainer(service, &NewContainerInput{Image: "postgres", WorkflowOptions: test.options})
+		}
+		require.ErrorContains(t, job.Create(nil, nil)(t.Context()), test.err)
+	}
+	pod, err := NewKubernetesPod(KubernetesOptions{Kubeconfig: kubeconfig, Namespace: "ci"})
+	require.NoError(t, err)
+	job := pod.JobContainer(&NewContainerInput{Image: "missing"})
+	require.NoError(t, job.Create(nil, nil)(t.Context()))
+	require.ErrorContains(t, job.Start(false)(t.Context()), "ErrImagePull: no such image")
+
+	plugin := filepath.Join(t.TempDir(), "kubeconfig")
+	require.NoError(t, os.WriteFile(plugin, []byte(`
+current-context: eks
+contexts: [{name: eks, context: {cluster: eks, user: eks}}]
+clusters: [{name: eks, cluster: {server: "https://eks.example"}}]
+users: [{name: eks, user: {exec: {command: aws}}}]
+`), 0o600))
+	_, err = NewKubernetesPod(KubernetesOptions{Kubeconfig: plugin})
+	require.ErrorContains(t, err, "credential plugin")
+}

act/container/parse_env_file.go

@@ -50,7 +50,7 @@ func parseEnvFile(e Container, srcPath string, env *map[string]string) common.Ex
 			case singleLineEnv != -1 && (multiLineEnv == -1 || singleLineEnv < multiLineEnv):
 				localEnv[line[:singleLineEnv]] = line[singleLineEnv+1:]
 			case multiLineEnv != -1:
-				multiLineEnvContent := ""
+				var multiLineEnvContent []string
 				multiLineEnvDelimiter := line[multiLineEnv+2:]
 				delimiterFound := false
 				for s.Scan() {
@@ -59,10 +59,7 @@ func parseEnvFile(e Container, srcPath string, env *map[string]string) common.Ex
 						delimiterFound = true
 						break
 					}
-					if multiLineEnvContent != "" {
-						multiLineEnvContent += "\n"
-					}
-					multiLineEnvContent += content
+					multiLineEnvContent = append(multiLineEnvContent, content)
 				}
 				if err := s.Err(); err != nil {
 					return fmt.Errorf("reading env file: %w", err)
@@ -70,7 +67,7 @@ func parseEnvFile(e Container, srcPath string, env *map[string]string) common.Ex
 				if !delimiterFound {
 					return fmt.Errorf("invalid format delimiter '%v' not found before end of file", multiLineEnvDelimiter)
 				}
-				localEnv[line[:multiLineEnv]] = multiLineEnvContent
+				localEnv[line[:multiLineEnv]] = strings.Join(multiLineEnvContent, "\n")
 			default:
 				return fmt.Errorf("invalid format '%v', expected a line with '=' or '<<'", line)
 			}

act/container/parse_env_file_test.go

@@ -86,6 +86,11 @@ func TestParseEnvFileMultiLineKeepsBlankLines(t *testing.T) {
 	env := map[string]string{}
 	require.NoError(t, parseEnvFile(e, envPath, &env)(context.Background()))
 	assert.Equal(t, "line1\n\nline2", env["FOO"])
+
+	require.NoError(t, os.WriteFile(envPath, []byte("FOO<<EOF\n\nline2\nEOF\n"), 0o600))
+	env = map[string]string{}
+	require.NoError(t, parseEnvFile(e, envPath, &env)(context.Background()))
+	assert.Equal(t, "\nline2", env["FOO"])
 }
 
 func TestParseEnvFileUTF8BOM(t *testing.T) {

act/container/tar.go

@@ -0,0 +1,69 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// Copyright 2020 The nektos/act Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package container
+
+import (
+	"archive/tar"
+	"context"
+	"io"
+	"path/filepath"
+	"strings"
+
+	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/filecollector"
+
+	"github.com/go-git/go-billy/v5/helper/polyfill"
+	"github.com/go-git/go-billy/v5/osfs"
+	"github.com/go-git/go-git/v5/plumbing/format/gitignore"
+)
+
+func writeFilesTar(ctx context.Context, w io.Writer, uid, gid int, files ...*FileEntry) error {
+	tw := tar.NewWriter(w)
+	for _, file := range files {
+		common.Logger(ctx).Debugf("Writing entry to tarball %s len:%d", file.Name, len(file.Body))
+		if err := tw.WriteHeader(&tar.Header{
+			Name: file.Name,
+			Mode: file.Mode,
+			Size: int64(len(file.Body)),
+			Uid:  uid,
+			Gid:  gid,
+		}); err != nil {
+			return err
+		}
+		if _, err := tw.Write([]byte(file.Body)); err != nil {
+			return err
+		}
+	}
+	return tw.Close()
+}
+
+// writeDirTar prefixes entries with dstPath for extraction at root.
+func writeDirTar(ctx context.Context, w io.Writer, dstPath, srcPath string, useGitIgnore, skipGitDir bool, uid, gid int) error {
+	logger := common.Logger(ctx)
+	tw := tar.NewWriter(w)
+	srcPrefix := strings.TrimSuffix(filepath.Dir(srcPath), string(filepath.Separator)) + string(filepath.Separator)
+	logger.Debugf("Stripping prefix:%s src:%s", srcPrefix, srcPath)
+
+	var ignorer gitignore.Matcher
+	if useGitIgnore {
+		ps, err := gitignore.ReadPatterns(polyfill.New(osfs.New(srcPath)), nil)
+		if err != nil {
+			logger.Debugf("Error loading .gitignore: %v", err)
+		}
+
+		ignorer = gitignore.NewMatcher(ps)
+	}
+
+	if err := filepath.Walk(srcPath, (&filecollector.FileCollector{
+		Ignorer:    ignorer,
+		SrcPath:    srcPath,
+		SrcPrefix:  srcPrefix,
+		SkipGitDir: skipGitDir,
+		Handler:    &filecollector.TarCollector{TarWriter: tw, UID: uid, GID: gid, DstDir: dstPath[1:]},
+	}).CollectFiles(ctx, []string{})); err != nil {
+		return err
+	}
+	return tw.Close()
+}

act/filecollector/file_collector.go

@@ -94,10 +94,11 @@ func (cc *CopyCollector) WriteFile(fpath string, fi fs.FileInfo, linkName string
 }
 
 type FileCollector struct {
-	Ignorer   gitignore.Matcher
-	SrcPath   string
-	SrcPrefix string
-	Handler   Handler
+	Ignorer    gitignore.Matcher
+	SrcPath    string
+	SrcPrefix  string
+	SkipGitDir bool
+	Handler    Handler
 }
 
 func openGitIndex(path string) (*index.Index, error) {
@@ -124,6 +125,12 @@ func (fc *FileCollector) CollectFiles(ctx context.Context, submodulePath []strin
 		if fi.IsDir() && len(split) > 0 && split[len(split)-1] == "." {
 			return nil
 		}
+		if fc.SkipGitDir && split[len(split)-1] == ".git" {
+			if fi.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
 		var entry *index.Entry
 		if i != nil {
 			entry, err = i.Entry(strings.Join(split[len(submodulePath):], "/"))

act/ghcontext/github_context.go

@@ -12,6 +12,7 @@ import (
 	"context"
 	"fmt"
 	"strings"
+	"sync"
 
 	"gitea.com/gitea/runner/act/common"
 	"gitea.com/gitea/runner/act/common/git"
@@ -25,6 +26,26 @@ var (
 	findGithubRepo  = git.FindGithubRepo
 )
 
+type pinnedKey struct{}
+
+// WithPinnedCheckout keeps a run's sha and ref fixed when HEAD moves.
+func WithPinnedCheckout(ctx context.Context) context.Context {
+	if ctx.Value(pinnedKey{}) != nil {
+		return ctx
+	}
+	return context.WithValue(ctx, pinnedKey{}, &sync.Map{})
+}
+
+func pinned(ctx context.Context, key string, lookup func() (string, error)) (string, error) {
+	cache, ok := ctx.Value(pinnedKey{}).(*sync.Map)
+	if !ok {
+		return lookup()
+	}
+	cached, _ := cache.LoadOrStore(key, sync.OnceValues(lookup))
+	lookupOnce, _ := cached.(func() (string, error))
+	return lookupOnce()
+}
+
 // SetRef resolves the ref of the context from its event payload, falling back
 // to the ref checked out in repoPath.
 func SetRef(ctx context.Context, ghc *model.GithubContext, repoPath string) {
@@ -51,7 +72,7 @@ func SetRef(ctx context.Context, ghc *model.GithubContext, repoPath string) {
 	}
 
 	if ghc.Ref == "" {
-		ref, err := findGitRef(ctx, repoPath)
+		ref, err := pinned(ctx, "ref:"+repoPath, func() (string, error) { return findGitRef(ctx, repoPath) })
 		if err != nil {
 			logger.Warningf("unable to get git ref: %v", err)
 		} else {
@@ -95,7 +116,10 @@ func SetSha(ctx context.Context, ghc *model.GithubContext, repoPath string) {
 	}
 
 	if ghc.Sha == "" {
-		_, sha, err := findGitRevision(ctx, repoPath)
+		sha, err := pinned(ctx, "sha:"+repoPath, func() (string, error) {
+			_, revision, err := findGitRevision(ctx, repoPath)
+			return revision, err
+		})
 		if err != nil {
 			logger.Warningf("unable to get git revision: %v", err)
 		} else {

act/ghcontext/github_context_test.go

@@ -214,4 +214,17 @@ func TestSetSha(t *testing.T) {
 			assert.Equal(t, table.sha, ghc.Sha)
 		})
 	}
+
+	t.Run("pinned checkout keeps the first sha and ref", func(t *testing.T) {
+		ctx := WithPinnedCheckout(context.Background())
+		for _, head := range []string{"first", "moved"} {
+			findGitRevision = func(context.Context, string) (string, string, error) { return "", head, nil }
+			findGitRef = func(context.Context, string) (string, error) { return "refs/heads/" + head, nil }
+			ghc := &model.GithubContext{Event: map[string]any{}}
+			SetSha(ctx, ghc, "/some/dir")
+			SetRef(ctx, ghc, "/some/dir")
+			assert.Equal(t, "first", ghc.Sha)
+			assert.Equal(t, "refs/heads/first", ghc.Ref)
+		}
+	})
 }

act/runner/action.go

@@ -6,6 +6,7 @@ package runner
 
 import (
 	"context"
+	"crypto/rand"
 	"crypto/sha256"
 	"embed"
 	"encoding/hex"
@@ -13,6 +14,7 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"maps"
 	"os"
 	"path"
 	"path/filepath"
@@ -32,7 +34,7 @@ type actionStep interface {
 	step
 
 	getActionModel() *model.Action
-	getCompositeRunContext(context.Context) *RunContext
+	getCompositeRunContext(context.Context) (*RunContext, error)
 	getCompositeSteps() *compositeSteps
 }
 
@@ -147,14 +149,14 @@ func maybeCopyToActionDir(ctx context.Context, step actionStep, actionDir, actio
 
 	if !rc.Config.NoActionPatch {
 		// A concurrent job's prepare resets this directory, so patch under the copy's lock.
-		patchActions(ctx, actionScriptPaths(filepath.Join(actionDir, actionPath), step.getActionModel()))
+		defer patchActions(ctx, actionScriptPaths(filepath.Join(actionDir, actionPath), step.getActionModel()))()
 	}
 
 	if err := removeGitIgnore(ctx, actionDir); err != nil {
 		return err
 	}
 
-	return rc.JobContainer.CopyDir(containerActionDirCopy, actionDir+"/", rc.Config.UseGitIgnore)(ctx)
+	return rc.JobContainer.CopyDir(containerActionDirCopy, actionDir+"/", rc.Config.UseGitIgnore, true)(ctx)
 }
 
 func runActionImpl(step actionStep, actionDir string, remoteAction *remoteAction) common.Executor {
@@ -172,7 +174,9 @@ func runActionImpl(step actionStep, actionDir string, remoteAction *remoteAction
 
 		rc.withGithubEnv(ctx, step.getGithubContext(ctx), *step.getEnv())
 		populateEnvsFromSavedState(step.getEnv(), step, rc)
-		populateEnvsFromInput(ctx, step.getEnv(), action, rc)
+		if err := populateEnvsFromInput(ctx, step.getEnv(), action, rc); err != nil {
+			return err
+		}
 
 		actionLocation := path.Join(actionDir, actionPath)
 		actionName, containerActionDir := getContainerActionPaths(stepModel, actionLocation, rc)
@@ -185,7 +189,7 @@ func runActionImpl(step actionStep, actionDir string, remoteAction *remoteAction
 			if err := maybeCopyToActionDir(ctx, step, actionDir, actionPath, containerActionDir); err != nil {
 				return err
 			}
-			containerArgs := []string{"node", path.Join(containerActionDir, action.Runs.Main)}
+			containerArgs := nodeActionCommand(path.Join(containerActionDir, action.Runs.Main))
 			logger.Debugf("executing remote job container: %s", containerArgs)
 
 			rc.ApplyExtraPath(ctx, step.getEnv())
@@ -232,6 +236,11 @@ func runActionImpl(step actionStep, actionDir string, remoteAction *remoteAction
 	}
 }
 
+// /var/run is a symlink, so without the flag node's import.meta.url differs from argv[1], which ESM actions compare.
+func nodeActionCommand(script string) []string {
+	return []string{"node", "--preserve-symlinks-main", script}
+}
+
 // https://github.com/nektos/act/issues/228#issuecomment-629709055
 // files in .gitignore are not copied in a Docker container
 // this causes issues with actions that ignore other important resources
@@ -279,11 +288,30 @@ func dockerActionImageTag(repository, actionName string, localAction bool) strin
 	return strings.ToLower(image)
 }
 
+// One image per step and job: its stages share a build, and concurrent jobs never run each other's.
+func (rc *RunContext) dockerActionImage(ctx context.Context, step actionStep, actionName string, localAction bool) string {
+	job := rc.topLevelRunContext()
+	if job.dockerActionImages == nil {
+		job.dockerActionImages = map[*model.Step]string{}
+	}
+	image, ok := job.dockerActionImages[step.getStepModel()]
+	if !ok {
+		image = dockerActionImageTag(step.getGithubContext(ctx).Repository, actionName, localAction) + "-" + strings.ToLower(rand.Text())
+		if !common.Dryrun(ctx) { // a dry run builds nothing to remove
+			job.dockerActionImages[step.getStepModel()] = image
+		}
+	}
+	return image
+}
+
 // TODO: break out parts of function to reduce complexicity
 func execAsDocker(ctx context.Context, step actionStep, actionName, actionDir, basedir string, localAction bool, stage stepStage) error {
 	logger := common.Logger(ctx)
 	rc := step.getRunContext()
 	action := step.getActionModel()
+	if rc.kubernetes {
+		return errKubernetesDocker
+	}
 
 	var prepImage common.Executor
 	var image string
@@ -293,7 +321,7 @@ func execAsDocker(ctx context.Context, step actionStep, actionName, actionDir, b
 		// Apply forcePull only for prebuild docker images
 		forcePull = rc.Config.ForcePull
 	} else {
-		image = dockerActionImageTag(step.getGithubContext(ctx).Repository, actionName, localAction)
+		image = rc.dockerActionImage(ctx, step, actionName, localAction)
 		contextDir, fileName := filepath.Split(filepath.Join(basedir, action.Runs.Image))
 
 		anyArchExists, err := ContainerImageExistsLocally(ctx, image, "any")
@@ -346,16 +374,24 @@ func execAsDocker(ctx context.Context, step actionStep, actionName, actionDir, b
 			logger.Debugf("image '%s' for architecture '%s' already exists", image, rc.Config.ContainerArchitecture)
 		}
 	}
-	eval := rc.NewActionInputsExpressionEvaluator(ctx, step)
-	cmd, err := shellquote.Split(eval.Interpolate(ctx, step.getStepModel().With["args"]))
+	cmd, err := shellquote.Split(step.getStepModel().With["args"])
 	if err != nil {
 		return err
 	}
-	if len(cmd) == 0 {
-		cmd = action.Runs.Args
-		evalDockerArgs(ctx, step, action, &cmd)
+	ee, err := evalDockerEnv(ctx, step, action)
+	if err != nil {
+		return err
 	}
-	entrypoint, err := dockerEntrypoint(ctx, step, eval, stage)
+	if action.Runs.Args != nil {
+		// a fresh slice, the manifest is evaluated again for every stage
+		cmd = make([]string, len(action.Runs.Args))
+		for i, v := range action.Runs.Args {
+			if cmd[i], err = ee.Interpolate(ctx, v); err != nil {
+				return fmt.Errorf("unable to interpolate runs.args: %w", err)
+			}
+		}
+	}
+	entrypoint, err := dockerEntrypoint(step, stage)
 	if err != nil {
 		return err
 	}
@@ -371,7 +407,7 @@ func execAsDocker(ctx context.Context, step actionStep, actionName, actionDir, b
 
 // dockerEntrypoint returns the entrypoint the action's image runs with for the given
 // stage. Only the main stage honours the `entrypoint` input.
-func dockerEntrypoint(ctx context.Context, step actionStep, eval *expressionEvaluator, stage stepStage) ([]string, error) {
+func dockerEntrypoint(step actionStep, stage stepStage) ([]string, error) {
 	runs := step.getActionModel().Runs
 
 	var entrypoint string
@@ -381,10 +417,12 @@ func dockerEntrypoint(ctx context.Context, step actionStep, eval *expressionEval
 	case stepStagePost:
 		entrypoint = runs.PostEntrypoint
 	default:
-		if fields := strings.Fields(eval.Interpolate(ctx, step.getStepModel().With["entrypoint"])); len(fields) > 0 {
-			return fields, nil
-		}
 		entrypoint = runs.Entrypoint
+		if entrypoint == "" {
+			if fields := strings.Fields(step.getStepModel().With["entrypoint"]); len(fields) > 0 {
+				return fields, nil
+			}
+		}
 	}
 
 	if entrypoint == "" {
@@ -393,33 +431,30 @@ func dockerEntrypoint(ctx context.Context, step actionStep, eval *expressionEval
 	return shellquote.Split(entrypoint)
 }
 
-func evalDockerArgs(ctx context.Context, step step, action *model.Action, cmd *[]string) {
+// evalDockerEnv returns an evaluator bound to the environment it installed.
+func evalDockerEnv(ctx context.Context, step step, action *model.Action) (*expressionEvaluator, error) {
 	rc := step.getRunContext()
-	stepModel := step.getStepModel()
 
+	var err error
 	inputs := make(map[string]string)
 	eval := rc.NewExpressionEvaluator(ctx)
 	// Set Defaults
 	for k, input := range action.Inputs {
-		inputs[k] = eval.Interpolate(ctx, input.Default)
-	}
-	if stepModel.With != nil {
-		for k, v := range stepModel.With {
-			inputs[k] = eval.Interpolate(ctx, v)
+		if inputs[k], err = eval.Interpolate(ctx, input.Default); err != nil {
+			return nil, fmt.Errorf("unable to interpolate the default of input %s: %w", k, err)
 		}
 	}
-	mergeIntoMap(step, step.getEnv(), inputs)
-
-	stepEE := rc.NewActionInputsExpressionEvaluator(ctx, step)
-	for i, v := range *cmd {
-		(*cmd)[i] = stepEE.Interpolate(ctx, v)
-	}
-	mergeIntoMap(step, step.getEnv(), action.Runs.Env)
+	mergeIntoMap(step, step.getEnv(), inputs, step.getStepModel().With)
 
 	ee := rc.NewActionInputsExpressionEvaluator(ctx, step)
-	for k, v := range *step.getEnv() {
-		(*step.getEnv())[k] = ee.Interpolate(ctx, v)
+	runsEnv := make(map[string]string, len(action.Runs.Env))
+	for k, v := range action.Runs.Env {
+		if runsEnv[k], err = ee.Interpolate(ctx, v); err != nil {
+			return nil, fmt.Errorf("unable to interpolate env %s: %w", k, err)
+		}
 	}
+	mergeIntoMap(step, step.getEnv(), runsEnv, maps.Clone(*step.getEnv()))
+	return ee, nil
 }
 
 func newStepContainer(ctx context.Context, step step, image string, cmd, entrypoint []string, runnerOptions string) container.Container {
@@ -427,14 +462,17 @@ func newStepContainer(ctx context.Context, step step, image string, cmd, entrypo
 	logWriter := rc.commandLogWriter(ctx)
 	envList := make([]string, 0)
 	for k, v := range *step.getEnv() {
+		if rc.IsHostEnv() && strings.EqualFold(k, rc.JobContainer.GetPathVariableName()) && v == rc.JobContainer.DefaultPathVariable() { // the runner's own PATH stays out, as on GitHub
+			continue
+		}
 		envList = append(envList, fmt.Sprintf("%s=%s", k, v))
 	}
 
 	envList = append(envList, rc.runnerEnv(ctx)...)
 
-	binds, mounts := rc.GetBindsAndMounts()
+	binds, mounts := rc.GetBindsAndMounts(ctx)
 	networkMode := "container:" + rc.jobContainerName()
-	if rc.IsHostEnv(ctx) {
+	if rc.IsHostEnv() {
 		networkMode = "default"
 	}
 	return ContainerNewContainer(&container.NewContainerInput{
@@ -469,15 +507,19 @@ func populateEnvsFromSavedState(env *map[string]string, step actionStep, rc *Run
 	}
 }
 
-func populateEnvsFromInput(ctx context.Context, env *map[string]string, action *model.Action, rc *RunContext) {
+func populateEnvsFromInput(ctx context.Context, env *map[string]string, action *model.Action, rc *RunContext) error {
 	eval := rc.NewExpressionEvaluator(ctx)
 	for inputID, input := range action.Inputs {
 		envKey := regexp.MustCompile("[^A-Z0-9-]").ReplaceAllString(strings.ToUpper(inputID), "_")
 		envKey = "INPUT_" + envKey
 		if _, ok := (*env)[envKey]; !ok {
-			(*env)[envKey] = eval.Interpolate(ctx, input.Default)
+			var err error
+			if (*env)[envKey], err = eval.Interpolate(ctx, input.Default); err != nil {
+				return fmt.Errorf("unable to interpolate the default of input %s: %w", inputID, err)
+			}
 		}
 	}
+	return nil
 }
 
 func getContainerActionPaths(step *model.Step, actionDir string, rc *RunContext) (string, string) {
@@ -577,16 +619,19 @@ func runPreStep(step actionStep) common.Executor {
 		actionDir, actionPath, _, containerActionDir := actionStagePaths(step)
 
 		x := action.Runs.Using
+		if !x.IsComposite() {
+			// defaults in pre steps were missing, however provided inputs are available
+			if err := populateEnvsFromInput(ctx, step.getEnv(), action, rc); err != nil {
+				return err
+			}
+		}
 		switch {
 		case x.IsNode():
-			// defaults in pre steps were missing, however provided inputs are available
-			populateEnvsFromInput(ctx, step.getEnv(), action, rc)
-
 			if err := maybeCopyToActionDir(ctx, step, actionDir, actionPath, containerActionDir); err != nil {
 				return err
 			}
 
-			containerArgs := []string{"node", path.Join(containerActionDir, action.Runs.Pre)}
+			containerArgs := nodeActionCommand(path.Join(containerActionDir, action.Runs.Pre))
 			logger.Debugf("executing remote job container: %s", containerArgs)
 
 			rc.ApplyExtraPath(ctx, step.getEnv())
@@ -594,14 +639,13 @@ func runPreStep(step actionStep) common.Executor {
 			return rc.JobContainer.Exec(containerArgs, *step.getEnv(), "", "")(ctx)
 
 		case x.IsDocker():
-			// defaults in pre steps were missing, however provided inputs are available
-			populateEnvsFromInput(ctx, step.getEnv(), action, rc)
-
 			return execDockerActionStage(ctx, step, stepStagePre)
 
 		case x.IsComposite():
 			if step.getCompositeSteps() == nil {
-				step.getCompositeRunContext(ctx)
+				if _, err := step.getCompositeRunContext(ctx); err != nil {
+					return err
+				}
 			}
 
 			if steps := step.getCompositeSteps(); steps != nil && steps.pre != nil {
@@ -610,9 +654,6 @@ func runPreStep(step actionStep) common.Executor {
 			return errors.New("missing steps in composite action")
 
 		case x == model.ActionRunsUsingGo:
-			// defaults in pre steps were missing, however provided inputs are available
-			populateEnvsFromInput(ctx, step.getEnv(), action, rc)
-
 			if err := maybeCopyToActionDir(ctx, step, actionDir, actionPath, containerActionDir); err != nil {
 				return err
 			}
@@ -687,7 +728,7 @@ func runPostStep(step actionStep) common.Executor {
 
 			populateEnvsFromSavedState(step.getEnv(), step, rc)
 
-			containerArgs := []string{"node", path.Join(containerActionDir, action.Runs.Post)}
+			containerArgs := nodeActionCommand(path.Join(containerActionDir, action.Runs.Post))
 			logger.Debugf("executing remote job container: %s", containerArgs)
 
 			rc.ApplyExtraPath(ctx, step.getEnv())

act/runner/action_composite.go

@@ -7,6 +7,7 @@ package runner
 import (
 	"context"
 	"errors"
+	"fmt"
 	"regexp"
 	"slices"
 	"strconv"
@@ -17,7 +18,7 @@ import (
 	"gitea.dev/actionslib/pkg/model"
 )
 
-func evaluateCompositeInputAndEnv(ctx context.Context, parent *RunContext, step actionStep) map[string]string {
+func evaluateCompositeInputAndEnv(ctx context.Context, parent *RunContext, step actionStep) (map[string]string, error) {
 	env := make(map[string]string)
 	stepEnv := *step.getEnv()
 	for k, v := range stepEnv {
@@ -28,7 +29,7 @@ func evaluateCompositeInputAndEnv(ctx context.Context, parent *RunContext, step
 		}
 	}
 
-	ee := parent.NewActionInputsExpressionEvaluator(ctx, step)
+	ee := parent.NewStepExpressionEvaluator(ctx, step)
 
 	for inputID, input := range step.getActionModel().Inputs {
 		envKey := regexp.MustCompile("[^A-Z0-9-]").ReplaceAllString(strings.ToUpper(inputID), "_")
@@ -36,23 +37,44 @@ func evaluateCompositeInputAndEnv(ctx context.Context, parent *RunContext, step
 
 		// lookup if key is defined in the step but the already
 		// evaluated value from the environment
-		_, defined := step.getStepModel().With[inputID]
+		defined := false
+		for key := range step.getStepModel().With {
+			if strings.EqualFold(key, inputID) {
+				defined = true
+				break
+			}
+		}
 		if value, ok := stepEnv[envKey]; defined && ok {
 			env[envKey] = value
 		} else {
 			// defaults could contain expressions
-			env[envKey] = ee.Interpolate(ctx, input.Default)
+			var err error
+			if env[envKey], err = ee.Interpolate(ctx, input.Default); err != nil {
+				return nil, fmt.Errorf("unable to interpolate the default of input %s: %w", inputID, err)
+			}
 		}
 	}
 	gh := step.getGithubContext(ctx)
 	env["GITHUB_ACTION_REPOSITORY"] = gh.ActionRepository
 	env["GITHUB_ACTION_REF"] = gh.ActionRef
 
-	return env
+	return env, nil
 }
 
-func newCompositeRunContext(ctx context.Context, parent *RunContext, step actionStep, actionPath string) *RunContext {
-	env := evaluateCompositeInputAndEnv(ctx, parent, step)
+func (rc *RunContext) setCompositeActionEnv(env map[string]string) {
+	rc.setActionEnv(env)
+	for key := range rc.Env {
+		if strings.HasPrefix(key, "INPUT_") {
+			delete(rc.Env, key)
+		}
+	}
+}
+
+func newCompositeRunContext(ctx context.Context, parent *RunContext, step actionStep, actionPath string) (*RunContext, error) {
+	env, err := evaluateCompositeInputAndEnv(ctx, parent, step)
+	if err != nil {
+		return nil, err
+	}
 
 	// run with the global config but without secrets
 	configCopy := *parent.Config
@@ -62,29 +84,34 @@ func newCompositeRunContext(ctx context.Context, parent *RunContext, step action
 	compositerc := &RunContext{
 		Name:    parent.Name,
 		JobName: parent.JobName,
+		Matrix:  parent.Matrix,
 		Run: &model.Run{
 			JobID: parent.Run.JobID,
 			Workflow: &model.Workflow{
 				Name: parent.Run.Workflow.Name,
 				Jobs: map[string]*model.Job{
-					parent.Run.JobID: {},
+					parent.Run.JobID: {Strategy: parent.Run.Job().Strategy},
 				},
 			},
 		},
-		Config:       &configCopy,
-		StepResults:  map[string]*model.StepResult{},
-		JobContainer: parent.JobContainer,
-		ActionPath:   actionPath,
-		GlobalEnv:    parent.GlobalEnv,
-		Masks:        parent.Masks,
-		ExtraPath:    parent.ExtraPath,
-		Parent:       parent,
-		EventJSON:    parent.EventJSON,
+		Config:        &configCopy,
+		StepResults:   map[string]*model.StepResult{},
+		JobContainer:  parent.JobContainer,
+		ActionPath:    actionPath,
+		GlobalEnv:     parent.GlobalEnv,
+		Masks:         parent.Masks,
+		ExtraPath:     parent.ExtraPath,
+		Parent:        parent,
+		EventJSON:     parent.EventJSON,
+		platformImage: parent.platformImage,
+		kubernetes:    parent.kubernetes,
+		jobIndex:      parent.jobIndex,
+		jobTotal:      parent.jobTotal,
 	}
-	compositerc.setActionEnv(env)
+	compositerc.setCompositeActionEnv(env)
 	compositerc.ExprEval = compositerc.NewExpressionEvaluator(ctx)
 
-	return compositerc
+	return compositerc, nil
 }
 
 // appendUniqueMasks appends the masks from src to dst, skipping any mask that
@@ -105,7 +132,10 @@ func execAsComposite(step actionStep) common.Executor {
 	action := step.getActionModel()
 
 	return func(ctx context.Context) error {
-		compositeRC := step.getCompositeRunContext(ctx)
+		compositeRC, err := step.getCompositeRunContext(ctx)
+		if err != nil {
+			return err
+		}
 
 		steps := step.getCompositeSteps()
 
@@ -115,14 +145,17 @@ func execAsComposite(step actionStep) common.Executor {
 
 		ctx = WithCompositeLogger(ctx, &compositeRC.Masks)
 
-		err := steps.main(ctx)
+		err = steps.main(ctx)
 
 		// Map outputs from composite RunContext to job RunContext
 		eval := compositeRC.NewExpressionEvaluator(ctx)
 		for outputName, output := range action.Outputs {
-			rc.setOutput(ctx, map[string]string{
-				"name": outputName,
-			}, eval.Interpolate(ctx, output.Value))
+			value, outputErr := eval.Interpolate(ctx, output.Value)
+			if outputErr != nil {
+				err = errors.Join(err, fmt.Errorf("unable to interpolate output %s: %w", outputName, outputErr))
+				continue
+			}
+			rc.setOutput(ctx, map[string]string{"name": outputName}, value)
 		}
 
 		// compositeRC.Masks is seeded with rc.Masks (see newCompositeRunContext)
@@ -131,7 +164,7 @@ func execAsComposite(step actionStep) common.Executor {
 		// repeated composite actions grow rc.Masks exponentially.
 		rc.Masks = appendUniqueMasks(rc.Masks, compositeRC.Masks)
 		rc.ExtraPath = compositeRC.ExtraPath
-		// compositeRC.Env is dirty, contains INPUT_ and merged step env, only rely on compositeRC.GlobalEnv
+		// Propagate GlobalEnv only, so composite inputs and step-local values do not escape.
 		mergeIntoMap := mergeIntoMapCaseSensitive
 		if rc.JobContainer.IsEnvironmentCaseInsensitive() {
 			mergeIntoMap = mergeIntoMapCaseInsensitive
@@ -194,6 +227,7 @@ func (rc *RunContext) compositeExecutor(action *model.Action) *compositeSteps {
 	}
 
 	steps = append(steps, common.JobError)
+	preSteps = append(preSteps, common.JobError)
 	return &compositeSteps{
 		pre: func(ctx context.Context) error {
 			return common.NewPipelineExecutor(preSteps...)(common.WithJobErrorContainer(ctx))