fix: coerce every expression value kind to a string and drop the format() panic (#1135)

`coerceToString` covered only a few kinds and returned the unconverted `reflect.Value` for the rest, so callers rendered contexts as `<*model.GithubContext Value>` and mangled sized integers and floats the same way. It now returns a string, which makes that placeholder unrepresentable, and is exported as `CoerceToString` so Gitea can drop its own diverging copy. It also takes an already reflected value, so internal callers need no conversion and no guard against the zero `Value`.

`format()` panicked whenever a lone `}` was followed by anything other than another `}`. Only a trailing `}` reached the existing unmatched-brace check, so an expression such as `format('a}b')`, which any workflow can write, took the process down instead. It now returns that same error.

Reviewed-on: https://gitea.com/gitea/runner/pulls/1135
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>

.gitea/workflows/pull-pr-title.yml

@@ -18,8 +18,8 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-    - uses: actions/setup-node@v6
+    - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
       with:
         node-version: 24
     - run: make lint-pr-title

.gitea/workflows/release-nightly.yml

@@ -17,14 +17,26 @@ jobs:
   goreleaser:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-go@v6
+      # Custom publishers (the R2 mirror below) run as the very last
+      # step of goreleaser's publish pipeline, after the Gitea release
+      # has already been created and every artifact already uploaded
+      # to S3. Fail here instead, before anything is built or
+      # published, if the R2 secrets are missing.
+      - name: check R2 configuration
+        run: sh scripts/upload-r2.sh --check-config
+        env:
+          R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: "go.mod"
       - name: goreleaser
-        uses: goreleaser/goreleaser-action@v7
+        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
         with:
           distribution: goreleaser-pro
           args: release --nightly
@@ -35,6 +47,10 @@ jobs:
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           S3_REGION: ${{ secrets.AWS_REGION }}
           S3_BUCKET: ${{ secrets.AWS_BUCKET }}
+          R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
           GORELEASER_FORCE_TOKEN: "gitea"
           GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -43,27 +59,33 @@ jobs:
     strategy:
       matrix:
         variant:
+          # The basic image is built from source and can target any arch the
+          # toolchain supports. The dind variants are limited to the arches the
+          # docker:dind base image publishes.
           - target: basic
             tag_suffix: ""
+            platforms: linux/amd64,linux/arm64,linux/riscv64,linux/s390x
           - target: dind
             tag_suffix: "-dind"
+            platforms: linux/amd64,linux/arm64
           - target: dind-rootless
             tag_suffix: "-dind-rootless"
+            platforms: linux/amd64,linux/arm64
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
+        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
 
       - name: Login to DockerHub
-        uses: docker/login-action@v4
+        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
@@ -77,14 +99,12 @@ jobs:
           echo REPO_VERSION=$(git describe --tags --always | sed 's/-/+/' | sed 's/^v//') >> $GITHUB_OUTPUT
 
       - name: Build and push
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
         with:
           context: .
           file: ./Dockerfile
           target: ${{ matrix.variant.target }}
-          platforms: |
+          platforms: ${{ matrix.variant.platforms }}
-            linux/amd64
-            linux/arm64
           push: true
           tags: |
             ${{ env.DOCKER_ORG }}/runner:nightly${{ matrix.variant.tag_suffix }}

.gitea/workflows/release-tag.yml

@@ -9,21 +9,33 @@ jobs:
   goreleaser:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0 # all history for all branches and tags
-      - uses: actions/setup-go@v6
+      # Custom publishers (the R2 mirror below) run as the very last
+      # step of goreleaser's publish pipeline, after the Gitea release
+      # has already been created and every artifact already uploaded
+      # to S3. Fail here instead, before anything is built or
+      # published, if the R2 secrets are missing.
+      - name: check R2 configuration
+        run: sh scripts/upload-r2.sh --check-config
+        env:
+          R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: "go.mod"
       - name: Import GPG key
         id: import_gpg
-        uses: crazy-max/ghaction-import-gpg@v7
+        uses: crazy-max/ghaction-import-gpg@2dc316deee8e90f13e1a351ab510b4d5bc0c82cd # v7
         with:
           gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
           passphrase: ${{ secrets.PASSPHRASE }}
           fingerprint: CC64B1DB67ABBEECAB24B6455FC346329753F4B0
       - name: goreleaser
-        uses: goreleaser/goreleaser-action@v7
+        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
         with:
           distribution: goreleaser-pro
           args: release
@@ -34,6 +46,10 @@ jobs:
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           S3_REGION: ${{ secrets.AWS_REGION }}
           S3_BUCKET: ${{ secrets.AWS_BUCKET }}
+          R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
           GORELEASER_FORCE_TOKEN: "gitea"
           GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }}
@@ -42,12 +58,18 @@ jobs:
     strategy:
       matrix:
         variant:
+          # The basic image is built from source and can target any arch the
+          # toolchain supports. The dind variants are limited to the arches the
+          # docker:dind base image publishes.
           - target: basic
             tag_suffix: ""
+            platforms: linux/amd64,linux/arm64,linux/riscv64,linux/s390x
           - target: dind
             tag_suffix: "-dind"
+            platforms: linux/amd64,linux/arm64
           - target: dind-rootless
             tag_suffix: "-dind-rootless"
+            platforms: linux/amd64,linux/arm64
     container:
       image: catthehacker/ubuntu:act-latest
     env:
@@ -55,25 +77,25 @@ jobs:
       DOCKER_LATEST: latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
+        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
 
       - name: Login to DockerHub
-        uses: docker/login-action@v4
+        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
 
       - name: "Docker meta"
         id: docker_meta
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
         with:
           images: |
             ${{ env.DOCKER_ORG }}/runner
@@ -86,14 +108,12 @@ jobs:
             suffix=${{ matrix.variant.tag_suffix }},onlatest=true
 
       - name: Build and push
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
         with:
           context: .
           file: ./Dockerfile
           target: ${{ matrix.variant.target }}
-          platforms: |
+          platforms: ${{ matrix.variant.platforms }}
-            linux/amd64
-            linux/arm64
           push: true
           tags: ${{ steps.docker_meta.outputs.tags }}
           build-args: |

.gitea/workflows/test.yml

@@ -9,14 +9,42 @@ jobs:
   lint:
     name: check and test
     runs-on: ubuntu-latest
+    env:
+      # The runner image ships a stale docker.io login; point docker at an empty config so
+      # image pulls go straight to anonymous instead of attempting (and failing) that auth
+      # first. The path must be a literal: the `runner` context is unavailable in job-level
+      # env, so `${{ runner.temp }}` would resolve to empty and config.Dir() would fall back
+      # to ~/.docker with the stale credentials.
+      DOCKER_CONFIG: /tmp/docker-noauth
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-go@v6
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: 'go.mod'
+      - name: prepare anonymous docker config
+        run: mkdir -p "$DOCKER_CONFIG" && echo '{}' > "$DOCKER_CONFIG/config.json"
+      # Pre-pull act/runner's two largest base images so a slow pull can't dominate `make test`;
+      # the rest (alpine/ubuntu) pull on demand, absorbed by the make-test -timeout. The host
+      # daemon retains them between runs, so this is usually a fast manifest re-check.
+      - name: pre-pull test images
+        run: |
+          for img in node:24-bookworm-slim nginx:alpine; do
+            for try in 1 2 3; do docker pull "$img" && break || sleep 5; done
+          done
       - name: lint
         run: make lint
+      - name: checks
+        run: make checks
       - name: build
         run: make build
       - name: test
         run: make test
+      # Build the dind image and run the daemon-facing tests against the docker version it
+      # ships, catching daemon-level regressions (e.g. gitea/runner#981) before release. Runs
+      # 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: coverage report
+        run: |
+          make coverage-report
+          cat .tmp/coverage.md >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -2,7 +2,9 @@
 .env
 !/act/runner/testdata/secrets/.env
 .runner
+.runner.lock
 coverage.txt
+.tmp/
 /config.yaml
 
 # Jetbrains
@@ -12,3 +14,4 @@ coverage.txt
 __debug_bin
 # gorelease binary folder
 /dist
+.DS_Store

.golangci.yml

@@ -11,6 +11,7 @@ linters:
     - dupl
     - errcheck
     - forbidigo
+    - forcetypeassert
     - gocheckcompilerdirectives
     - gocritic
     - goheader
@@ -36,12 +37,8 @@ linters:
       rules:
         main:
           deny:
-            - pkg: io/ioutil
-              desc: use os or io instead
             - pkg: golang.org/x/exp
               desc: it's experimental and unreliable
-            - pkg: github.com/pkg/errors
-              desc: use builtin errors package instead
     nolintlint:
       allow-unused: false
       require-explanation: true
@@ -102,6 +99,9 @@ linters:
       - linters:
           - forbidigo
         path: cmd
+      - linters:
+          - forcetypeassert
+        path: _test\.go
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0

.goreleaser.yaml

@@ -93,6 +93,37 @@ blobs:
       - glob: ./**.xz
       - glob: ./**.sha256
 
+# Mirrors the S3 `blobs:` upload above into Cloudflare R2 during the
+# parallel S3+R2 period (S3 will be removed once migration completes).
+# A second `blobs:` entry is impossible here since the blob pipe
+# authenticates from the global AWS_* env with no per-entry
+# credentials; `publishers:` supports per-entry `env:` instead, so
+# it's used to invoke scripts/upload-r2.sh once per artifact. Custom
+# publishers inherit almost nothing from the environment, hence the
+# explicit R2_* forwarding below.
+#
+# This publisher fires 109 times for 73 distinct keys because
+# goreleaser's release pipe already registers `release.extra_files`
+# as UploadableFile artifacts, and `internal/exec`'s filterArtifacts
+# appends this block's own extra_files with no de-duplication. It
+# can't be globbed away, since gobwas/glob (via goreleaser/fileglob)
+# has no substring-exclusion matcher. It's harmless: PUT is
+# idempotent, and the `./**.xz` glob below is kept deliberately so
+# this publisher declares its own complete file set rather than
+# implicitly depending on the `release:` block's globs.
+publishers:
+  - name: cloudflare-r2
+    checksum: true
+    extra_files:
+      - glob: ./**.xz
+      - glob: ./**.sha256
+    cmd: sh scripts/upload-r2.sh {{ abs .ArtifactPath }} gitea-runner/{{ .Version }}/{{ .ArtifactName }}
+    env:
+      - R2_ENDPOINT={{ index .Env "R2_ENDPOINT" }}
+      - R2_BUCKET={{ index .Env "R2_BUCKET" }}
+      - R2_ACCESS_KEY_ID={{ index .Env "R2_ACCESS_KEY_ID" }}
+      - R2_SECRET_ACCESS_KEY={{ index .Env "R2_SECRET_ACCESS_KEY" }}
+
 archives:
   - format: binary
     name_template: "{{ .Binary }}"

AGENTS.md

@@ -1,10 +1,18 @@
+- Never assume, verify before claiming
 - Use `make help` to find available development targets
-- Run `make fmt` to format `.go` files, and run `make lint-go` to lint them
+- PR descriptions: minimal, only what and why, no task lists or file listings
-- Run `make tidy` after any `go.mod` changes
+- Reference issues and PRs by full URL, not by number
-- Run single go unit tests with `go test -run '^TestName$' ./modulepath/`
+- Use Conventional Commits for commit messages and PR titles, plus the `enhance` type for user-facing enhancements
+- Add an `Assisted-by: AGENT_NAME:MODEL_VERSION` trailer to commit messages, never `Co-Authored-By` or `Signed-off-by`
+- Attribute agent authorship on one trailing line in issue and pull request comments, never as a PR description section
+- Never force-push, amend, or squash unless asked. Use new commits and normal push for pull request updates
+- Comments: write almost none, short and preferably same-line, explaining why for a future reader. Never narrate code, the change or the prompt. Preserve existing ones that still apply
 - Add the current year into the copyright header of new `.go` files
 - Ensure no trailing whitespace in edited files
-- Never force-push, amend, or squash unless asked. Use new commits and normal push for pull request updates
+- Run `make fmt` after `.go` edits, `make tidy` after `go.mod` edits, and `make checks` for the non-lint source checks
-- Preserve existing code comments, do not remove or rewrite comments that are still relevant
+- Lint what changed with `make lint-go`, and `make lint-go-windows` for Windows and platform-split files
-- Include authorship attribution in issue and pull request comments
+- Fix the cause rather than disabling a linter or weakening a test. Where unavoidable, use the narrowest scope with a trailing comment giving the reason
-- Add `Co-Authored-By` lines to all commits, indicating name and model used
+- Run single go tests with `go test -run '^TestName$' ./modulepath/`. `make test` self-skips the integration tests without docker or network, `make test-dind` runs the daemon-facing tests against the built dind image
+- Write the fewest, fastest tests covering the behavior, extending an existing one where possible. Prefer unit tests where logic is testable in isolation
+- Wait on a deterministic condition rather than `sleep`
+- Update the files under `docs/` when behavior documented there changes

Dockerfile

@@ -17,14 +17,14 @@ RUN make clean && make build
 ### DIND VARIANT
 #
 #
-FROM docker:29.5.2-dind AS dind
+FROM docker:29.6.2-dind AS dind
 
 ARG VERSION=dev
 
 LABEL org.opencontainers.image.source="https://gitea.com/gitea/runner"
 LABEL org.opencontainers.image.version="${VERSION}"
 
-RUN apk add --no-cache s6 bash git tzdata
+RUN apk add --no-cache s6 bash git tzdata nftables
 
 COPY --from=builder /opt/src/runner/gitea-runner /usr/local/bin/gitea-runner
 COPY scripts/run.sh /usr/local/bin/run.sh
@@ -37,7 +37,7 @@ ENTRYPOINT ["s6-svscan","/etc/s6"]
 ### DIND-ROOTLESS VARIANT
 #
 #
-FROM docker:29.5.2-dind-rootless AS dind-rootless
+FROM docker:29.6.2-dind-rootless AS dind-rootless
 
 ARG VERSION=dev
 
@@ -45,7 +45,7 @@ LABEL org.opencontainers.image.source="https://gitea.com/gitea/runner"
 LABEL org.opencontainers.image.version="${VERSION}"
 
 USER root
-RUN apk add --no-cache s6 bash git tzdata
+RUN apk add --no-cache s6 bash git tzdata nftables
 
 COPY --from=builder /opt/src/runner/gitea-runner /usr/local/bin/gitea-runner
 COPY scripts/run.sh /usr/local/bin/run.sh
@@ -63,7 +63,7 @@ ENTRYPOINT ["s6-svscan","/etc/s6"]
 ### BASIC VARIANT
 #
 #
-FROM alpine:3.23 AS basic
+FROM alpine:3.24 AS basic
 
 ARG VERSION=dev
 

Makefile

@@ -4,9 +4,9 @@ DIST_DIRS := $(DIST)/binaries $(DIST)/release
 GO ?= go
 SHASUM ?= shasum -a 256
 HAS_GO = $(shell hash $(GO) > /dev/null 2>&1 && echo "GO" || echo "NOGO" )
-XGO_PACKAGE ?= src.techknowlogick.com/xgo@latest
+XGO_PACKAGE ?= src.techknowlogick.com/xgo@v1.9.0 # renovate: datasource=go
 XGO_VERSION := go-1.26.x
-GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/[email protected]0
+GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/[email protected]5 # renovate: datasource=go
 
 LINUX_ARCHS ?= linux/amd64,linux/arm64
 DARWIN_ARCHS ?= darwin-12/amd64,darwin-12/arm64
@@ -18,8 +18,10 @@ DOCKER_TAG ?= nightly
 DOCKER_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)
 DOCKER_ROOTLESS_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)-dind-rootless
 
-GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/[email protected]
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/[email protected] # renovate: datasource=go
-GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/[email protected]
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/[email protected] # renovate: datasource=go
+
+GOTEST_FLAGS ?= -race -timeout 20m -parallel 8
 
 STATIC ?=
 EXTLDFLAGS ?=
@@ -38,12 +40,15 @@ endif
 ifeq ($(OS), Windows_NT)
 	GOFLAGS := -v -buildmode=exe
 	EXECUTABLE ?= $(EXECUTABLE).exe
+	GO_ENV_WINDOWS := set GOOS=windows&&
 else ifeq ($(OS), Windows)
 	GOFLAGS := -v -buildmode=exe
 	EXECUTABLE ?= $(EXECUTABLE).exe
+	GO_ENV_WINDOWS := set GOOS=windows&&
 else
 	GOFLAGS := -v
 	EXECUTABLE ?= $(EXECUTABLE)
+	GO_ENV_WINDOWS := GOOS=windows
 endif
 
 STORED_VERSION_FILE := VERSION
@@ -92,7 +97,7 @@ go-check:
 
 .PHONY: fmt-check
 fmt-check: fmt
-	@diff=$$(git diff --color=always); \
+	@diff=$$(git diff --color=always -- '*.go'); \
 	if [ -n "$$diff" ]; then \
 		echo "Please run 'make fmt' and commit the result:"; \
 		printf "%s" "$${diff}"; \
@@ -107,13 +112,21 @@ deps-tools: ## install tool dependencies
 	$(GO) install $(GOVULNCHECK_PACKAGE) & \
 	wait
 
+.PHONY: checks
+checks: tidy-check fmt-check security-check ## run the non-lint source checks
+
 .PHONY: lint
-lint: lint-go ## lint everything
+lint: lint-go lint-go-windows ## lint everything
 
 .PHONY: lint-go
 lint-go: ## lint go files
 	$(GO) run $(GOLANGCI_LINT_PACKAGE) run
 
+.PHONY: lint-go-windows
+lint-go-windows: ## lint Windows go files
+	$(GO) install $(GOLANGCI_LINT_PACKAGE)
+	$(GO_ENV_WINDOWS) golangci-lint run
+
 .PHONY: lint-go-fix
 lint-go-fix: ## lint go files and fix issues
 	$(GO) run $(GOLANGCI_LINT_PACKAGE) run --fix
@@ -123,7 +136,7 @@ lint-pr-title: ## lint PR title against Conventional Commits (set PR_TITLE=...)
 	@node ./tools/lint-pr-title.ts
 
 .PHONY: security-check
-security-check: deps-tools
+security-check:
 	GOEXPERIMENT= $(GO) run $(GOVULNCHECK_PACKAGE) -show color ./... || true
 
 .PHONY: tidy
@@ -140,8 +153,18 @@ tidy-check: tidy
 	fi
 
 .PHONY: test
-test: fmt-check security-check ## test everything
+test: ## test everything (integration tests self-skip without docker/network)
-	@$(GO) test -race -short -v -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
+	@$(GO) test $(GOTEST_FLAGS) -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
+
+.PHONY: coverage-report
+coverage-report: ## turn coverage.txt from `make test` into .tmp/coverage.md
+	@mkdir -p .tmp
+	@node ./tools/coverage-report.ts -i coverage.txt -o .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)
 
 .PHONY: install
 install: $(GOFILES) ## install the runner binary via `go install`
@@ -206,7 +229,7 @@ docker: ## build the docker image
 .PHONY: clean
 clean: ## delete binary and coverage files
 	$(GO) clean -x -i ./...
-	rm -rf coverage.txt $(EXECUTABLE) $(DIST)
+	rm -rf coverage.txt .tmp $(EXECUTABLE) $(DIST)
 
 .PHONY: version
 version: ## print the version

README.md

@@ -85,6 +85,48 @@ docker run -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRA
 
 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:
+
+```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
+```
+
+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.
+
+#### `latest-dind-rootless` — rootless Docker-in-Docker
+
+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).
+
+> **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.
+
 ### Configuration
 
 The runner is configured with a YAML file. Generate a starting point (this matches what ships in the tree):
@@ -105,26 +147,146 @@ Every option is described in [config.example.yaml](internal/pkg/config/config.ex
 
 #### Without a config file
 
-If you omit `-c`, built-in defaults apply (same as an empty YAML document). A small set of **deprecated** environment variables can still override parts of that default config, but **only when no `-c` path was given**; they are ignored if you use a config file:
+If you omit `-c`, built-in defaults apply (same as an empty YAML document).
 
-| Variable | Effect |
+Earlier releases let a small set of environment variables (`GITEA_DEBUG`, `GITEA_TRACE`, `GITEA_RUNNER_CAPACITY`, `GITEA_RUNNER_FILE`, `GITEA_RUNNER_ENVIRON`, `GITEA_RUNNER_ENV_FILE`) override parts of the default config. Those overrides have been removed — use a YAML config file for all settings instead. For the Docker images, the entrypoint still understands a separate set of variables (such as `RUNNER_STATE_FILE`); see [scripts/run.sh](scripts/run.sh) and the container documentation below.
+
+### Labels
+
+Labels decide **which jobs a runner accepts** and **how it runs them**. A job's `runs-on` is matched against the runner's label names; the first match wins and selects the execution environment for that job.
+
+A label is written as:
+
+```text
+<name>[:<schema>[:<args>]]
+```
+
+| Part | Meaning |
 | --- | --- |
-| `GITEA_DEBUG` | If true, sets log level to `debug` |
+| `name` | The name a workflow refers to in `runs-on`, e.g. `ubuntu-latest`. |
-| `GITEA_TRACE` | If true, sets log level to `trace` |
+| `schema` | Either `docker` or `host`. Defaults to `host` when omitted. |
-| `GITEA_RUNNER_CAPACITY` | Concurrent jobs (integer) |
+| `args` | Only used by the `docker` schema: the image to run the job in. |
-| `GITEA_RUNNER_FILE` | Registration state file path (default `.runner`) |
-| `GITEA_RUNNER_ENVIRON` | Extra job env vars as comma-separated `KEY:VALUE` pairs |
-| `GITEA_RUNNER_ENV_FILE` | Path to an env file merged into job env (same idea as `runner.env_file` in YAML) |
 
-Prefer a YAML file for all settings.
+Two schemas are supported:
+
+- **`docker://<image>`** — the job runs inside a container created from `<image>`:
+
+  ```text
+  ubuntu-latest:docker://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
+  macos:host
+  ```
+
+So with the labels
+
+```text
+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.
+
+If a job's `runs-on` matches none of the runner's labels, the job still runs, in the default `docker.gitea.com/runner-images:ubuntu-latest` image. 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.
 
 #### Registration vs config labels
 
 If `runner.labels` is set in the YAML file, those labels are used during `register` and the `--labels` CLI flag is ignored.
 
-#### External cache (`actions/cache`)
+The `daemon` command also accepts `--labels` (which defaults to the `GITEA_RUNNER_LABELS` environment variable), so the labels of an already registered runner can be changed without deleting its registration file. The most explicit source wins:
 
-If `cache.external_server` is set, you must set `cache.external_secret` to the same value on this runner and on the standalone cache server. Run the server with `gitea-runner cache-server` using a config that defines `cache.external_secret` (and matching `cache.dir` / host / port as needed). Flags `--dir`, `--host`, and `--port` on `cache-server` override the file.
+```
+--labels / GITEA_RUNNER_LABELS   >   runner.labels in the config file   >   labels in the .runner file
+```
+
+Whenever the resulting labels differ from the ones in the registration file, they are written back to it and re-declared to the Gitea instance on startup.
+
+> **Note:** A runner that only exposes `host` labels still needs access to a Docker daemon (e.g. a mounted `/var/run/docker.sock`) whenever a job uses a `docker://` action or a service container. `host` labels only change where the job's own steps run; container-based steps and actions are still executed with Docker.
+
+#### Proxy
+
+Set these variables in the runner's environment, with systemd `Environment=`, `docker run -e`, or Kubernetes `env:`:
+
+```sh
+http_proxy=http://proxy.example:3128
+https_proxy=http://proxy.example:3128
+no_proxy=gitea.internal,.example.local
+```
+
+The runner uses them for its own requests and gives them to every job, in lower and upper case.
+
+These hosts are added to `no_proxy` for jobs, so they are always reached directly:
+
+- the cache server
+- `localhost`, `127.0.0.1` and `::1`
+- the job's service containers
+- the Docker daemon, when it is reached over `tcp://`
+
+Gitea is not added. Add it to `no_proxy` yourself if it should be reached directly.
+
+To change a value for one job, set it in a step's `env:` or in the job's `container.env`. Setting it at workflow or job level has no effect. To change it for the whole runner, set it in `runner.envs`. A `no_proxy` set there is added to the list above instead of replacing it.
+
+Images are pulled by the Docker daemon, which needs its own proxy setting. In the `dind` images the daemon runs in the same container and reads the variables above. For any other daemon, see [the Docker documentation](https://docs.docker.com/engine/daemon/proxy/). The runner logs a warning at startup if it has a proxy and the daemon does not.
+
+Dockerfile actions are built with these variables as build arguments, so their `RUN` steps can reach the network.
+
+A password in a proxy URL is hidden in job logs. Any step can still read it, because the step is given the proxy URL in its environment.
+
+#### Caching (`actions/cache`)
+
+Each runner starts its own cache server automatically. Cache entries are local to that runner — runners do not share a cache by default.
+
+**Cache service v2**
+
+`actions/cache@v4.2` and later can use the *cache service v2* API. The runner serves it from the same store as v1, on by default, and it works with `external_server`. Turn it off with:
+
+```yaml
+cache:
+  v2: false
+```
+
+Those actions refuse any host they do not take for GitHub. Rather than misreport the server URL, the runner edits that check out of the action's own bundle and keeps the untouched copy beside it; a bundle it does not recognise is left alone and keeps to v1. The same edit lets the stock `actions/upload-artifact` and `actions/download-artifact` work from `v4.4.0` on, without the `gitea-upload-artifact` fork.
+
+**Shared cache across multiple runners**
+
+Run one dedicated `gitea-runner cache-server` that all runners point at.
+
+1. Create a config file for the cache server host:
+
+   ```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
+   ```
+
+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
+   ```
+
+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.
 
 #### Official Docker image
 
@@ -132,11 +294,32 @@ Besides `GITEA_INSTANCE_URL` and `GITEA_RUNNER_REGISTRATION_TOKEN`, the image en
 
 For a fuller container-oriented walkthrough, see [examples/docker](examples/docker/README.md).
 
-When `container.bind_workdir` is enabled, stale task workspace directories can be cleaned while the runner is idle:
+While the runner is idle it cleans up after earlier jobs:
-- directories older than `runner.workdir_cleanup_age` are removed (default: `24h`; set `0` to disable)
+- when `container.bind_workdir` is enabled, stale task workspace directories older than `runner.workdir_cleanup_age` are removed (default: `24h`; set `0` to disable)
-- cleanup runs every `runner.idle_cleanup_interval` (default: `10m`; set `0` to disable)
 - only purely numeric subdirectories under `container.workdir_parent` are treated as task workspaces and may be removed
 - cleanup assumes `container.workdir_parent` is not shared across multiple runners
+- on runners that use docker, per-job networks left behind by jobs the runner did not live to tear down are removed, identified by the `com.gitea.runner.uuid` label carrying this runner's uuid
+- cleanup runs every `runner.idle_cleanup_interval` (default: `10m`; set `0` to disable), and setting either knob to `0` disables all of the above
+
+#### Post-task script (`runner.post_task_script`)
+
+Optional host script that runs **after** each task's built-in cleanup (post-steps, container teardown, bind-workdir removal). Use it for extra machine housekeeping — Docker pruning, disk cleanup, and similar.
+
+**While the script runs, the runner stops task heartbeats and stays offline from Gitea's perspective until the script exits (or hits `runner.post_task_script_timeout`, default `5m`).** A script that blocks without exiting keeps the runner from taking new work for up to that timeout. Script output goes to the runner log, not the job log; a non-zero exit is warned but does not change the job result.
+
+On Windows, use `.exe`, `.bat`, or `.cmd` paths; **PowerShell (`.ps1`) is not supported yet** as the configured path — wrap commands in a `.cmd` file instead.
+
+See **[docs/post-task-script.md](docs/post-task-script.md)** for lifecycle details, environment variables, timeout interaction, and platform notes.
+
+#### Job hooks (`runner.hooks.job_started`, `runner.hooks.job_completed`)
+
+Optional scripts that run **inside the job environment** (the job container, or the host in host mode), before the job's first step and after its last one. They are the equivalent of GitHub's `ACTIONS_RUNNER_HOOK_JOB_STARTED` / `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`, which are read when the settings are unset.
+
+Because they run where the steps run and see the job's environment, they are the place for per-job setup no workflow should have to carry: registry logins, mirror configuration, or masking runner-wide secrets with `::add-mask::`. Their output is part of the job log and is scanned for workflow commands, and they can export to the job through `$GITHUB_ENV` and `$GITHUB_PATH`.
+
+Both hooks are synchronous and block the job while they run. Either one exiting non-zero fails the job, and there is no per-hook timeout.
+
+See **[docs/job-hooks.md](docs/job-hooks.md)** for the execution order, environment, and platform notes.
 
 ### Example Deployments
 

act/artifactcache/handler.go

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

act/artifactcache/handler_test.go

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

act/artifactcache/handler_v2.go

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

act/artifactcache/handler_v2_test.go

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

act/artifactcache/storage.go

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

act/artifacts/server_test.go

@@ -5,24 +5,25 @@
 package artifacts
 
 import (
-	"context"
+	"bytes"
+	"compress/gzip"
 	"encoding/json"
 	"fmt"
+	"io"
+	"maps"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"os"
-	"path"
 	"path/filepath"
 	"strings"
 	"testing"
 	"testing/fstest"
-
+	"time"
-	"gitea.com/gitea/runner/act/model"
-	"gitea.com/gitea/runner/act/runner"
 
 	"github.com/julienschmidt/httprouter"
-	log "github.com/sirupsen/logrus"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 type writableMapFile struct {
@@ -234,89 +235,133 @@ func TestDownloadArtifactFile(t *testing.T) {
 	assert.Equal("content", string(data))
 }
 
-type TestJobFileInfo struct {
+// TestArtifactFlow drives the real Serve() artifact server over a loopback socket, exercising
-	workdir               string
+// the same upload -> finalize -> list -> download protocol the upload-artifact/download-artifact
-	workflowPath          string
+// actions speak. Running it in-process (rather than from a job container) keeps it network-free
-	eventName             string
+// and reachable everywhere, including when the CI job is itself a container.
-	errorMessage          string
-	platforms             map[string]string
-	containerArchitecture string
-}
-
-var (
-	artifactsPath = path.Join(os.TempDir(), "test-artifacts")
-	artifactsAddr = "127.0.0.1"
-	artifactsPort = "12345"
-)
-
 func TestArtifactFlow(t *testing.T) {
-	if testing.Short() {
+	artifactPath := t.TempDir()
-		t.Skip("skipping integration test")
+
+	// Serve the exact routes Serve() wires up, on a real loopback socket via httptest. httptest
+	// picks a free port and Close() tears the server down synchronously — avoiding both the
+	// port-rebind race and Serve()'s detached ListenAndServe goroutine, which logger.Fatal()s
+	// (process exit) on a bind error and can outlive the test's temp-dir cleanup.
+	router := httprouter.New()
+	fsys := readWriteFSImpl{}
+	uploads(router, artifactPath, fsys)
+	downloads(router, artifactPath, fsys)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	baseURL := server.URL
+	client := server.Client()
+	client.Timeout = 5 * time.Second
+
+	// request performs one HTTP call and returns the status and body. The default transport adds
+	// Accept-Encoding: gzip and transparently decompresses, so gzipped downloads come back plain.
+	request := func(t *testing.T, method, rawURL string, body io.Reader, header http.Header) (int, []byte) {
+		t.Helper()
+		req, err := http.NewRequest(method, rawURL, body)
+		require.NoError(t, err)
+		maps.Copy(req.Header, header)
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+		data, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		return resp.StatusCode, data
 	}
 
-	ctx := context.Background()
+	t.Run("upload-and-download", func(t *testing.T) {
+		const runID, item, content = "1", "my-artifact/data.txt", "hello artifact\n"
 
-	cancel := Serve(ctx, artifactsPath, artifactsAddr, artifactsPort)
+		status, data := request(t, http.MethodPost, baseURL+"/_apis/pipelines/workflows/"+runID+"/artifacts", nil, nil)
-	defer cancel()
+		require.Equal(t, http.StatusOK, status, string(data))
+		var prep FileContainerResourceURL
+		require.NoError(t, json.Unmarshal(data, &prep))
+		require.Equal(t, baseURL+"/upload/"+runID, prep.FileContainerResourceURL)
 
-	platforms := map[string]string{
+		status, data = request(t, http.MethodPut, prep.FileContainerResourceURL+"?itemPath="+url.QueryEscape(item), strings.NewReader(content), nil)
-		"ubuntu-latest": "node:24-bookworm", // Don't use node:24-bookworm-slim because it doesn't have curl command, which is used in the tests
+		require.Equal(t, http.StatusOK, status, string(data))
-	}
+		var msg ResponseMessage
+		require.NoError(t, json.Unmarshal(data, &msg))
+		require.Equal(t, "success", msg.Message)
 
-	tables := []TestJobFileInfo{
+		status, data = request(t, http.MethodPatch, baseURL+"/_apis/pipelines/workflows/"+runID+"/artifacts", nil, nil)
-		{"testdata", "upload-and-download", "push", "", platforms, ""},
+		require.Equal(t, http.StatusOK, status, string(data))
-		{"testdata", "GHSL-2023-004", "push", "", platforms, ""},
-	}
-	log.SetLevel(log.DebugLevel)
 
-	for _, table := range tables {
+		status, data = request(t, http.MethodGet, baseURL+"/_apis/pipelines/workflows/"+runID+"/artifacts", nil, nil)
-		runTestJobFile(ctx, t, table)
+		require.Equal(t, http.StatusOK, status, string(data))
-	}
+		var list NamedFileContainerResourceURLResponse
-}
+		require.NoError(t, json.Unmarshal(data, &list))
+		require.Equal(t, 1, list.Count)
+		require.Equal(t, "my-artifact", list.Value[0].Name)
 
-func runTestJobFile(ctx context.Context, t *testing.T, tjfi TestJobFileInfo) {
+		status, data = request(t, http.MethodGet, list.Value[0].FileContainerResourceURL+"?itemPath=my-artifact", nil, nil)
-	t.Run(tjfi.workflowPath, func(t *testing.T) {
+		require.Equal(t, http.StatusOK, status, string(data))
-		fmt.Printf("::group::%s\n", tjfi.workflowPath) //nolint:forbidigo // pre-existing issue from nektos/act
+		var items ContainerItemResponse
+		require.NoError(t, json.Unmarshal(data, &items))
+		require.Len(t, items.Value, 1)
+		require.Equal(t, "file", items.Value[0].ItemType)
+		require.Equal(t, "my-artifact/data.txt", items.Value[0].Path)
 
-		if err := os.RemoveAll(artifactsPath); err != nil {
+		status, data = request(t, http.MethodGet, items.Value[0].ContentLocation, nil, nil)
-			panic(err)
+		require.Equal(t, http.StatusOK, status)
-		}
+		require.Equal(t, content, string(data))
 
-		workdir, err := filepath.Abs(tjfi.workdir)
+		stored, err := os.ReadFile(filepath.Join(artifactPath, runID, "my-artifact", "data.txt"))
-		assert.NoError(t, err, workdir) //nolint:testifylint // pre-existing issue from nektos/act
+		require.NoError(t, err)
-		fullWorkflowPath := filepath.Join(workdir, tjfi.workflowPath)
+		require.Equal(t, content, string(stored))
-		runnerConfig := &runner.Config{
+	})
-			Workdir:               workdir,
-			BindWorkdir:           false,
-			EventName:             tjfi.eventName,
-			Platforms:             tjfi.platforms,
-			ReuseContainers:       false,
-			ContainerArchitecture: tjfi.containerArchitecture,
-			GitHubInstance:        "github.com",
-			ArtifactServerPath:    artifactsPath,
-			ArtifactServerAddr:    artifactsAddr,
-			ArtifactServerPort:    artifactsPort,
-		}
 
-		runner, err := runner.New(runnerConfig)
+	t.Run("gzip-roundtrip", func(t *testing.T) {
-		assert.NoError(t, err, tjfi.workflowPath) //nolint:testifylint // pre-existing issue from nektos/act
+		const runID, item, content = "2", "logs/app.log", "compressed payload\n"
 
-		planner, err := model.NewWorkflowPlanner(fullWorkflowPath, true)
+		var buf bytes.Buffer
-		assert.NoError(t, err, fullWorkflowPath) //nolint:testifylint // pre-existing issue from nektos/act
+		gz := gzip.NewWriter(&buf)
+		_, err := gz.Write([]byte(content))
+		require.NoError(t, err)
+		require.NoError(t, gz.Close())
 
-		plan, err := planner.PlanEvent(tjfi.eventName)
+		status, data := request(t, http.MethodPut, baseURL+"/upload/"+runID+"?itemPath="+url.QueryEscape(item),
-		if err == nil {
+			&buf, http.Header{"Content-Encoding": []string{"gzip"}})
-			err = runner.NewPlanExecutor(plan)(ctx)
+		require.Equal(t, http.StatusOK, status, string(data))
-			if tjfi.errorMessage == "" {
-				assert.NoError(t, err, fullWorkflowPath) //nolint:testifylint // pre-existing issue from nektos/act
-			} else {
-				assert.Error(t, err, tjfi.errorMessage) //nolint:testifylint // pre-existing issue from nektos/act
-			}
-		} else {
-			assert.Nil(t, plan)
-		}
 
-		fmt.Println("::endgroup::") //nolint:forbidigo // pre-existing issue from nektos/act
+		// stored compressed, with the server's gzip marker suffix
+		_, err = os.Stat(filepath.Join(artifactPath, runID, "logs", "app.log.gz__"))
+		require.NoError(t, err)
+
+		status, data = request(t, http.MethodGet, baseURL+"/download/"+runID+"?itemPath=logs", nil, nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+		var items ContainerItemResponse
+		require.NoError(t, json.Unmarshal(data, &items))
+		require.Len(t, items.Value, 1)
+		require.Equal(t, "logs/app.log", items.Value[0].Path)
+
+		status, data = request(t, http.MethodGet, items.Value[0].ContentLocation, nil, nil)
+		require.Equal(t, http.StatusOK, status)
+		require.Equal(t, content, string(data))
+	})
+
+	// GHSL-2023-004: an itemPath that climbs out of the run directory must be neutralised so the
+	// blob cannot be written outside the artifact root.
+	t.Run("GHSL-2023-004", func(t *testing.T) {
+		const runID, content = "3", "contained\n"
+
+		status, data := request(t, http.MethodPut, baseURL+"/upload/"+runID+"?itemPath="+url.QueryEscape("../../escape.txt"),
+			strings.NewReader(content), nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+
+		stored, err := os.ReadFile(filepath.Join(artifactPath, runID, "escape.txt"))
+		require.NoError(t, err)
+		require.Equal(t, content, string(stored))
+
+		_, err = os.Stat(filepath.Join(filepath.Dir(artifactPath), "escape.txt"))
+		require.True(t, os.IsNotExist(err), "upload escaped the artifact root")
+
+		status, data = request(t, http.MethodGet, baseURL+"/artifact/"+runID+"/escape.txt", nil, nil)
+		require.Equal(t, http.StatusOK, status)
+		require.Equal(t, content, string(data))
 	})
 }
 
@@ -345,6 +390,43 @@ func TestMkdirFsImplSafeResolve(t *testing.T) {
 	}
 }
 
+func TestReadWriteFSWritableAndAppendable(t *testing.T) {
+	fsys := readWriteFSImpl{}
+	name := filepath.Join(t.TempDir(), "nested", "artifact.txt")
+
+	w, err := fsys.OpenWritable(name)
+	require.NoError(t, err)
+	_, err = w.Write([]byte("first"))
+	require.NoError(t, err)
+	require.NoError(t, w.Close())
+
+	w, err = fsys.OpenAppendable(name)
+	require.NoError(t, err)
+	_, err = w.Write([]byte("-second"))
+	require.NoError(t, err)
+	require.NoError(t, w.Close())
+
+	got, err := os.ReadFile(name)
+	require.NoError(t, err)
+	require.Equal(t, "first-second", string(got))
+
+	w, err = fsys.OpenWritable(name)
+	require.NoError(t, err)
+	_, err = w.Write([]byte("replaced"))
+	require.NoError(t, err)
+	require.NoError(t, w.Close())
+
+	got, err = os.ReadFile(name)
+	require.NoError(t, err)
+	require.Equal(t, "replaced", string(got))
+}
+
+func TestServeEmptyArtifactPathReturnsCancelableNoop(t *testing.T) {
+	cancel := Serve(t.Context(), "", "127.0.0.1", "0")
+	require.NotNil(t, cancel)
+	cancel()
+}
+
 func TestDownloadArtifactFileUnsafePath(t *testing.T) {
 	assert := assert.New(t)
 

act/artifacts/testdata/GHSL-2023-004/artifacts.yml

@@ -1,39 +0,0 @@
-
-name: "GHSL-2023-0004"
-on: push
-
-jobs:
-  test-artifacts:
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "hello world" > test.txt
-      - name: curl upload
-        run: curl --silent --show-error --fail ${ACTIONS_RUNTIME_URL}upload/1?itemPath=../../my-artifact/secret.txt --upload-file test.txt
-      - uses: actions/download-artifact@v2
-        with:
-          name: my-artifact
-          path: test-artifacts
-      - name: 'Verify Artifact #1'
-        run: |
-          file="test-artifacts/secret.txt"
-          if [ ! -f $file ] ; then
-            echo "Expected file does not exist"
-            exit 1
-          fi
-          if [ "$(cat $file)" != "hello world" ] ; then
-            echo "File contents of downloaded artifact are incorrect"
-            exit 1
-          fi
-      - name: Verify download should work by clean extra dots
-        run: curl --silent --show-error --fail --path-as-is -o out.txt ${ACTIONS_RUNTIME_URL}artifact/1/../../../1/my-artifact/secret.txt
-      - name: 'Verify download content'
-        run: |
-          file="out.txt"
-          if [ ! -f $file ] ; then
-            echo "Expected file does not exist"
-            exit 1
-          fi
-          if [ "$(cat $file)" != "hello world" ] ; then
-            echo "File contents of downloaded artifact are incorrect"
-            exit 1
-          fi

act/artifacts/testdata/upload-and-download/artifacts.yml

@@ -1,230 +0,0 @@
-
-name: "Test that artifact uploads and downloads succeed"
-on: push
-
-jobs:
-  test-artifacts:
-    runs-on: ubuntu-latest
-    steps:
-      - run: mkdir -p path/to/artifact
-      - run: echo hello > path/to/artifact/world.txt
-      - uses: actions/upload-artifact@v2
-        with:
-          name: my-artifact
-          path: path/to/artifact/world.txt
-
-      - run: rm -rf path
-
-      - uses: actions/download-artifact@v2
-        with:
-          name: my-artifact
-      - name: Display structure of downloaded files
-        run: ls -la
-
-      # Test end-to-end by uploading two artifacts and then downloading them
-      - name: Create artifact files
-        run: |
-          mkdir -p path/to/dir-1
-          mkdir -p path/to/dir-2
-          mkdir -p path/to/dir-3
-          mkdir -p path/to/dir-5
-          mkdir -p path/to/dir-6
-          mkdir -p path/to/dir-7
-          echo "Lorem ipsum dolor sit amet" > path/to/dir-1/file1.txt
-          echo "Hello world from file #2" > path/to/dir-2/file2.txt
-          echo "This is a going to be a test for a large enough file that should get compressed with GZip. The @actions/artifact package uses GZip to upload files. This text should have a compression ratio greater than 100% so it should get uploaded using GZip" > path/to/dir-3/gzip.txt
-          dd if=/dev/random of=path/to/dir-5/file5.rnd bs=1024 count=1024
-          dd if=/dev/random of=path/to/dir-6/file6.rnd bs=1024 count=$((10*1024))
-          dd if=/dev/random of=path/to/dir-7/file7.rnd bs=1024 count=$((10*1024))
-
-      # Upload a single file artifact
-      - name: 'Upload artifact #1'
-        uses: actions/upload-artifact@v2
-        with:
-          name: 'Artifact-A'
-          path: path/to/dir-1/file1.txt
-      
-      # Upload using a wildcard pattern, name should default to 'artifact' if not provided
-      - name: 'Upload artifact #2'
-        uses: actions/upload-artifact@v2
-        with:
-          path: path/**/dir*/
-      
-      # Upload a directory that contains a file that will be uploaded with GZip
-      - name: 'Upload artifact #3'
-        uses: actions/upload-artifact@v2
-        with:
-          name: 'GZip-Artifact'
-          path: path/to/dir-3/
-      
-      # Upload a directory that contains a file that will be uploaded with GZip
-      - name: 'Upload artifact #4'
-        uses: actions/upload-artifact@v2
-        with:
-          name: 'Multi-Path-Artifact'
-          path: |
-            path/to/dir-1/*
-            path/to/dir-[23]/*
-            !path/to/dir-3/*.txt
-      
-      # Upload a mid-size file artifact
-      - name: 'Upload artifact #5'
-        uses: actions/upload-artifact@v2
-        with:
-          name: 'Mid-Size-Artifact'
-          path: path/to/dir-5/file5.rnd
-      
-      # Upload a big file artifact
-      - name: 'Upload artifact #6'
-        uses: actions/upload-artifact@v2
-        with:
-          name: 'Big-Artifact'
-          path: path/to/dir-6/file6.rnd
-
-      # Upload a big file artifact twice
-      - name: 'Upload artifact #7 (First)'
-        uses: actions/upload-artifact@v2
-        with:
-          name: 'Big-Uploaded-Twice'
-          path: path/to/dir-7/file7.rnd
-
-      # Upload a big file artifact twice
-      - name: 'Upload artifact #7 (Second)'
-        uses: actions/upload-artifact@v2
-        with:
-          name: 'Big-Uploaded-Twice'
-          path: path/to/dir-7/file7.rnd
-
-      # Verify artifacts. Switch to download-artifact@v2 once it's out of preview
-      
-      # Download Artifact #1 and verify the correctness of the content
-      - name: 'Download artifact #1'
-        uses: actions/download-artifact@v2
-        with:
-          name: 'Artifact-A'
-          path: some/new/path
-      
-      - name: 'Verify Artifact #1'
-        run: |
-          file="some/new/path/file1.txt"
-          if [ ! -f $file ] ; then
-            echo "Expected file does not exist"
-            exit 1
-          fi
-          if [ "$(cat $file)" != "Lorem ipsum dolor sit amet" ] ; then
-            echo "File contents of downloaded artifact are incorrect"
-            exit 1
-          fi
-      
-      # Download Artifact #2 and verify the correctness of the content
-      - name: 'Download artifact #2'
-        uses: actions/download-artifact@v2
-        with:
-          name: 'artifact'
-          path: some/other/path
-      
-      - name: 'Verify Artifact #2'
-        run: |
-          file1="some/other/path/to/dir-1/file1.txt"
-          file2="some/other/path/to/dir-2/file2.txt"
-          if [ ! -f $file1 -o ! -f $file2 ] ; then
-            echo "Expected files do not exist"
-            exit 1
-          fi
-          if [ "$(cat $file1)" != "Lorem ipsum dolor sit amet" -o "$(cat $file2)" != "Hello world from file #2" ] ; then
-            echo "File contents of downloaded artifacts are incorrect"
-            exit 1
-          fi
-      
-      # Download Artifact #3 and verify the correctness of the content
-      - name: 'Download artifact #3'
-        uses: actions/download-artifact@v2
-        with:
-          name: 'GZip-Artifact'
-          path: gzip/artifact/path
-      
-      # Because a directory was used as input during the upload the parent directories, path/to/dir-3/, should not be included in the uploaded artifact
-      - name: 'Verify Artifact #3'
-        run: |
-          gzipFile="gzip/artifact/path/gzip.txt"
-          if [ ! -f $gzipFile ] ; then
-            echo "Expected file do not exist"
-            exit 1
-          fi
-          if [ "$(cat $gzipFile)" != "This is a going to be a test for a large enough file that should get compressed with GZip. The @actions/artifact package uses GZip to upload files. This text should have a compression ratio greater than 100% so it should get uploaded using GZip" ] ; then
-            echo "File contents of downloaded artifact is incorrect"
-            exit 1
-          fi
-      
-      - name: 'Download artifact #4'
-        uses: actions/download-artifact@v2
-        with:
-          name: 'Multi-Path-Artifact'
-          path: multi/artifact
-      
-      - name: 'Verify Artifact #4'
-        run: |
-          file1="multi/artifact/dir-1/file1.txt"
-          file2="multi/artifact/dir-2/file2.txt"
-          if [ ! -f $file1 -o ! -f $file2 ] ; then
-            echo "Expected files do not exist"
-            exit 1
-          fi
-          if [ "$(cat $file1)" != "Lorem ipsum dolor sit amet" -o "$(cat $file2)" != "Hello world from file #2" ] ; then
-            echo "File contents of downloaded artifacts are incorrect"
-            exit 1
-          fi
-      
-      - name: 'Download artifact #5'
-        uses: actions/download-artifact@v2
-        with:
-          name: 'Mid-Size-Artifact'
-          path: mid-size/artifact/path
-      
-      - name: 'Verify Artifact #5'
-        run: |
-          file="mid-size/artifact/path/file5.rnd"
-          if [ ! -f $file ] ; then
-            echo "Expected file does not exist"
-            exit 1
-          fi
-          if ! diff $file path/to/dir-5/file5.rnd ; then
-            echo "File contents of downloaded artifact are incorrect"
-            exit 1
-          fi
-      
-      - name: 'Download artifact #6'
-        uses: actions/download-artifact@v2
-        with:
-          name: 'Big-Artifact'
-          path: big/artifact/path
-      
-      - name: 'Verify Artifact #6'
-        run: |
-          file="big/artifact/path/file6.rnd"
-          if [ ! -f $file ] ; then
-            echo "Expected file does not exist"
-            exit 1
-          fi
-          if ! diff $file path/to/dir-6/file6.rnd ; then
-            echo "File contents of downloaded artifact are incorrect"
-            exit 1
-          fi
-
-      - name: 'Download artifact #7'
-        uses: actions/download-artifact@v2
-        with:
-          name: 'Big-Uploaded-Twice'
-          path: big-uploaded-twice/artifact/path
-
-      - name: 'Verify Artifact #7'
-        run: |
-          file="big-uploaded-twice/artifact/path/file7.rnd"
-          if [ ! -f $file ] ; then
-            echo "Expected file does not exist"
-            exit 1
-          fi
-          if ! diff $file path/to/dir-7/file7.rnd ; then
-            echo "File contents of downloaded artifact are incorrect"
-            exit 1
-          fi

act/common/context_helpers_test.go

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

act/common/executor_max_parallel_test.go

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

act/common/executor_parallel_advanced_test.go

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

act/common/executor_test.go

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

act/common/git/git.go

@@ -16,6 +16,7 @@ import (
 	"sync"
 
 	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/internal/pkg/lock"
 
 	"github.com/go-git/go-git/v5"
 	"github.com/go-git/go-git/v5/config"
@@ -32,7 +33,7 @@ var (
 	githubHTTPRegex     = regexp.MustCompile(`^https?://.*github.com.*/(.+)/(.+?)(?:.git)?$`)
 	githubSSHRegex      = regexp.MustCompile(`github.com[:/](.+)/(.+?)(?:.git)?$`)
 
-	cloneLocks sync.Map // key: clone target directory; value: *sync.Mutex
+	cloneLocks lock.Keyed[string] // key: clone target directory
 
 	ErrShortRef = errors.New("short SHA references are not supported")
 	ErrNoRepo   = errors.New("unable to find git repo")
@@ -43,10 +44,7 @@ var (
 // Callers reading files inside dir (e.g. tarring a checked-out action into a job container) must hold this lock too,
 // otherwise a concurrent NewGitCloneExecutor on the same dir can mutate the worktree mid-read.
 func AcquireCloneLock(dir string) func() {
-	v, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
+	return cloneLocks.Lock(dir)
-	mu := v.(*sync.Mutex)
-	mu.Lock()
-	return mu.Unlock
 }
 
 type Error struct {
@@ -66,8 +64,21 @@ func (e *Error) Commit() string {
 	return e.commit
 }
 
+// goGitMu serializes go-git repository access across the process. go-git is not safe for
+// concurrent use of the same repository (even read access decodes packfiles into shared
+// state), so parallel jobs inspecting the shared workdir repo race without this. The guarded
+// operations are fast local reads; gitea runs one job per process, so the lock is effectively
+// uncontended in production.
+var goGitMu sync.Mutex
+
 // FindGitRevision get the current git revision
 func FindGitRevision(ctx context.Context, file string) (shortSha, sha string, err error) {
+	goGitMu.Lock()
+	defer goGitMu.Unlock()
+	return findGitRevision(ctx, file)
+}
+
+func findGitRevision(ctx context.Context, file string) (shortSha, sha string, err error) {
 	logger := common.Logger(ctx)
 
 	gitDir, err := git.PlainOpenWithOptions(
@@ -99,10 +110,13 @@ func FindGitRevision(ctx context.Context, file string) (shortSha, sha string, er
 
 // FindGitRef get the current git ref
 func FindGitRef(ctx context.Context, file string) (string, error) {
+	goGitMu.Lock()
+	defer goGitMu.Unlock()
+
 	logger := common.Logger(ctx)
 
 	logger.Debugf("Loading revision from git directory")
-	_, ref, err := FindGitRevision(ctx, file)
+	_, ref, err := findGitRevision(ctx, file)
 	if err != nil {
 		return "", err
 	}
@@ -174,6 +188,8 @@ func FindGitRef(ctx context.Context, file string) (string, error) {
 
 // FindGithubRepo get the repo
 func FindGithubRepo(ctx context.Context, file, githubInstance, remoteName string) (string, error) {
+	goGitMu.Lock()
+	defer goGitMu.Unlock()
 	if remoteName == "" {
 		remoteName = "origin"
 	}
@@ -239,6 +255,14 @@ type NewGitCloneExecutorInput struct {
 	Token       string
 	OfflineMode bool
 
+	// Depth limits the clone/fetch to the given number of commits from the tip of the requested ref.
+	// 0 for full clone.
+	Depth int
+
+	// Quiet drops the informational clone line to debug level, for callers that log their own
+	// download summary (the setup section's action report).
+	Quiet bool
+
 	// For Gitea
 	InsecureSkipTLS bool
 }
@@ -247,8 +271,23 @@ type NewGitCloneExecutorInput struct {
 func CloneIfRequired(ctx context.Context, refName plumbing.ReferenceName, input NewGitCloneExecutorInput, logger log.FieldLogger) (*git.Repository, bool, error) {
 	r, err := git.PlainOpen(input.Dir)
 	if err == nil {
-		// Reuse existing clone
+		// Verify the cached clone still points to the resolved URL before reusing it.
-		return r, true, nil
+		remote, err := r.Remote("origin")
+		if err == nil && len(remote.Config().URLs) > 0 && remote.Config().URLs[0] == input.URL {
+			// Reuse existing clone
+			return r, true, nil
+		}
+
+		if err != nil {
+			logger.Debugf("Removing cached clone at %s because origin cannot be read: %v", input.Dir, err)
+		} else if len(remote.Config().URLs) == 0 {
+			logger.Debugf("Removing cached clone at %s because origin has no URL", input.Dir)
+		} else {
+			logger.Debugf("Removing cached clone at %s because origin URL changed from %s to %s", input.Dir, remote.Config().URLs[0], input.URL)
+		}
+		if err := os.RemoveAll(input.Dir); err != nil {
+			return nil, false, fmt.Errorf("remove cached clone %s: %w", input.Dir, err)
+		}
 	}
 
 	var progressWriter io.Writer
@@ -276,7 +315,7 @@ func CloneIfRequired(ctx context.Context, refName plumbing.ReferenceName, input
 		}
 	}
 
-	r, err = git.PlainCloneContext(ctx, input.Dir, false, &cloneOptions)
+	r, err = cloneAtDepth(ctx, input, cloneOptions, logger)
 	if err != nil {
 		logger.Errorf("Unable to clone %v %s: %v", input.URL, refName, err)
 		return nil, false, err
@@ -310,7 +349,11 @@ func gitOptions(token string) (fetchOptions git.FetchOptions, pullOptions git.Pu
 func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
 		logger := common.Logger(ctx)
-		logger.Infof("git clone '%s' # ref=%s", input.URL, input.Ref)
+		if input.Quiet {
+			logger.Debugf("git clone '%s' # ref=%s", input.URL, input.Ref)
+		} else {
+			logger.Infof("git clone '%s' # ref=%s", input.URL, input.Ref)
+		}
 		logger.Debugf("  cloning %s to %s", input.URL, input.Dir)
 
 		defer AcquireCloneLock(input.Dir)()
@@ -331,6 +374,16 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 			pullOptions.InsecureSkipTLS = true
 		}
 
+		// Action clones only ever need the tip commit, so keep a shallow cache cheap on update at depth 1 regardless of its original depth
+		// Turning action_shallow_clone off does not convert an existing shallow cache; evict it for a full clone.
+		shallow := isShallow(r)
+		if shallow {
+			fetchOptions.Depth = 1
+			if spec, ok := shallowFetchRefSpec(r, input.Ref); ok {
+				fetchOptions.RefSpecs = []config.RefSpec{spec}
+			}
+		}
+
 		if !isOfflineMode {
 			err = r.Fetch(&fetchOptions)
 			if err != nil && !errors.Is(err, git.NoErrAlreadyUpToDate) {
@@ -398,11 +451,13 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 
 		reusedMsg := ""
 
-		if !isOfflineMode {
+		switch {
+		case !isOfflineMode && !shallow:
+			// In shallow mode the depth-limited fetch above already advanced the ref.
 			if err = w.Pull(&pullOptions); err != nil && err != git.NoErrAlreadyUpToDate {
 				logger.Debugf("Unable to pull %s: %v", refName, err)
 			}
-		} else if reused {
+		case isOfflineMode && reused:
 			reusedMsg = " (reused in offline mode)"
 		}
 
@@ -435,3 +490,53 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 		return nil
 	}
 }
+
+// cloneAtDepth clones input.URL into input.Dir using opts.
+// With input.Depth > 0 it first tries a shallow, single-branch clone of input.Ref, falling back when error.
+func cloneAtDepth(ctx context.Context, input NewGitCloneExecutorInput, opts git.CloneOptions, logger log.FieldLogger) (*git.Repository, error) {
+	if input.Depth > 0 {
+		for _, refName := range []plumbing.ReferenceName{
+			plumbing.NewBranchReferenceName(input.Ref),
+			plumbing.NewTagReferenceName(input.Ref),
+		} {
+			shallowOpts := opts
+			shallowOpts.Depth = input.Depth
+			shallowOpts.SingleBranch = true
+			shallowOpts.ReferenceName = refName
+			shallowOpts.Tags = git.NoTags
+
+			r, err := git.PlainCloneContext(ctx, input.Dir, false, &shallowOpts)
+			if err == nil {
+				return r, nil
+			}
+			logger.Debugf("Shallow clone of %s as %s failed: %v", input.URL, refName, err)
+			if rmErr := os.RemoveAll(input.Dir); rmErr != nil {
+				return nil, fmt.Errorf("remove partial clone %s: %w", input.Dir, rmErr)
+			}
+		}
+		logger.Debugf("Falling back to a full clone of %s for ref %q", input.URL, input.Ref)
+	}
+
+	return git.PlainCloneContext(ctx, input.Dir, false, &opts)
+}
+
+// isShallow reports whether the local repository was cloned with a limited depth.
+func isShallow(r *git.Repository) bool {
+	shallows, err := r.Storer.Shallow()
+	return err == nil && len(shallows) > 0
+}
+
+// shallowFetchRefSpec returns the single refspec that updates only input.Ref, keeping a shallow clone from re-downloading every branch's history.
+// ok is false when the ref is not present locally as a tag or remote-tracking branch, in which case the broad default refspec is used.
+func shallowFetchRefSpec(r *git.Repository, ref string) (config.RefSpec, bool) {
+	tagRef := plumbing.NewTagReferenceName(ref)
+	if _, err := r.Reference(tagRef, false); err == nil {
+		return config.RefSpec(fmt.Sprintf("+%s:%s", tagRef, tagRef)), true
+	}
+	remoteRef := plumbing.NewRemoteReferenceName("origin", ref)
+	if _, err := r.Reference(remoteRef, false); err == nil {
+		branchRef := plumbing.NewBranchReferenceName(ref)
+		return config.RefSpec(fmt.Sprintf("+%s:%s", branchRef, remoteRef)), true
+	}
+	return "", false
+}

act/common/git/git_test.go

@@ -10,13 +10,16 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
-	"sync"
 	"syscall"
 	"testing"
 	"time"
 
+	"gitea.com/gitea/runner/act/common"
+
 	log "github.com/sirupsen/logrus"
+	logrustest "github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -50,8 +53,11 @@ func TestFindGitSlug(t *testing.T) {
 	}
 }
 
-func testDir(t *testing.T) string {
+func TestErrorWrapsCommitAndCause(t *testing.T) {
-	return t.TempDir()
+	err := &Error{err: ErrShortRef, commit: "abc123"}
+	require.Equal(t, ErrShortRef.Error(), err.Error())
+	require.ErrorIs(t, err, ErrShortRef)
+	require.Equal(t, "abc123", err.Commit())
 }
 
 func cleanGitHooks(dir string) error {
@@ -78,8 +84,7 @@ func cleanGitHooks(dir string) error {
 func TestFindGitRemoteURL(t *testing.T) {
 	assert := assert.New(t)
 
-	basedir := testDir(t)
+	basedir := t.TempDir()
-	gitConfig()
 	err := gitCmd("init", basedir)
 	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
 	err = cleanGitHooks(basedir)
@@ -101,9 +106,24 @@ func TestFindGitRemoteURL(t *testing.T) {
 	assert.Equal(remoteURL, u)
 }
 
+func TestFindGithubRepoUsesOriginAndCustomRemote(t *testing.T) {
+	basedir := t.TempDir()
+	require.NoError(t, gitCmd("init", basedir))
+	require.NoError(t, cleanGitHooks(basedir))
+	require.NoError(t, gitCmd("-C", basedir, "remote", "add", "origin", "https://github.com/owner/repo.git"))
+	require.NoError(t, gitCmd("-C", basedir, "remote", "add", "ghe", "[email protected]:team/project.git"))
+
+	slug, err := FindGithubRepo(context.Background(), basedir, "github.com", "")
+	require.NoError(t, err)
+	require.Equal(t, "owner/repo", slug)
+
+	slug, err = FindGithubRepo(context.Background(), basedir, "git.example.com", "ghe")
+	require.NoError(t, err)
+	require.Equal(t, "team/project", slug)
+}
+
 func TestGitFindRef(t *testing.T) {
-	basedir := testDir(t)
+	basedir := t.TempDir()
-	gitConfig()
 
 	for name, tt := range map[string]struct {
 		Prepare func(t *testing.T, dir string)
@@ -180,36 +200,55 @@ func TestGitFindRef(t *testing.T) {
 }
 
 func TestGitCloneExecutor(t *testing.T) {
+	// Build a local bare "remote" so this runs offline and fast. The cases below mirror
+	// the tag/branch/sha/short-sha ref paths the executor handles, formerly exercised by
+	// cloning actions/checkout and anchore/scan-action over the network.
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "initial"))
+	require.NoError(t, gitCmd("-C", workDir, "tag", "v2"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "v2"))
+
+	// A branch with a dash in the name (mirrors the historical scan-action@act-fails case).
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "act-fails"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "branch-commit"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "act-fails"))
+
+	out, err := exec.Command("git", "-C", workDir, "rev-parse", "main").Output()
+	require.NoError(t, err)
+	fullSha := strings.TrimSpace(string(out))
+
 	for name, tt := range map[string]struct {
-		Err      error
+		Err error
-		URL, Ref string
+		Ref string
 	}{
 		"tag": {
 			Err: nil,
-			URL: "https://github.com/actions/checkout",
 			Ref: "v2",
 		},
 		"branch": {
 			Err: nil,
-			URL: "https://github.com/anchore/scan-action",
 			Ref: "act-fails",
 		},
 		"sha": {
 			Err: nil,
-			URL: "https://github.com/actions/checkout",
+			Ref: fullSha,
-			Ref: "5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f", // v2
 		},
 		"short-sha": {
-			Err: &Error{ErrShortRef, "5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f"},
+			Err: &Error{ErrShortRef, fullSha},
-			URL: "https://github.com/actions/checkout",
+			Ref: fullSha[:7],
-			Ref: "5a4ac90", // v2
 		},
 	} {
 		t.Run(name, func(t *testing.T) {
 			clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
-				URL: tt.URL,
+				URL: remoteDir,
 				Ref: tt.Ref,
-				Dir: testDir(t),
+				Dir: t.TempDir(),
 			})
 
 			err := clone(context.Background())
@@ -223,13 +262,56 @@ func TestGitCloneExecutor(t *testing.T) {
 	}
 }
 
+func TestGitCloneExecutorReclonesWhenOriginURLChanges(t *testing.T) {
+	createRemote := func(message string) string {
+		remoteDir := t.TempDir()
+		require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+
+		workDir := t.TempDir()
+		require.NoError(t, gitCmd("clone", remoteDir, workDir))
+		require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", message))
+		require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+
+		return remoteDir
+	}
+
+	oldRemoteDir := createRemote("old-action")
+	newRemoteDir := createRemote("new-action")
+	cacheDir := t.TempDir()
+
+	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+		URL: oldRemoteDir,
+		Ref: "main",
+		Dir: cacheDir,
+	})(t.Context()))
+
+	markerPath := filepath.Join(cacheDir, "stale-marker")
+	require.NoError(t, os.WriteFile(markerPath, []byte("stale"), 0o644))
+
+	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+		URL: newRemoteDir,
+		Ref: "main",
+		Dir: cacheDir,
+	})(t.Context()))
+
+	originURL, err := findGitRemoteURL(t.Context(), cacheDir, "origin")
+	require.NoError(t, err)
+	assert.Equal(t, newRemoteDir, originURL)
+
+	out, err := exec.Command("git", "-C", cacheDir, "log", "--oneline", "-1", "--format=%s").Output()
+	require.NoError(t, err)
+	assert.Equal(t, "new-action", strings.TrimSpace(string(out)))
+
+	_, err = os.Stat(markerPath)
+	require.True(t, os.IsNotExist(err), "stale cached directory should be removed before recloning")
+}
+
 func TestGitCloneExecutorNonFastForwardRef(t *testing.T) {
 	// Simulate the scenario where a remote ref (e.g. a GitHub PR head ref) changes
 	// non-fast-forward between two fetches. Before the fix, the fetch used Force=false,
 	// causing go-git to return ErrForceNeeded and short-circuit the checkout.
 
-	gitConfig()
-
 	// Create a bare "remote" repo with an initial commit on main and a feature branch.
 	remoteDir := t.TempDir()
 	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
@@ -280,8 +362,6 @@ func TestGitCloneExecutorNonFastForwardRef(t *testing.T) {
 }
 
 func TestGitCloneExecutorOfflineMode(t *testing.T) {
-	gitConfig()
-
 	// Build a local "remote" with a single commit on main.
 	remoteDir := t.TempDir()
 	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
@@ -327,22 +407,149 @@ func TestGitCloneExecutorOfflineMode(t *testing.T) {
 	})
 }
 
-func gitConfig() {
+func TestGitCloneExecutorQuietDemotesCloneLine(t *testing.T) {
-	if os.Getenv("GITHUB_ACTIONS") == "true" {
+	remoteDir := t.TempDir()
-		var err error
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
-		if err = gitCmd("config", "--global", "user.email", "[email protected]"); err != nil {
+	workDir := t.TempDir()
-			log.Error(err)
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
-		}
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
-		if err = gitCmd("config", "--global", "user.name", "Unit Test"); err != nil {
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "initial"))
-			log.Error(err)
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
-		}
+
+	// Quiet callers report the download themselves, so the clone line must not reach the job log.
+	for name, quiet := range map[string]bool{"quiet": true, "not quiet": false} {
+		t.Run(name, func(t *testing.T) {
+			logger, hook := logrustest.NewNullLogger()
+			logger.SetLevel(log.InfoLevel)
+			ctx := common.WithLogger(context.Background(), logger.WithField("job", "j1"))
+
+			require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL:   remoteDir,
+				Ref:   "main",
+				Dir:   t.TempDir(),
+				Quiet: quiet,
+			})(ctx))
+
+			var cloneLines int
+			for _, entry := range hook.AllEntries() {
+				if strings.HasPrefix(entry.Message, "git clone ") {
+					cloneLines++
+				}
+			}
+			if quiet {
+				assert.Zero(t, cloneLines)
+			} else {
+				assert.Equal(t, 1, cloneLines)
+			}
+		})
 	}
 }
 
+func TestGitCloneExecutorShallow(t *testing.T) {
+	// Build a local "remote" with several commits on main plus a tag, so a full clone would pull noticeably more history than a shallow one.
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	for _, m := range []string{"c1", "c2", "c3"} {
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", m))
+	}
+	require.NoError(t, gitCmd("-C", workDir, "tag", "v1"))
+	sha := gitRevParse(t, workDir, "HEAD~1") // c2, a SHA that go-git cannot shallow-clone
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "v1"))
+
+	shallowMarker := func(dir string) string { return filepath.Join(dir, ".git", "shallow") }
+
+	t.Run("branch is cloned shallowly", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.FileExists(t, shallowMarker(dir), "clone should be shallow")
+		assert.Equal(t, 1, gitRevCount(t, dir), "only the tip commit should be present")
+		assert.Equal(t, "c3", gitHeadSubject(t, dir))
+	})
+
+	t.Run("tag is cloned shallowly", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "v1", Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.FileExists(t, shallowMarker(dir), "clone should be shallow")
+		assert.Equal(t, 1, gitRevCount(t, dir))
+		assert.Equal(t, "c3", gitHeadSubject(t, dir))
+	})
+
+	t.Run("SHA falls back to a full clone", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: sha, Dir: dir, Depth: 1,
+		})(t.Context()))
+		// go-git cannot shallow-clone a raw SHA, so it falls back to a full clone; the absence of a shallow marker proves the fallback happened.
+		assert.NoFileExists(t, shallowMarker(dir), "a SHA ref must not produce a shallow clone")
+		assert.Equal(t, sha, gitRevParse(t, dir, "HEAD"))
+	})
+
+	t.Run("moving branch updates while staying shallow", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
+		})(t.Context()))
+		require.Equal(t, "c3", gitHeadSubject(t, dir))
+
+		// Advance main on the remote, then reuse the existing shallow clone.
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "c4"))
+		require.NoError(t, gitCmd("-C", workDir, "push", "origin", "main"))
+
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.Equal(t, "c4", gitHeadSubject(t, dir), "reused shallow clone should update to the new tip")
+		assert.FileExists(t, shallowMarker(dir), "repo should remain shallow after update")
+		assert.Equal(t, 1, gitRevCount(t, dir))
+	})
+}
+
+func gitRevParse(t *testing.T, dir, rev string) string {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "rev-parse", rev).Output()
+	require.NoError(t, err)
+	return strings.TrimSpace(string(out))
+}
+
+func gitRevCount(t *testing.T, dir string) int {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "rev-list", "--count", "HEAD").Output()
+	require.NoError(t, err)
+	n, err := strconv.Atoi(strings.TrimSpace(string(out)))
+	require.NoError(t, err)
+	return n
+}
+
+func gitHeadSubject(t *testing.T, dir string) string {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "log", "-1", "--format=%s").Output()
+	require.NoError(t, err)
+	return strings.TrimSpace(string(out))
+}
+
 func gitCmd(args ...string) error {
 	cmd := exec.Command("git", args...)
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr
+	// Inject a deterministic identity and ignore the host's global/system config so commits
+	// succeed regardless of the host having no user.name/user.email (e.g. CI, GITHUB_ACTIONS
+	// unset) or a global commit.gpgsign, and without mutating the developer's ~/.gitconfig.
+	cmd.Env = append(os.Environ(),
+		"GIT_AUTHOR_NAME=Unit Test",
+		"[email protected]",
+		"GIT_COMMITTER_NAME=Unit Test",
+		"[email protected]",
+		"GIT_CONFIG_GLOBAL=/dev/null",
+		"GIT_CONFIG_SYSTEM=/dev/null",
+	)
 
 	err := cmd.Run()
 	if exitError, ok := err.(*exec.ExitError); ok {
@@ -402,12 +609,4 @@ func TestAcquireCloneLock(t *testing.T) {
 			t.Fatal("acquire on a different directory must not block")
 		}
 	})
-
-	t.Run("same directory reuses the same mutex", func(t *testing.T) {
-		dir := t.TempDir()
-
-		v1, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
-		v2, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
-		require.Same(t, v1, v2)
-	})
 }

act/common/job_error.go

@@ -24,7 +24,9 @@ func JobError(ctx context.Context) error {
 }
 
 func SetJobError(ctx context.Context, err error) {
-	ctx.Value(jobErrorContextKeyVal).(map[string]error)["error"] = err
+	if container, ok := ctx.Value(jobErrorContextKeyVal).(map[string]error); ok {
+		container["error"] = err
+	}
 }
 
 // WithJobErrorContainer adds a value to the context as a container for an error

act/common/line_writer.go

@@ -12,6 +12,13 @@ import (
 // LineHandler is a callback function for handling a line
 type LineHandler func(line string) bool
 
+// Flusher is implemented by writers that buffer a trailing, not-yet-terminated
+// line. Callers should flush once the underlying stream has reached EOF so the
+// final line (when it is not newline-terminated) is not lost.
+type Flusher interface {
+	Flush()
+}
+
 type lineWriter struct {
 	buffer   bytes.Buffer
 	handlers []LineHandler
@@ -24,6 +31,14 @@ func NewLineWriter(handlers ...LineHandler) io.Writer {
 	return w
 }
 
+// FlushWriter flushes w if it implements Flusher. It is a no-op otherwise, so
+// callers can flush an io.Writer without knowing its concrete type.
+func FlushWriter(w io.Writer) {
+	if f, ok := w.(Flusher); ok {
+		f.Flush()
+	}
+}
+
 func (lw *lineWriter) Write(p []byte) (n int, err error) {
 	pBuf := bytes.NewBuffer(p)
 	written := 0
@@ -44,6 +59,17 @@ func (lw *lineWriter) Write(p []byte) (n int, err error) {
 	return written, nil
 }
 
+// Flush emits any buffered, not-yet-newline-terminated content as a final line.
+// It is safe to call multiple times; subsequent calls with an empty buffer are
+// no-ops.
+func (lw *lineWriter) Flush() {
+	if lw.buffer.Len() == 0 {
+		return
+	}
+	lw.handleLine(lw.buffer.String())
+	lw.buffer.Reset()
+}
+
 func (lw *lineWriter) handleLine(line string) {
 	for _, h := range lw.handlers {
 		ok := h(line)

act/common/line_writer_test.go

@@ -5,6 +5,7 @@
 package common
 
 import (
+	"io"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -39,3 +40,33 @@ func TestLineWriter(t *testing.T) {
 	assert.Equal(" and another\n", lines[2])
 	assert.Equal("last line\n", lines[3])
 }
+
+func TestLineWriterFlush(t *testing.T) {
+	lines := make([]string, 0)
+	lineHandler := func(s string) bool {
+		lines = append(lines, s)
+		return true
+	}
+
+	lineWriter := NewLineWriter(lineHandler)
+
+	assert := assert.New(t)
+	_, err := lineWriter.Write([]byte("complete line\npartial line without newline"))
+	assert.NoError(err) //nolint:testifylint // pre-existing pattern from nektos/act
+
+	// Only the newline-terminated line is emitted before flushing.
+	assert.Equal([]string{"complete line\n"}, lines)
+
+	// Flushing emits the buffered, not-yet-terminated trailing line.
+	FlushWriter(lineWriter)
+	assert.Equal([]string{"complete line\n", "partial line without newline"}, lines)
+
+	// Flushing again is a no-op: nothing is buffered.
+	FlushWriter(lineWriter)
+	assert.Len(lines, 2)
+}
+
+func TestFlushWriterIgnoresNonFlusher(t *testing.T) {
+	// FlushWriter must be a safe no-op for writers that do not buffer lines.
+	assert.NotPanics(t, func() { FlushWriter(io.Discard) })
+}

act/common/outbound_ip.go

@@ -19,7 +19,9 @@ func GetOutboundIP() net.IP {
 	conn, err := net.Dial("udp", "8.8.8.8:80")
 	if err == nil {
 		defer conn.Close()
-		return conn.LocalAddr().(*net.UDPAddr).IP
+		if addr, ok := conn.LocalAddr().(*net.UDPAddr); ok {
+			return addr.IP
+		}
 	}
 
 	// So the machine cannot access the internet. Pick an IP address from network interfaces.

act/container/container_types.go

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

act/container/docker_auth.go

@@ -13,7 +13,6 @@ import (
 
 	"github.com/distribution/reference"
 	"github.com/docker/cli/cli/config"
-	"github.com/docker/cli/cli/config/credentials"
 	"github.com/moby/moby/api/types/registry"
 )
 
@@ -26,10 +25,6 @@ func LoadDockerAuthConfig(ctx context.Context, image string) (registry.AuthConfi
 		logger.Warnf("Could not load docker config: %v", err)
 		return registry.AuthConfig{}, err
 	}
-	if !cfg.ContainsAuth() {
-		cfg.CredentialsStore = credentials.DetectDefaultStore(cfg.CredentialsStore)
-	}
-
 	registryKey := registryAuthConfigKey("docker.io")
 	if image != "" {
 		if registryRef, refErr := reference.ParseNormalizedNamed(image); refErr != nil {
@@ -55,10 +50,6 @@ func LoadDockerAuthConfigs(ctx context.Context) map[string]registry.AuthConfig {
 		logger.Warnf("Could not load docker config: %v", err)
 		return nil
 	}
-	if !cfg.ContainsAuth() {
-		cfg.CredentialsStore = credentials.DetectDefaultStore(cfg.CredentialsStore)
-	}
-
 	creds, err := cfg.GetAllCredentials()
 	if err != nil {
 		logger.Warnf("Could not get docker auth configs: %v", err)

act/container/docker_build.go

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

act/container/docker_cli.go

@@ -4,8 +4,10 @@
 
 //go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
 
-// This file is exact copy of https://github.com/docker/cli/blob/9a471180cb7d39c236d090399a9d362c3f5a8ebd/cli/command/container/opts.go
+// This file is exact copy of https://github.com/docker/cli/blob/dfc4efb1e2ab8c06d70d2a1366ad448d2f917e90/cli/command/container/opts.go with:
-// appended with license information.
+// * appended with license information
+// * regexp and loader.ParseVolume in place of the import-restricted internal/lazyregexp and internal/volumespec
+// * 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.
 // See DOCKER_LICENSE for the full license text.
@@ -30,6 +32,7 @@ import (
 	"strings"
 	"time"
 
+	cerrdefs "github.com/containerd/errdefs"
 	"github.com/docker/cli/cli/compose/loader"
 	"github.com/docker/cli/opts"
 	"github.com/docker/go-connections/nat"
@@ -380,7 +383,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 	var binds []string
 	volumes := copts.volumes.GetMap()
 	// add any bind targets to the list of container volumes
-	for bind := range copts.volumes.GetMap() {
+	for bind := range volumes {
 		parsed, err := loader.ParseVolume(bind)
 		if err != nil {
 			return nil, err
@@ -515,13 +518,13 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 	// collect all the environment variables for the container
 	envVariables, err := opts.ReadKVEnvStrings(copts.envFile.GetSlice(), copts.env.GetSlice())
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("--env-file: %w", err)
 	}
 
 	// collect all the labels for the container
 	labels, err := opts.ReadKVStrings(copts.labelsFile.GetSlice(), copts.labels.GetSlice())
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("--label-file: %w", err)
 	}
 
 	pidMode := container.PidMode(copts.pidMode)
@@ -1164,16 +1167,17 @@ func toNetipAddrSlice(ips []string) []netip.Addr {
 }
 
 // invalidParameter wraps an error to indicate it was caused by invalid input.
-// This is a local replacement for docker/docker/errdefs.InvalidParameter.
+// This is a copy of docker/cli's cli/command/container/errors.go, which is not importable.
-type invalidParameterError struct{ error }
+type invalidParameterErr struct{ error }
 
-func (e invalidParameterError) InvalidParameter() {}
+func (invalidParameterErr) InvalidParameter() {}
+func (e invalidParameterErr) Unwrap() error   { return e.error }
 
 func invalidParameter(err error) error {
-	if err == nil {
+	if err == nil || cerrdefs.IsInvalidArgument(err) {
-		return nil
+		return err
 	}
-	return invalidParameterError{err}
+	return invalidParameterErr{err}
 }
 
 func convertPortSet(ports nat.PortSet) (network.PortSet, error) {

act/container/docker_create_flags.go

@@ -0,0 +1,86 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+
+package container
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"slices"
+
+	"github.com/kballard/go-shellquote"
+	"github.com/spf13/pflag"
+)
+
+const (
+	pullPolicyAlways  = "always"
+	pullPolicyMissing = "missing"
+	pullPolicyNever   = "never"
+)
+
+var pullPolicies = []string{pullPolicyAlways, pullPolicyMissing, pullPolicyNever}
+
+// createFlags are the flags docker/cli registers on the `create` and `run` commands
+// instead of in addFlags, so they are not part of containerOptions.
+type createFlags struct {
+	platform     string
+	pull         string
+	name         string
+	useAPISocket bool
+}
+
+func registerCreateFlags(flags *pflag.FlagSet) *createFlags {
+	cf := new(createFlags)
+	flags.StringVar(&cf.platform, "platform", "", "Set platform if server is multi-platform capable")
+	flags.StringVar(&cf.pull, "pull", pullPolicyMissing, `Pull image before creating ("always", "missing", "never")`)
+	flags.StringVar(&cf.name, "name", "", "Assign a name to the container")
+	flags.BoolVar(&cf.useAPISocket, "use-api-socket", false, "Bind mount Docker API socket and required auth")
+	// Accepted without effect: pull progress is only logged at debug level, and docker
+	// no longer implements content trust.
+	flags.BoolP("quiet", "q", false, "Suppress the pull output")
+	flags.Bool("disable-content-trust", true, "Skip image verification (deprecated)")
+	return cf
+}
+
+// parseContainerOptions parses a container options string. The flags are returned even
+// on error, holding whatever was read before the failure.
+func parseContainerOptions(options string) (*pflag.FlagSet, *containerOptions, *createFlags, error) {
+	flags := pflag.NewFlagSet("container_flags", pflag.ContinueOnError)
+	flags.SetOutput(io.Discard)
+	copts := addFlags(flags)
+	cf := registerCreateFlags(flags)
+
+	args, err := shellquote.Split(options)
+	if err != nil {
+		return flags, copts, cf, fmt.Errorf("Cannot split container options: '%s': '%w'", options, err)
+	}
+
+	if err := flags.Parse(args); err != nil {
+		return flags, copts, cf, fmt.Errorf("Cannot parse container options: '%s': '%w'", options, err)
+	}
+
+	return flags, copts, cf, nil
+}
+
+// createFlagsFromOptions reads the create-level flags that have to be known before the
+// container is created. Malformed options keep the defaults here and are reported by
+// mergeContainerConfigs at create time.
+func createFlagsFromOptions(options string) *createFlags {
+	_, _, cf, _ := parseContainerOptions(options)
+	return cf
+}
+
+func (cf *createFlags) validate() error {
+	if !slices.Contains(pullPolicies, cf.pull) {
+		return fmt.Errorf("invalid --pull option %q: must be one of %q", cf.pull, pullPolicies)
+	}
+
+	if cf.useAPISocket {
+		return errors.New("--use-api-socket is not supported, use the runner's container.docker_host setting to expose a docker socket")
+	}
+
+	return nil
+}

act/container/docker_create_flags_test.go

@@ -0,0 +1,62 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package container
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCreateFlagsFromOptions(t *testing.T) {
+	for _, tc := range []struct {
+		options  string
+		platform string
+		pull     string
+	}{
+		{"", "", pullPolicyMissing},
+		{"-v /a:/b --platform=linux/arm64 --pull always", "linux/arm64", pullPolicyAlways},
+		{"--platform linux/arm/v7 --pull never", "linux/arm/v7", pullPolicyNever},
+		{`--platform "linux/amd64`, "", pullPolicyMissing}, // malformed, defaults kept
+	} {
+		t.Run(tc.options, func(t *testing.T) {
+			cf := createFlagsFromOptions(tc.options)
+			assert.Equal(t, tc.platform, cf.platform)
+			assert.Equal(t, tc.pull, cf.pull)
+		})
+	}
+}
+
+func TestCreateFlagsValidate(t *testing.T) {
+	for _, tc := range []struct {
+		options string
+		wantErr string
+	}{
+		{"--quiet --disable-content-trust --name mine", ""},
+		{"--pull sometimes", `invalid --pull option "sometimes"`},
+		{"--use-api-socket", "--use-api-socket is not supported"},
+	} {
+		t.Run(tc.options, func(t *testing.T) {
+			err := createFlagsFromOptions(tc.options).validate()
+			if tc.wantErr == "" {
+				require.NoError(t, err)
+				return
+			}
+			require.ErrorContains(t, err, tc.wantErr)
+		})
+	}
+}
+
+func TestNewContainerAppliesCreateFlags(t *testing.T) {
+	input := &NewContainerInput{Platform: "linux/amd64", Options: "--platform linux/arm64 --pull never"}
+	cr, ok := NewContainer(input).(*containerReference)
+	require.True(t, ok)
+	assert.Equal(t, "linux/arm64", input.Platform)
+	assert.Equal(t, pullPolicyNever, cr.pullPolicy)
+
+	kept := &NewContainerInput{Platform: "linux/amd64", Options: "--privileged"}
+	NewContainer(kept)
+	assert.Equal(t, "linux/amd64", kept.Platform)
+}

act/container/docker_images_test.go

@@ -6,66 +6,64 @@ package container
 
 import (
 	"context"
-	"io"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
 	"testing"
 
-	"github.com/moby/moby/client"
-	specs "github.com/opencontainers/image-spec/specs-go/v1"
 	log "github.com/sirupsen/logrus"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func init() {
 	log.SetLevel(log.DebugLevel)
 }
 
+// buildScratchImage builds a tiny empty image for the given platform locally (FROM scratch, no
+// network or emulation since there is nothing to run) and returns its tag, removing it after
+// the test.
+func buildScratchImage(t *testing.T, platform string) string {
+	t.Helper()
+	tag := fmt.Sprintf("act-test-exists-%s:latest", strings.TrimPrefix(platform, "linux/"))
+	cmd := exec.Command("docker", "build", "--platform", platform, "-t", tag, "-")
+	cmd.Stdin = strings.NewReader("FROM scratch\nLABEL act-test=1\n")
+	// Force BuildKit: it records the requested architecture in the image config for a
+	// FROM-scratch build, whereas the classic builder ignores --platform and tags it with the
+	// host arch, which would break the per-platform existence assertions below.
+	cmd.Env = append(os.Environ(), "DOCKER_BUILDKIT=1")
+	out, err := cmd.CombinedOutput()
+	require.NoError(t, err, string(out))
+	t.Cleanup(func() { _ = exec.Command("docker", "rmi", "-f", tag).Run() })
+	return tag
+}
+
 func TestImageExistsLocally(t *testing.T) {
-	if testing.Short() {
+	requireDocker(t)
-		t.Skip("skipping integration test")
-	}
 	ctx := context.Background()
-	// to help make this test reliable and not flaky, we need to have
-	// an image that will exist, and onew that won't exist
-
-	// Test if image exists with specific tag
-	invalidImageTag, err := ImageExistsLocally(ctx, "library/alpine:this-random-tag-will-never-exist", "linux/amd64")
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.False(t, invalidImageTag)
-
-	// Test if image exists with specific architecture (image platform)
-	invalidImagePlatform, err := ImageExistsLocally(ctx, "alpine:latest", "windows/amd64")
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.False(t, invalidImagePlatform)
 
-	// pull an image
+	// a non-existent image is reported absent
-	cli, err := client.New(client.FromEnv)
+	missing, err := ImageExistsLocally(ctx, "library/alpine:this-random-tag-will-never-exist", "linux/amd64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	defer cli.Close()
+	assert.False(t, missing)
 
-	// Chose alpine latest because it's so small
+	// Build tiny images for two architectures locally so per-platform existence can be checked
-	// maybe we should build an image instead so that tests aren't reliable on dockerhub
+	// offline (formerly pulled node:24-bookworm-slim for amd64 and arm64 over the network).
-	readerDefault, err := cli.ImagePull(ctx, "node:24-bookworm-slim", client.ImagePullOptions{
+	amd64Ref := buildScratchImage(t, "linux/amd64")
-		Platforms: []specs.Platform{{OS: "linux", Architecture: "amd64"}},
+	arm64Ref := buildScratchImage(t, "linux/arm64")
-	})
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	defer readerDefault.Close()
-	_, err = io.ReadAll(readerDefault)
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 
-	imageDefaultArchExists, err := ImageExistsLocally(ctx, "node:24-bookworm-slim", "linux/amd64")
+	amd64Exists, err := ImageExistsLocally(ctx, amd64Ref, "linux/amd64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.True(t, imageDefaultArchExists)
+	assert.True(t, amd64Exists)
 
-	// Validate if another architecture platform can be pulled
+	// a non-host architecture image is detected for its own architecture
-	readerArm64, err := cli.ImagePull(ctx, "node:24-bookworm-slim", client.ImagePullOptions{
+	arm64Exists, err := ImageExistsLocally(ctx, arm64Ref, "linux/arm64")
-		Platforms: []specs.Platform{{OS: "linux", Architecture: "arm64"}},
-	})
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	defer readerArm64.Close()
-	_, err = io.ReadAll(readerArm64)
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
+	assert.True(t, arm64Exists)
 
-	imageArm64Exists, err := ImageExistsLocally(ctx, "node:24-bookworm-slim", "linux/arm64")
+	// a present image is reported absent for a different platform
+	wrongPlatform, err := ImageExistsLocally(ctx, amd64Ref, "linux/arm64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.True(t, imageArm64Exists)
+	assert.False(t, wrongPlatform)
 }

act/container/docker_logger.go

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

act/container/docker_network.go

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

act/container/docker_network_test.go

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

act/container/docker_pull.go

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

act/container/docker_pull_test.go

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

act/container/docker_socket_test.go

@@ -18,9 +18,19 @@ func init() {
 
 var originalCommonSocketLocations = CommonSocketLocations
 
+func isolateSocketEnv(t *testing.T) {
+	t.Helper()
+	t.Cleanup(func() { CommonSocketLocations = originalCommonSocketLocations })
+	if host, ok := os.LookupEnv("DOCKER_HOST"); ok {
+		t.Setenv("DOCKER_HOST", host)
+	} else {
+		t.Cleanup(func() { os.Unsetenv("DOCKER_HOST") })
+	}
+}
+
 func TestGetSocketAndHostWithSocket(t *testing.T) {
 	// Arrange
-	CommonSocketLocations = originalCommonSocketLocations
+	isolateSocketEnv(t)
 	dockerHost := "unix:///my/docker/host.sock"
 	socketURI := "/path/to/my.socket"
 	t.Setenv("DOCKER_HOST", dockerHost)
@@ -48,9 +58,9 @@ func TestGetSocketAndHostNoSocket(t *testing.T) {
 
 func TestGetSocketAndHostOnlySocket(t *testing.T) {
 	// Arrange
+	isolateSocketEnv(t)
 	socketURI := "/path/to/my.socket"
 	os.Unsetenv("DOCKER_HOST")
-	CommonSocketLocations = originalCommonSocketLocations
 	defaultSocket, defaultSocketFound := socketLocation()
 
 	// Act
@@ -65,7 +75,7 @@ func TestGetSocketAndHostOnlySocket(t *testing.T) {
 
 func TestGetSocketAndHostDontMount(t *testing.T) {
 	// Arrange
-	CommonSocketLocations = originalCommonSocketLocations
+	isolateSocketEnv(t)
 	dockerHost := "unix:///my/docker/host.sock"
 	t.Setenv("DOCKER_HOST", dockerHost)
 
@@ -79,7 +89,7 @@ func TestGetSocketAndHostDontMount(t *testing.T) {
 
 func TestGetSocketAndHostNoHostNoSocket(t *testing.T) {
 	// Arrange
-	CommonSocketLocations = originalCommonSocketLocations
+	isolateSocketEnv(t)
 	os.Unsetenv("DOCKER_HOST")
 	defaultSocket, found := socketLocation()
 
@@ -97,6 +107,7 @@ func TestGetSocketAndHostNoHostNoSocket(t *testing.T) {
 // > This happens if neither DOCKER_HOST nor --container-daemon-socket has a value, but socketLocation() returns a URI
 func TestGetSocketAndHostNoHostNoSocketDefaultLocation(t *testing.T) {
 	// Arrange
+	isolateSocketEnv(t)
 	mySocketFile, tmpErr := os.CreateTemp(t.TempDir(), "act-*.sock")
 	mySocket := mySocketFile.Name()
 	unixSocket := "unix://" + mySocket
@@ -119,6 +130,7 @@ func TestGetSocketAndHostNoHostNoSocketDefaultLocation(t *testing.T) {
 
 func TestGetSocketAndHostNoHostInvalidSocket(t *testing.T) {
 	// Arrange
+	isolateSocketEnv(t)
 	os.Unsetenv("DOCKER_HOST")
 	mySocket := "/my/socket/path.sock"
 	CommonSocketLocations = []string{"/unusual", "/socket", "/location"}
@@ -136,6 +148,7 @@ func TestGetSocketAndHostNoHostInvalidSocket(t *testing.T) {
 
 func TestGetSocketAndHostOnlySocketValidButUnusualLocation(t *testing.T) {
 	// Arrange
+	isolateSocketEnv(t)
 	socketURI := "unix:///path/to/my.socket"
 	CommonSocketLocations = []string{"/unusual", "/location"}
 	os.Unsetenv("DOCKER_HOST")

act/container/docker_stub.go

@@ -8,12 +8,13 @@ package container
 
 import (
 	"context"
+	"errors"
 	"runtime"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
 	"github.com/moby/moby/api/types/system"
-	"github.com/pkg/errors"
 )
 
 // ImageExistsLocally returns a boolean indicating if an image with the
@@ -61,7 +62,7 @@ func NewDockerVolumeRemoveExecutor(volume string, force bool) common.Executor {
 	}
 }
 
-func NewDockerNetworkCreateExecutor(name string) common.Executor {
+func NewDockerNetworkCreateExecutor(name string, opts NewDockerNetworkCreateExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
 		return nil
 	}
@@ -72,3 +73,7 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 		return nil
 	}
 }
+
+func RemoveOrphanNetworks(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
+	return nil
+}

act/container/helpers_test.go

@@ -0,0 +1,27 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package container
+
+import (
+	"context"
+	"testing"
+
+	mobyclient "github.com/moby/moby/client"
+)
+
+// requireDocker skips the test unless a reachable docker daemon is available.
+// GetDockerClient succeeds even without a running daemon (its ping is best-effort),
+// so the daemon has to be pinged explicitly here to decide whether to skip.
+func requireDocker(t *testing.T) {
+	t.Helper()
+	ctx := context.Background()
+	cli, err := GetDockerClient(ctx)
+	if err != nil {
+		t.Skipf("skipping: docker client unavailable: %v", err)
+	}
+	defer cli.Close()
+	if _, err := cli.Ping(ctx, mobyclient.PingOptions{}); err != nil {
+		t.Skipf("skipping: docker daemon unreachable: %v", err)
+	}
+}

act/container/host_environment.go

@@ -16,7 +16,6 @@ import (
 	"os/exec"
 	"path/filepath"
 	"runtime"
-	"strconv"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -25,6 +24,7 @@ import (
 	"gitea.com/gitea/runner/act/common"
 	"gitea.com/gitea/runner/act/filecollector"
 	"gitea.com/gitea/runner/act/lookpath"
+	"gitea.com/gitea/runner/internal/pkg/process"
 
 	"github.com/go-git/go-billy/v5/helper/polyfill"
 	"github.com/go-git/go-billy/v5/osfs"
@@ -45,8 +45,24 @@ type HostEnvironment struct {
 	StdOut       io.Writer
 	AllocatePTY  bool // allocate a pseudo-TTY for each step's process
 
-	mu          sync.Mutex
+	// procGroup owns every process the job's steps start. Atomic: Remove may read
-	runningPIDs map[int]struct{}
+	// it while a step is still starting.
+	procGroupOnce sync.Once
+	procGroup     atomic.Pointer[process.Group]
+}
+
+// processGroup returns the job-scoped process group, creating it on first use.
+// Returns nil if the job object could not be created; Group is nil-safe.
+func (e *HostEnvironment) processGroup(ctx context.Context) *process.Group {
+	e.procGroupOnce.Do(func() {
+		group, err := process.NewGroup()
+		if err != nil {
+			common.Logger(ctx).Warnf("could not create the job's process group; processes a step leaves behind can only be reclaimed by the workspace scan: %v", err)
+			return
+		}
+		e.procGroup.Store(group)
+	})
+	return e.procGroup.Load()
 }
 
 func (e *HostEnvironment) Create(_, _ []string) common.Executor {
@@ -266,7 +282,7 @@ func setupPty(cmd *exec.Cmd, cmdline string) (*os.File, *os.File, error) {
 	cmd.Stdin = tty
 	cmd.Stdout = tty
 	cmd.Stderr = tty
-	cmd.SysProcAttr = getSysProcAttr(cmdline, true)
+	cmd.SysProcAttr = process.SysProcAttr(cmdline, true)
 	return ppty, tty, nil
 }
 
@@ -314,6 +330,10 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 	} else {
 		wd = e.Path
 	}
+	// Flush any buffered, not-yet-newline-terminated trailing line, as the docker backend
+	// does in waitForCommand, so the final line of a command's output is not lost.
+	defer common.FlushWriter(e.StdOut)
+
 	f, err := lookupPathHost(command[0], env, e.StdOut)
 	if err != nil {
 		return err
@@ -326,7 +346,12 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 	cmd.Env = envList
 	cmd.Stderr = e.StdOut
 	cmd.Dir = wd
-	cmd.SysProcAttr = getSysProcAttr(cmdline, false)
+	cmd.SysProcAttr = process.SysProcAttr(cmdline, false)
+
+	// Kills the step's whole tree on cancellation and bounds the post-exit I/O
+	// wait, so an orphan holding cmd's stdout pipe cannot hang cmd.Wait().
+	treeKill := process.NewTreeKill(cmd)
+
 	var ppty *os.File
 	var tty *os.File
 	defer func() {
@@ -353,23 +378,18 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 		go copyPtyOutput(writer, ppty, finishLog)
 		go writeKeepAlive(ppty)
 	}
-	// Split Start/Wait so the PID can be registered before the process can exit;
-	// cmd.Run() would block until exit, by which time the PID may have been reused.
 	if err := cmd.Start(); err != nil {
 		return err
 	}
-	if cmd.Process != nil {
+	// Assign before the step's Killer so the step's job nests inside the group's;
-		e.mu.Lock()
+	// cancellation still scopes to this step's tree.
-		if e.runningPIDs == nil {
+	if err := e.processGroup(ctx).Assign(cmd.Process); err != nil {
-			e.runningPIDs = map[int]struct{}{}
+		common.Logger(ctx).Warnf("could not assign the step's process to the job's process group; a process it leaves behind may outlive the job: %v", err)
-		}
+	}
-		e.runningPIDs[cmd.Process.Pid] = struct{}{}
+	if k, kerr := treeKill.Capture(cmd.Process); kerr != nil {
-		e.mu.Unlock()
+		common.Logger(ctx).Warnf("process tree kill setup failed, falling back to single-process kill: %v", kerr)
-		defer func(pid int) {
+	} else {
-			e.mu.Lock()
+		defer k.Close()
-			delete(e.runningPIDs, pid)
-			e.mu.Unlock()
-		}(cmd.Process.Pid)
 	}
 	err = cmd.Wait()
 	if err != nil {
@@ -413,6 +433,23 @@ func (e *HostEnvironment) UpdateFromEnv(srcPath string, env *map[string]string)
 	return parseEnvFile(e, srcPath, env)
 }
 
+// removeAll is a var so tests can substitute a blocking stub.
+var removeAll = os.RemoveAll
+
+// removeAllWithContext returns once the delete finishes or ctx is cancelled. On
+// cancellation the goroutine leaks: a delete inside a syscall cannot be
+// interrupted (see runWithTimeout).
+func removeAllWithContext(ctx context.Context, path string) error {
+	done := make(chan error, 1)
+	go func() { done <- removeAll(path) }()
+	select {
+	case err := <-done:
+		return err
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
 func removePathWithRetry(ctx context.Context, path string) error {
 	if path == "" {
 		return nil
@@ -432,64 +469,165 @@ func removePathWithRetry(ctx context.Context, path string) error {
 			case <-time.After(delay):
 			}
 		}
-		lastErr = os.RemoveAll(path)
+		lastErr = removeAllWithContext(ctx, path)
 		if lastErr == nil {
 			return nil
 		}
+		if errors.Is(lastErr, context.DeadlineExceeded) {
+			return lastErr
+		}
 	}
 	return lastErr
 }
 
+// buildWindowsWorkspaceKillScript builds a PowerShell command that taskkills
+// every process tree whose ExecutablePath or CommandLine references one of the
+// given workspace dirs, releasing file handles for cleanup. Win32_Process
+// exposes both fields (Get-Process doesn't, wmic is deprecated); matching is on
+// the dir+separator prefix via ordinal String methods, so a name-prefix sibling
+// (job1 vs job10) is spared and path metacharacters stay literal.
+func buildWindowsWorkspaceKillScript(dirs []string) string {
+	quoted := make([]string, len(dirs))
+	for i, d := range dirs {
+		// Single-quoted PowerShell literal; escape ' by doubling it.
+		quoted[i] = "'" + strings.ReplaceAll(d, "'", "''") + "'"
+	}
+
+	return `$paths = @(` + strings.Join(quoted, ",") + `)
+$selfPid = $PID
+Get-CimInstance Win32_Process -ErrorAction SilentlyContinue | Where-Object {
+    if ($_.ProcessId -eq $selfPid) { return $false }
+    foreach ($p in $paths) {
+        $prefix = $p + '\'
+        if ($_.ExecutablePath -and $_.ExecutablePath.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)) { return $true }
+        if ($_.CommandLine -and $_.CommandLine.IndexOf($prefix, [System.StringComparison]::OrdinalIgnoreCase) -ge 0) { return $true }
+    }
+    return $false
+} | ForEach-Object {
+    & taskkill.exe /PID $_.ProcessId /T /F 2>$null | Out-Null
+}
+`
+}
+
 func (e *HostEnvironment) terminateRunningProcesses(ctx context.Context) {
 	if runtime.GOOS != "windows" {
 		return
 	}
-	e.mu.Lock()
-	pids := make([]int, 0, len(e.runningPIDs))
-	for pid := range e.runningPIDs {
-		pids = append(pids, pid)
-	}
-	e.mu.Unlock()
 
-	if len(pids) == 0 {
+	// Detached: exec.CommandContext won't start on a cancelled ctx, and a
+	// server cancel has already cancelled the parent ctx.
+	killCtx, killCancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer killCancel()
+
+	logger := common.Logger(ctx)
+
+	// Dirs we own; a process referencing one is a leftover. ToolCache is shared
+	// across jobs, and Workdir may be a caller-owned checkout.
+	owned := []string{e.Path, e.TmpDir}
+	if e.CleanWorkdir {
+		owned = append(owned, e.Workdir)
+	}
+	dirs := make([]string, 0, len(owned))
+	for _, d := range owned {
+		if d == "" {
+			continue
+		}
+		abs, err := filepath.Abs(d)
+		if err != nil {
+			continue
+		}
+		dirs = append(dirs, abs)
+	}
+	if len(dirs) == 0 {
 		return
 	}
 
-	logger := common.Logger(ctx)
+	script := buildWindowsWorkspaceKillScript(dirs)
-	for _, pid := range pids {
+
-		// Best-effort: forcibly terminate process tree to release file handles
+	cmd := exec.CommandContext(killCtx, "powershell.exe", "-NoProfile", "-NonInteractive", "-Command", script)
-		// so that workspace cleanup can succeed on Windows.
+	out, err := cmd.CombinedOutput()
-		cmd := exec.CommandContext(ctx, "taskkill", "/PID", strconv.Itoa(pid), "/T", "/F")
+	if err != nil {
-		out, err := cmd.CombinedOutput()
+		logger.Debugf("workspace process-tree kill via PowerShell failed: %v output=%s", err, strings.TrimSpace(string(out)))
-		if err != nil {
+	}
-			logger.Debugf("taskkill failed for pid=%d: %v output=%s", pid, err, strings.TrimSpace(string(out)))
+
-		}
+	// Win32_Process exposes no working directory, so the scan above misses a
+	// process that merely runs in a workspace dir while pinning a handle on it.
+	if killed, err := process.KillProcessesWithCWDUnder(killCtx, dirs); err != nil {
+		logger.Debugf("workspace process kill by working directory reported errors: %v", err)
+	} else if killed > 0 {
+		logger.Debugf("terminated %d leftover process(es) by workspace working directory", killed)
+	}
+}
+
+// hostCleanupTimeout bounds each teardown phase so one stalled delete cannot
+// wedge the runner slot. A var so tests can shrink it.
+var hostCleanupTimeout = 30 * time.Second
+
+// runWithTimeout returns context.DeadlineExceeded once timeout elapses, leaking
+// the goroutine: a delete blocked in a syscall (AV filter driver, dead network
+// mount) cannot be interrupted, and leaking scratch state beats losing the
+// runner's capacity slot forever. The idle stale-dir sweep reclaims it later.
+func runWithTimeout(fn func(), timeout time.Duration) error {
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		fn()
+	}()
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+	select {
+	case <-done:
+		return nil
+	case <-timer.C:
+		return context.DeadlineExceeded
 	}
 }
 
 func (e *HostEnvironment) Remove() common.Executor {
 	return func(ctx context.Context) error {
-		// Ensure any lingering child processes are ended before attempting
+		logger := common.Logger(ctx)
-		// to remove the workspace (Windows file locks otherwise prevent cleanup).
+
+		// End lingering processes before removing the workspace; on Windows their
+		// file locks block cleanup. Closing the group is deterministic, the scan a net.
+		if err := e.procGroup.Load().Close(); err != nil {
+			logger.Debugf("closing the job's process group failed: %v", err)
+		}
 		e.terminateRunningProcesses(ctx)
 
-		// Only removes per-job misc state. Must not remove the cache/toolcache root.
+		// Removes per-job misc state only, never the toolcache root. Bounded because
+		// CleanUp is a caller-supplied, typically unbounded os.RemoveAll.
 		if e.CleanUp != nil {
-			e.CleanUp()
+			logger.Debugf("running host environment cleanup callback")
+			if err := runWithTimeout(e.CleanUp, hostCleanupTimeout); err != nil {
+				logger.Warnf("host environment cleanup did not finish within %s; continuing job completion, scratch state may be leaked and is reclaimed by the idle stale-dir sweep", hostCleanupTimeout)
+			} else {
+				logger.Debugf("host environment cleanup callback finished")
+			}
 		}
-		logger := common.Logger(ctx)
+
+		// Detach: a cancelled ctx would skip removePathWithRetry's retries,
+		// which absorb Windows file-handle release lag after the kill above.
+		rmCtx, rmCancel := context.WithTimeout(context.Background(), hostCleanupTimeout)
+		defer rmCancel()
+
 		var errs []error
-		if err := removePathWithRetry(ctx, e.Path); err != nil {
+		if err := removePathWithRetry(rmCtx, e.Path); err != nil {
 			logger.Warnf("failed to remove host misc state %s: %v", e.Path, err)
 			errs = append(errs, err)
 		}
 		if e.CleanWorkdir {
-			if err := removePathWithRetry(ctx, e.Workdir); err != nil {
+			if err := removePathWithRetry(rmCtx, e.Workdir); err != nil {
 				logger.Warnf("failed to remove host workspace %s: %v", e.Workdir, err)
 				errs = append(errs, err)
 			}
 		}
-		return errors.Join(errs...)
+		for _, err := range errs {
+			if !errors.Is(err, context.DeadlineExceeded) {
+				return errors.Join(errs...)
+			}
+		}
+		// Teardown timed out; warned above. Do not fail job completion over it.
+		return nil
 	}
 }
 

act/container/host_environment_test.go

@@ -15,6 +15,7 @@ import (
 	"runtime"
 	"strings"
 	"testing"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
@@ -187,3 +188,176 @@ func TestHostEnvironmentRemoveCleansWorkdirWhenOwned(t *testing.T) {
 	_, err := os.Stat(workdir)
 	assert.ErrorIs(t, err, os.ErrNotExist)
 }
+
+func TestRemoveAllWithContextDoesNotHangOnStuckDelete(t *testing.T) {
+	release := make(chan struct{})
+	stubDone := make(chan struct{})
+
+	orig := removeAll
+	removeAll = func(string) error {
+		defer close(stubDone)
+		<-release
+		return nil
+	}
+	// removeAllWithContext intentionally leaks the delete goroutine on timeout,
+	// and that goroutine still references removeAll. Unblock it and wait for it
+	// to return before restoring the var, so the restore can't race the read.
+	t.Cleanup(func() {
+		close(release)
+		<-stubDone
+		removeAll = orig
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	err := removeAllWithContext(ctx, t.TempDir())
+	require.ErrorIs(t, err, context.DeadlineExceeded)
+}
+
+// TestHostEnvironmentRemoveDoesNotHangOnStuckCleanUp guards against a stalled
+// CleanUp callback (e.g. an os.RemoveAll blocked by an AV/EDR filter driver or
+// an unresponsive mount) wedging the runner slot forever at "Cleaning up
+// container". Remove must time out the callback and complete job teardown.
+func TestHostEnvironmentRemoveDoesNotHangOnStuckCleanUp(t *testing.T) {
+	// Keep the suite fast: shrink the per-phase teardown timeout for this test.
+	orig := hostCleanupTimeout
+	hostCleanupTimeout = 100 * time.Millisecond
+	t.Cleanup(func() { hostCleanupTimeout = orig })
+
+	logger := logrus.New()
+	ctx := common.WithLogger(context.Background(), logrus.NewEntry(logger))
+	base := t.TempDir()
+	path := filepath.Join(base, "misc", "hostexecutor")
+	require.NoError(t, os.MkdirAll(path, 0o700))
+
+	release := make(chan struct{})
+	t.Cleanup(func() { close(release) }) // unblock the leaked goroutine at test end
+
+	e := &HostEnvironment{
+		Path: path,
+		CleanUp: func() {
+			<-release // simulate a delete syscall stuck indefinitely
+		},
+		StdOut: os.Stdout,
+	}
+
+	done := make(chan error, 1)
+	go func() { done <- e.Remove()(ctx) }()
+
+	select {
+	case err := <-done:
+		require.NoError(t, err)
+	case <-time.After(10 * time.Second):
+		t.Fatal("Remove() hung on a stuck CleanUp callback")
+	}
+}
+
+// TestHostEnvironmentRemoveDoesNotHangOnStuckPathRemoval guards against a
+// stalled os.RemoveAll on the misc/workspace paths (same AV/EDR wedge as
+// #1023) wedging job completion after the CleanUp callback has already timed
+// out or finished.
+func TestHostEnvironmentRemoveDoesNotHangOnStuckPathRemoval(t *testing.T) {
+	origTimeout := hostCleanupTimeout
+	hostCleanupTimeout = 100 * time.Millisecond
+	t.Cleanup(func() { hostCleanupTimeout = origTimeout })
+
+	release := make(chan struct{})
+	stubDone := make(chan struct{})
+
+	origRemoveAll := removeAll
+	removeAll = func(string) error {
+		defer close(stubDone)
+		<-release
+		return nil
+	}
+	// The stuck delete goroutine outlives the timed-out Remove and still reads
+	// removeAll; unblock it and wait before restoring to avoid a restore/read race.
+	t.Cleanup(func() {
+		close(release)
+		<-stubDone
+		removeAll = origRemoveAll
+	})
+
+	logger := logrus.New()
+	ctx := common.WithLogger(context.Background(), logrus.NewEntry(logger))
+	base := t.TempDir()
+	path := filepath.Join(base, "misc", "hostexecutor")
+	require.NoError(t, os.MkdirAll(path, 0o700))
+
+	e := &HostEnvironment{
+		Path:   path,
+		StdOut: os.Stdout,
+	}
+
+	done := make(chan error, 1)
+	go func() { done <- e.Remove()(ctx) }()
+
+	select {
+	case err := <-done:
+		require.NoError(t, err)
+	case <-time.After(10 * time.Second):
+		t.Fatal("Remove() hung on a stuck path removal")
+	}
+}
+
+func TestBuildWindowsWorkspaceKillScript(t *testing.T) {
+	t.Run("single dir", func(t *testing.T) {
+		s := buildWindowsWorkspaceKillScript([]string{`C:\workspace\job1`})
+		assert.Contains(t, s, `$paths = @('C:\workspace\job1')`)
+		// Self-PID guard is essential — without it the script could taskkill
+		// the PowerShell process running it.
+		assert.Contains(t, s, "$selfPid = $PID")
+		assert.Contains(t, s, "$_.ProcessId -eq $selfPid")
+		// Must match both ExecutablePath (binaries from the workspace) and
+		// CommandLine (system binaries invoked with workspace paths in args),
+		// both bounded by dir+separator so a name-prefix sibling is spared.
+		assert.Contains(t, s, `$prefix = $p + '\'`)
+		assert.Contains(t, s, "$_.ExecutablePath.StartsWith($prefix")
+		assert.Contains(t, s, "$_.CommandLine.IndexOf($prefix")
+		// Each matched PID must be tree-killed, not just stopped.
+		assert.Contains(t, s, "taskkill.exe /PID $_.ProcessId /T /F")
+	})
+
+	t.Run("multiple dirs comma-separated", func(t *testing.T) {
+		s := buildWindowsWorkspaceKillScript([]string{
+			`C:\work\path`,
+			`C:\work\workdir`,
+			`C:\Users\runner\AppData\Local\Temp\job-42`,
+		})
+		assert.Contains(t, s, `'C:\work\path'`)
+		assert.Contains(t, s, `'C:\work\workdir'`)
+		assert.Contains(t, s, `'C:\Users\runner\AppData\Local\Temp\job-42'`)
+		// Commas between entries — no trailing comma, no leading comma.
+		assert.Contains(t, s, `'C:\work\path','C:\work\workdir',`)
+	})
+
+	t.Run("path with single quote is escaped", func(t *testing.T) {
+		// In PowerShell single-quoted strings the only special char is the
+		// quote itself, escaped by doubling. A workspace path that ever
+		// contained `'` would inject a command into the script otherwise.
+		s := buildWindowsWorkspaceKillScript([]string{`C:\work\it's\path`})
+		assert.Contains(t, s, `'C:\work\it''s\path'`)
+		// And it must NOT appear unescaped — otherwise the quote would
+		// terminate the literal early.
+		assert.NotContains(t, s, `'C:\work\it's\path'`)
+	})
+
+	t.Run("path with wildcard metacharacters is matched literally", func(t *testing.T) {
+		// A path containing [ ] ? * must be embedded verbatim and matched with
+		// ordinal String methods, not -like, otherwise the metacharacters would
+		// be interpreted as wildcards and the leftover process could escape.
+		s := buildWindowsWorkspaceKillScript([]string{`C:\work\[job]?1`})
+		assert.Contains(t, s, `'C:\work\[job]?1'`)
+		assert.NotContains(t, s, "-like")
+		assert.Contains(t, s, "StartsWith")
+		assert.Contains(t, s, "IndexOf")
+	})
+
+	t.Run("empty dir list still produces a valid script", func(t *testing.T) {
+		s := buildWindowsWorkspaceKillScript(nil)
+		// Empty array literal — script runs, matches nothing, is a no-op.
+		assert.Contains(t, s, "$paths = @()")
+		assert.Contains(t, s, "Get-CimInstance Win32_Process")
+	})
+}

act/container/linux_container_environment_extensions.go

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