enhance: support Docker on FreeBSD and restructure the README (#1367)

1. Restructures the README into installation, quickstart, deployment, configuration, jobs and operation, and shortens it to user-facing prose. Option details are left to `config.example.yaml` and `docs/`, existing heading anchors are kept where possible.
2. FreeBSD builds used the Docker stub, so `docker://` labels, services and Docker actions failed there. The Docker code works on FreeBSD against a remote daemon, so it is enabled, and host jobs report `runner.os` as `FreeBSD`.
3. `make build` on Windows now writes `gitea-runner.exe`, taking the suffix from `go env GOEXE`.

Reviewed-on: https://gitea.com/gitea/runner/pulls/1367
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>

.dockerignore

@@ -45,8 +45,13 @@ cpu.out
 
 /bin
 /dist
+/.tmp
+/.git/hooks
+/.git/logs
+/.git/rr-cache
 /.env
 /.runner
+/.runner.lock
 /config.yaml
 /Dockerfile
 .DS_Store

.gitea/actions/go-setup/action.yml

@@ -0,0 +1,29 @@
+name: go-setup
+description: Set up go and restore its caches, which only the cache-seeder workflow saves
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+      id: setup-go
+      with:
+        go-version-file: go.mod
+        check-latest: true
+        cache: false
+    - if: ${{ github.workflow == 'cache-seeder' }}
+      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      with:
+        path: |
+          ~/go/pkg/mod
+          ~/.cache/go-build
+          ~/.cache/golangci-lint
+        key: go-${{ runner.os }}-${{ runner.arch }}-${{ steps.setup-go.outputs.go-version }}-${{ hashFiles('go.mod', 'go.sum', '.golangci.yml', 'Makefile', '.gitea/actions/go-setup/action.yml', '.gitea/workflows/cache-seeder.yml') }}
+    - if: ${{ github.workflow != 'cache-seeder' }}
+      uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      with:
+        path: |
+          ~/go/pkg/mod
+          ~/.cache/go-build
+          ~/.cache/golangci-lint
+        key: go-${{ runner.os }}-${{ runner.arch }}-${{ steps.setup-go.outputs.go-version }}-${{ hashFiles('go.mod', 'go.sum', '.golangci.yml', 'Makefile', '.gitea/actions/go-setup/action.yml', '.gitea/workflows/cache-seeder.yml') }}
+        restore-keys: go-${{ runner.os }}-${{ runner.arch }}-${{ steps.setup-go.outputs.go-version }}-

.gitea/workflows/cache-seeder.yml

@@ -0,0 +1,26 @@
+name: cache-seeder
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - go.mod
+      - go.sum
+      - .golangci.yml
+      - Makefile
+      - .gitea/actions/go-setup/action.yml
+      - .gitea/workflows/cache-seeder.yml
+
+jobs:
+  seed:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: ./.gitea/actions/go-setup
+      - run: make deps-tools lint build
+      - name: compile the test binaries without running them
+        run: |
+          make test GOTEST_FLAGS='-race -exec true'
+          go test -tags e2e -exec true ./e2e/...

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

@@ -19,9 +19,9 @@ jobs:
     timeout-minutes: 5
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-    - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+    - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
       with:
-        node-version: 24
+        node-version: 26
     - run: make lint-pr-title
       env:
         PR_TITLE: ${{ github.event.pull_request.title }}

.gitea/workflows/release-nightly.yml

@@ -11,7 +11,6 @@ on:
 
 env:
   DOCKER_ORG: gitea
-  DOCKER_LATEST: nightly
 
 jobs:
   goreleaser:
@@ -20,11 +19,10 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
-      # Custom publishers (the R2 mirror below) run as the very last
+      # Custom publishers (the R2 upload 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.
+      # has already been created. 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:
@@ -35,18 +33,14 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: "go.mod"
+          check-latest: true
       - name: goreleaser
-        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
+        uses: goreleaser/goreleaser-action@a4f02ab5355a589de60d917a659ce617ed19b3de # v7
         with:
           distribution: goreleaser-pro
           args: release --nightly
         env:
           GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}
-          AWS_REGION: ${{ secrets.AWS_REGION }}
-          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_KEY_ID }}
-          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 }}
@@ -79,13 +73,13 @@ jobs:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to DockerHub
-        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
@@ -99,7 +93,7 @@ jobs:
           echo REPO_VERSION=$(git describe --tags --always | sed 's/-/+/' | sed 's/^v//') >> $GITHUB_OUTPUT
 
       - name: Build and push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: ./Dockerfile

.gitea/workflows/release-tag.yml

@@ -12,11 +12,10 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0 # all history for all branches and tags
-      # Custom publishers (the R2 mirror below) run as the very last
+      # Custom publishers (the R2 upload 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.
+      # has already been created. 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:
@@ -27,6 +26,7 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: "go.mod"
+          check-latest: true
       - name: Import GPG key
         id: import_gpg
         uses: crazy-max/ghaction-import-gpg@2dc316deee8e90f13e1a351ab510b4d5bc0c82cd # v7
@@ -35,17 +35,12 @@ jobs:
           passphrase: ${{ secrets.PASSPHRASE }}
           fingerprint: CC64B1DB67ABBEECAB24B6455FC346329753F4B0
       - name: goreleaser
-        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
+        uses: goreleaser/goreleaser-action@a4f02ab5355a589de60d917a659ce617ed19b3de # v7
         with:
           distribution: goreleaser-pro
           args: release
         env:
           GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}
-          AWS_REGION: ${{ secrets.AWS_REGION }}
-          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_KEY_ID }}
-          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 }}
@@ -74,7 +69,6 @@ jobs:
       image: catthehacker/ubuntu:act-latest
     env:
       DOCKER_ORG: gitea
-      DOCKER_LATEST: latest
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -82,13 +76,13 @@ jobs:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to DockerHub
-        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
@@ -108,7 +102,7 @@ jobs:
             suffix=${{ matrix.variant.tag_suffix }},onlatest=true
 
       - name: Build and push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: ./Dockerfile

.gitea/workflows/test-windows.yml

@@ -0,0 +1,21 @@
+name: windows
+on:
+  schedule:
+    - cron: '0 3 * * 1'
+  workflow_dispatch:
+
+env:
+  DOCKER_CONFIG: /tmp/docker-noauth # see test.yml
+
+jobs:
+  test:
+    name: test on windows
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: ./.gitea/actions/go-setup
+      - name: prepare anonymous docker config
+        run: mkdir -p "$DOCKER_CONFIG" && echo '{}' > "$DOCKER_CONFIG/config.json"
+      - name: test on windows
+        run: make test-windows

.gitea/workflows/test.yml

@@ -1,35 +1,41 @@
 name: checks
 on:
-  push:
-    branches:
-      - main
   pull_request:
+  workflow_dispatch:
+
+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 workflow-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
 
 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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
-        with:
-          go-version-file: 'go.mod'
+      - uses: ./.gitea/actions/go-setup
       - 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.
+      # daemon retains them between runs, and their digest pins skip the registry when it has them.
       - name: pre-pull test images
+        env:
+          TEST_JOB_IMAGE: node:26-bookworm-slim@sha256:bc0a2afd3b74ce12222fc8bab99271e66257f021078f5f4a5d687a77d280c1d9 # renovate: datasource=docker
+          TEST_SERVICE_IMAGE: nginx:alpine@sha256:a3554c0d0b48177b1413c26e01f695334428020d9df01243fbae3e11cfd17417 # renovate: datasource=docker
         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
+          for image in "$TEST_JOB_IMAGE" "$TEST_SERVICE_IMAGE"; do
+            if [ "$(docker image inspect --format '{{.Os}}/{{.Architecture}}' "$image" 2>/dev/null)" != linux/amd64 ]; then
+              for attempt in 1 2 3; do
+                docker pull "$image" && break
+                [ "$attempt" = 3 ] || sleep 5
+              done
+            fi
+            docker tag "$image" "${image%@*}"
           done
       - name: lint
         run: make lint
@@ -44,7 +50,25 @@ jobs:
       # after `make test` so the images it needs are already present on the host daemon.
       - name: test against dind image
         run: make test-dind
+      - name: test against podman
+        run: make test-dind TARGET=podman
       - name: coverage report
         run: |
           make coverage-report
-          cat .tmp/coverage.md >> "$GITHUB_STEP_SUMMARY"
+          cat .tmp/coverage.md >> "$GITHUB_STEP_SUMMARY"
+
+  e2e:
+    name: gitea compatibility (${{ matrix.gitea_image }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        gitea_image:
+          - gitea/gitea:latest
+          - gitea/gitea:main-nightly
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: ./.gitea/actions/go-setup
+      - name: prepare anonymous docker config
+        run: mkdir -p "$DOCKER_CONFIG" && echo '{}' > "$DOCKER_CONFIG/config.json"
+      - name: e2e compatibility
+        run: make test-e2e E2E_GITEA_IMAGE=${{ matrix.gitea_image }}

.gitignore

@@ -1,4 +1,5 @@
 /gitea-runner
+/gitea-runner.exe
 .env
 !/act/runner/testdata/secrets/.env
 .runner

.golangci.yml

@@ -39,6 +39,13 @@ linters:
           deny:
             - pkg: golang.org/x/exp
               desc: it's experimental and unreliable
+        logging:
+          files:
+            - $all
+            - "!**/act/common/logging/**"
+          deny:
+            - pkg: log/slog
+              desc: log through gitea.com/gitea/runner/act/common/logging
     nolintlint:
       allow-unused: false
       require-explanation: true
@@ -46,8 +53,7 @@ linters:
     gocritic:
       enabled-checks:
         - equalFold
-      disabled-checks:
-        - ifElseChain
+      disabled-checks: []
     revive:
       severity: error
       rules:
@@ -71,10 +77,14 @@ linters:
         - name: unexported-return
         - name: var-declaration
         - name: var-naming
+          arguments:
+            - [] # AllowList - do not remove as args for the rule are positional and won't work without lists first
+            - [] # DenyList
+            - - skip-initialism-name-checks: true
     staticcheck:
       checks:
         - all
-        - -ST1005
+    testifylint: {}
     usetesting:
       os-temp-dir: true
     perfsprint:
@@ -92,8 +102,6 @@ linters:
     generated: lax
     presets:
       - comments
-      - common-false-positives
-      - legacy
       - std-error-handling
     rules:
       - linters:
@@ -118,7 +126,8 @@ formatters:
         - blank
         - default
     gofumpt:
-      extra-rules: true
+      extra:
+        group-params: true
   exclusions:
     generated: lax
 run:

.goreleaser.yaml

@@ -28,38 +28,16 @@ builds:
   ignore:
     - goos: darwin
       goarch: arm
-    - goos: darwin
-      goarch: ppc64le
     - goos: darwin
       goarch: s390x
-    - goos: windows
-      goarch: ppc64le
     - goos: windows
       goarch: s390x
     - goos: windows
       goarch: arm
-      goarm: "5"
-    - goos: windows
-      goarch: arm
-      goarm: "6"
-    - goos: windows
-      goarch: arm
-      goarm: "7"
-    - goos: windows
-      goarch: arm64
-    - goos: freebsd
-      goarch: ppc64le
     - goos: freebsd
       goarch: s390x
     - goos: freebsd
       goarch: arm
-      goarm: "5"
-    - goos: freebsd
-      goarch: arm
-      goarm: "6"
-    - goos: freebsd
-      goarch: arm
-      goarm: "7"
     - goos: freebsd
       goarch: arm64
   flags:
@@ -83,24 +61,12 @@ builds:
       - cmd: sh .goreleaser.checksum.sh {{ .Path }}
       - cmd: sh .goreleaser.checksum.sh {{ .Path }}.xz
 
-blobs:
-  -
-    provider: s3
-    bucket: "{{ .Env.S3_BUCKET }}"
-    region: "{{ .Env.S3_REGION }}"
-    directory: "gitea-runner/{{.Version}}"
-    extra_files:
-      - 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.
+# Uploads every release artifact to Cloudflare R2. The `blobs:` pipe
+# isn't usable here since it 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`
@@ -125,7 +91,7 @@ publishers:
       - R2_SECRET_ACCESS_KEY={{ index .Env "R2_SECRET_ACCESS_KEY" }}
 
 archives:
-  - format: binary
+  - formats: [binary]
     name_template: "{{ .Binary }}"
     allow_different_binary_count: true
 

AGENTS.md

@@ -8,6 +8,7 @@
 - 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
+- Read `DEVELOPMENT.md` for internals and conventions
 - Ensure no trailing whitespace in edited files
 - Run `make fmt` after `.go` edits, `make tidy` after `go.mod` edits, and `make checks` for the non-lint source checks
 - Lint what changed with `make lint-go`, and `make lint-go-windows` for Windows and platform-split files

CLAUDE.md

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

DEVELOPMENT.md

@@ -0,0 +1,80 @@
+# Development
+
+## Job log line format
+
+Gitea stores one log row per line and its web UI decodes the payload, so getting the encoding
+wrong never fails a test here, it only shows up in the browser.
+
+**A row cannot contain a real newline.** `FormatLog` rewrites `\n` to a literal backslash-n and
+truncates at 64 KiB on a byte boundary.
+
+**The payload of a line starting with a recognised prefix is decoded**, with the escape set
+depending on the prefix:
+
+| prefix | decodes |
+| --- | --- |
+| `##[error]` `##[warning]` `##[notice]` `##[debug]` `##[group]` `##[endgroup]` `##[add-matcher]` | `%25` `%0D` `%0A` `%3B` `%5D` |
+| `::error::` `::warning::` `::notice::` `::debug::` (with or without ` key=value` properties), `::group::` `::endgroup::` `::add-matcher::` | `%25` `%0D` `%0A` |
+| `##[command]` `[command]`, or no recognised prefix | nothing |
+
+### Rules
+
+- **Emitting a command line?** Escape the payload with `runner.EscapeCommandData`. One escaper
+  covers both forms: it escapes `%` first, so a literal `%3B` becomes `%253B` that the extra
+  `##[…]` rules cannot match, and a raw `;` or `]` is never decoded. It is also what makes
+  multi-line work, `\n` becomes `%0A` and the UI turns it back into a line break.
+- **Forwarding a command from step output?** Leave the payload alone, it arrived escaped and is
+  decoded once. Decoding here double-decodes and destroys multi-line.
+- **No prefix?** Do not escape, and split multi-line values into one row each.
+- **Interpolating a secret?** Masking runs after escaping, so `AppendSecretMasker` registers the
+  encoded forms too.
+- Command *properties* also escape `%3A` and `%2C`, which the UI never decodes, so the command
+  handler folds an annotation's location into its decoded message and escapes the result again.
+
+## Logging
+
+Log through `act/common/logging`; the linter rejects importing `log/slog` elsewhere.
+A job's logger comes from `common.Logger(ctx)`; code with no job uses the package functions
+(`logging.Infof`, `logging.With`). Both take printf-style messages, and `With("key", value)` adds
+fields.
+
+- The process-wide logger masks the secrets of every live task, the job logger masks its own.
+  Going around either leaks them.
+- The job logger's output can reach the job log workflow authors see, the process-wide logger's
+  stays on the runner host, so keep operator-only detail (host paths, internal addresses) off the
+  job logger.
+- Libraries that log through slog's global logger are forwarded to the process-wide one, so they
+  follow its level and masking too. Avoid dependencies that log through logrus, nothing forwards it.
+- Tests read what was logged with `logtest.NewLogger()`, or `logtest.SetDefault(t)` for the
+  package functions.
+
+## Built-in actions
+
+Each lives in `internal/pkg/action/<name>` and is registered in `builtinActions` in
+`act/runner/step_action_builtin.go`.
+
+## End-to-end compatibility tests
+
+`make test-e2e` runs the runner against `E2E_GITEA_IMAGE`. It defaults to the nightly image.
+It requires Docker and is excluded from `make test`. CI runs stable and nightly variants in
+parallel. Outside a container it runs `go test` in a Linux container on its own network, as CI does,
+so both take the same paths. `E2E_ARGS` passes extra flags, e.g. `make test-e2e E2E_ARGS='-run TestCompatibility/dispatch'`.
+
+The `cli_*` scenarios build the binary and drive `register` and `daemon` as a user would, including `--once`,
+`--labels` and shutdown with a running job. `failure_paths` covers failed, skipped and tolerated jobs, `job_timeout`
+a job killed at the runner's deadline. `label_routing` and `capacity` cover scheduling, `reconnect` drops the
+connection to Gitea through a proxy, and `host_mode` and `reusable_workflow` cover host labels and `workflow_call`.
+`dispatch`, `failure_paths` and `reusable_workflow` run in every mode: through the daemon and `exec`, each on
+Docker and Kubernetes.
+
+The suite shares one Gitea, regular runner and k3s cluster. Cache and ephemeral scenarios use isolated
+repository runners. A run path is `<workflow>@<ref>` and a log row is `<timestamp>Z <payload>`.
+
+## Windows tests
+
+`make test-windows` cross-compiles the test binaries, installs Windows Server 2025 Core in a
+[dockur/windows](https://github.com/dockur/windows) QEMU VM on the docker host and runs them there.
+The host must be amd64 and allow privileged containers. `WINDOWS_TEST_TIMEOUT` sets the minutes
+allowed for installing Windows and running the tests, 165 by default. The VM uses KVM when the host
+has `/dev/kvm`, otherwise Windows is emulated and much slower. Docker-backed tests skip in the VM
+and the race detector is off, it needs cgo. CI runs this weekly and on demand.

Dockerfile

@@ -1,7 +1,7 @@
 ### BUILDER STAGE
 #
 #
-FROM golang:1.26-alpine3.23 AS builder
+FROM golang:1.27-alpine AS builder
 
 # Do not remove `git` here, it is required for getting runner version when executing `make build`
 RUN apk add --no-cache make git
@@ -12,12 +12,14 @@ ENV GOPROXY=${GOPROXY:-}
 COPY . /opt/src/runner
 WORKDIR /opt/src/runner
 
-RUN make clean && make build
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/root/.cache/go-build \
+    make clean && make build
 
 ### DIND VARIANT
 #
 #
-FROM docker:29.6.2-dind AS dind
+FROM docker:29.9.2-dind AS dind
 
 ARG VERSION=dev
 
@@ -32,12 +34,14 @@ COPY scripts/s6 /etc/s6
 
 VOLUME /data
 
+ENV TINI_SUBREAPER=1
+
 ENTRYPOINT ["s6-svscan","/etc/s6"]
 
 ### DIND-ROOTLESS VARIANT
 #
 #
-FROM docker:29.6.2-dind-rootless AS dind-rootless
+FROM docker:29.9.2-dind-rootless AS dind-rootless
 
 ARG VERSION=dev
 
@@ -56,6 +60,7 @@ VOLUME /data
 RUN mkdir -p /data && chown -R rootless:rootless /etc/s6 /data
 
 ENV DOCKER_HOST=unix:///run/user/1000/docker.sock
+ENV TINI_SUBREAPER=1
 
 USER rootless
 ENTRYPOINT ["s6-svscan","/etc/s6"]

Makefile

@@ -1,25 +1,23 @@
 DIST := dist
-EXECUTABLE := gitea-runner
-DIST_DIRS := $(DIST)/binaries $(DIST)/release
 GO ?= go
-SHASUM ?= shasum -a 256
+EXECUTABLE := gitea-runner$(shell $(GO) env GOEXE)
 HAS_GO = $(shell hash $(GO) > /dev/null 2>&1 && echo "GO" || echo "NOGO" )
-XGO_PACKAGE ?= src.techknowlogick.com/xgo@v1.9.0 # renovate: datasource=go
-XGO_VERSION := go-1.26.x
-GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/gxz@v0.5.15 # renovate: datasource=go
 
-LINUX_ARCHS ?= linux/amd64,linux/arm64
-DARWIN_ARCHS ?= darwin-12/amd64,darwin-12/arm64
-WINDOWS_ARCHS ?= windows/amd64
+PODMAN_TEST_IMAGE ?= quay.io/containers/podman:v5.8.9-immutable@sha256:87f42f37fa85b421664c30b8f5f9cfc23920057f5e5fcadf0b6f68d9edc6d415 # renovate: datasource=docker
+E2E_JOB_IMAGE ?= docker.gitea.com/runner-images:ubuntu-latest@sha256:657378e5cfd898e36f820459c60ef8e69be8fcda9fd354e4381a8b654d091bbc # renovate: datasource=docker
+SERVICE_IMAGE ?= nginx:1.31.7-alpine@sha256:892bb2152464f0c5d8972593a5f5afaf8054552580b699d95f8ff4af08c2d33d # renovate: datasource=docker
+E2E_GITEA_IMAGE ?= gitea/gitea:main-nightly
+E2E_K3S_IMAGE ?= rancher/k3s:v1.37.1-k3s1@sha256:ca7f37d993d82ef0dcdcfecb2e0e2618ea541dbaffc620c8cedebe01a82acd0d # renovate: datasource=docker
+WINDOWS_TEST_IMAGE ?= dockurr/windows:6.06@sha256:16fd7c39a3e48bb946d29c59dc6015942e5b900a1fa5d7e5552053bfc48ee2ea # renovate: datasource=docker
+
 GOFILES := $(shell find . -type f -name "*.go" -o -name "go.mod" ! -name "generated.*")
 
 DOCKER_IMAGE ?= gitea/runner
 DOCKER_TAG ?= nightly
 DOCKER_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)
-DOCKER_ROOTLESS_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)-dind-rootless
 
-GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 # renovate: datasource=go
-GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.3.0 # renovate: datasource=go
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 # renovate: datasource=go
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.9.0 # renovate: datasource=go
 
 GOTEST_FLAGS ?= -race -timeout 20m -parallel 8
 
@@ -32,22 +30,16 @@ endif
 ifeq ($(HAS_GO), GO)
 	GOPATH ?= $(shell $(GO) env GOPATH)
 	export PATH := $(GOPATH)/bin:$(PATH)
-
-	CGO_EXTRA_CFLAGS := -DSQLITE_MAX_VARIABLE_NUMBER=32766
-	CGO_CFLAGS ?= $(shell $(GO) env CGO_CFLAGS) $(CGO_EXTRA_CFLAGS)
 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
 
@@ -96,19 +88,12 @@ go-check:
 	fi
 
 .PHONY: fmt-check
-fmt-check: fmt
-	@diff=$$(git diff --color=always -- '*.go'); \
-	if [ -n "$$diff" ]; then \
-		echo "Please run 'make fmt' and commit the result:"; \
-		printf "%s" "$${diff}"; \
-		exit 1; \
-	fi
+fmt-check: ## check the Go code formatting
+	$(GO) run $(GOLANGCI_LINT_PACKAGE) fmt --diff-colored
 
 .PHONY: deps-tools
 deps-tools: ## install tool dependencies
 	$(GO) install $(GOLANGCI_LINT_PACKAGE) & \
-	$(GO) install $(GXZ_PACKAGE) & \
-	$(GO) install $(XGO_PACKAGE) & \
 	$(GO) install $(GOVULNCHECK_PACKAGE) & \
 	wait
 
@@ -137,20 +122,20 @@ lint-pr-title: ## lint PR title against Conventional Commits (set PR_TITLE=...)
 
 .PHONY: security-check
 security-check:
-	GOEXPERIMENT= $(GO) run $(GOVULNCHECK_PACKAGE) -show color ./... || true
+	$(GO) run $(GOVULNCHECK_PACKAGE) -show color ./... || true
 
 .PHONY: tidy
 tidy: ## run go mod tidy
+	$(eval GO_TOOLCHAIN := $(shell grep -Eo '^toolchain\s+go[0-9.]+' go.mod | cut -d' ' -f2))
 	$(GO) mod tidy
+	@# workaround https://github.com/golang/go/issues/75331: restore toolchain if tidy dropped it
+	@if [ -n "$(GO_TOOLCHAIN)" ] && ! grep -qE '^toolchain\s' go.mod; then \
+		$(GO) mod edit -toolchain=$(GO_TOOLCHAIN); \
+	fi
 
 .PHONY: tidy-check
-tidy-check: tidy
-	@diff=$$(git diff --color=always -- go.mod go.sum); \
-	if [ -n "$$diff" ]; then \
-		echo "Please run 'make tidy' and commit the result:"; \
-		printf "%s" "$${diff}"; \
-		exit 1; \
-	fi
+tidy-check: ## check that go.mod and go.sum are tidy
+	$(GO) mod tidy -diff
 
 .PHONY: test
 test: ## test everything (integration tests self-skip without docker/network)
@@ -163,8 +148,18 @@ coverage-report: ## turn coverage.txt from `make test` into .tmp/coverage.md
 	@echo "Wrote .tmp/coverage.md"
 
 .PHONY: test-dind
-test-dind: ## run the daemon-facing tests against the built dind image (TARGET=dind|dind-rootless)
-	@./scripts/test-dind.sh $(TARGET)
+test-dind: ## run the daemon-facing tests against the built dind image or podman (TARGET=dind|dind-rootless|podman)
+	@PODMAN_TEST_IMAGE=$(PODMAN_TEST_IMAGE) ./scripts/test-dind.sh $(TARGET)
+
+.PHONY: test-windows
+test-windows: ## run the tests on Windows Server Core in a QEMU VM on the docker host
+	@WINDOWS_TEST_IMAGE=$(WINDOWS_TEST_IMAGE) ./scripts/test-windows.sh
+
+E2E_CONCURRENCY ?= 8
+
+.PHONY: test-e2e
+test-e2e: ## run Gitea compatibility tests against E2E_GITEA_IMAGE
+	@E2E_CONCURRENCY=$(E2E_CONCURRENCY) E2E_GITEA_IMAGE=$(E2E_GITEA_IMAGE) E2E_K3S_IMAGE=$(E2E_K3S_IMAGE) E2E_JOB_IMAGE=$(E2E_JOB_IMAGE) GO=$(GO) SERVICE_IMAGE=$(SERVICE_IMAGE) ./tools/test-e2e.sh $(E2E_ARGS)
 
 .PHONY: install
 install: $(GOFILES) ## install the runner binary via `go install`
@@ -180,45 +175,6 @@ $(EXECUTABLE): $(GOFILES)
 deps-backend: ## install backend dependencies
 	$(GO) mod download
 
-.PHONY: release
-release: release-windows release-linux release-darwin release-copy release-compress release-check ## build release artifacts
-
-$(DIST_DIRS):
-	mkdir -p $(DIST_DIRS)
-
-.PHONY: release-windows
-release-windows: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -buildmode exe -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w -linkmode external -extldflags "-static" $(LDFLAGS)' -targets '$(WINDOWS_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
-ifeq ($(CI),true)
-	cp -r /build/* $(DIST)/binaries/
-endif
-
-.PHONY: release-linux
-release-linux: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w -linkmode external -extldflags "-static" $(LDFLAGS)' -targets '$(LINUX_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
-ifeq ($(CI),true)
-	cp -r /build/* $(DIST)/binaries/
-endif
-
-.PHONY: release-darwin
-release-darwin: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w $(LDFLAGS)' -targets '$(DARWIN_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
-ifeq ($(CI),true)
-	cp -r /build/* $(DIST)/binaries/
-endif
-
-.PHONY: release-copy
-release-copy: | $(DIST_DIRS)
-	cd $(DIST); for file in `find . -type f -name "*"`; do cp $${file} ./release/; done;
-
-.PHONY: release-check
-release-check: | $(DIST_DIRS)
-	cd $(DIST)/release/; for file in `find . -type f -name "*"`; do echo "checksumming $${file}" && $(SHASUM) `echo $${file} | sed 's/^..//'` > $${file}.sha256; done;
-
-.PHONY: release-compress
-release-compress: | $(DIST_DIRS)
-	cd $(DIST)/release/; for file in `find . -type f -name "*"`; do echo "compressing $${file}" && $(GO) run $(GXZ_PACKAGE) -k -9 $${file}; done;
-
 .PHONY: docker
 docker: ## build the docker image
 	if ! docker buildx version >/dev/null 2>&1; then \

README.md

@@ -1,14 +1,28 @@
 # Gitea Runner
 
+Gitea Runner runs the jobs of Gitea Actions workflows. Register it with a Gitea instance to run jobs in Docker containers, Kubernetes pods or directly on the host.
+
 ## Installation
 
 ### Prerequisites
 
-Docker Engine Community version is required for docker mode. To install Docker CE, follow the official [install instructions](https://docs.docker.com/engine/install/).
+- Linux, macOS or Windows, or FreeBSD.
+- `git` 2.34.1 or newer.
+- `docker`, or `podman` with `podman.socket` enabled, for `docker` labels and Docker actions. See Docker's [install instructions](https://docs.docker.com/engine/install/).
+
+In the job image, or on the host for host jobs:
+
+- `bash` or `sh`, or `pwsh` or `powershell` on Windows.
+- `node` for JavaScript actions and `hashFiles()`.
+- `git` 2.34.1 or newer for [`builtin:checkout`](docs/builtin-actions.md).
+- `git-lfs` for `builtin:checkout` with `lfs: true`.
+- `ssh` for `builtin:checkout` with `ssh-key`.
+
+Kubernetes mode needs [a few more tools](docs/kubernetes.md) in job images.
 
 ### Download pre-built binary
 
-Visit [here](https://dl.gitea.com/gitea-runner/) and download the right version for your platform.
+Download the binary for your platform from [dl.gitea.com](https://dl.gitea.com/gitea-runner/).
 
 ### Build from source
 
@@ -24,7 +38,7 @@ make docker
 
 ## Quickstart
 
-Actions are disabled by default, so you need to add the following to the configuration file of your Gitea instance to enable it:
+Enable Actions in the configuration file of your Gitea instance:
 
 ```ini
 [actions]
@@ -37,181 +51,154 @@ ENABLED=true
 ./gitea-runner register
 ```
 
-And you will be asked to input:
+It asks for:
 
-1. Gitea instance URL, like `http://192.168.8.8:3000/`. You should use your gitea instance ROOT_URL as the instance argument
- and you should not use `localhost` or `127.0.0.1` as instance IP;
-2. Runner token, you can get it from `http://192.168.8.8:3000/admin/actions/runners`;
-3. Runner name, you can just leave it blank;
-4. Runner labels, you can just leave it blank.
+1. The Gitea instance URL. Use its `ROOT_URL`, not `localhost` or `127.0.0.1`.
+2. A runner token, from `/admin/actions/runners` on your instance.
+3. A runner name, the hostname when left blank.
+4. The runner [labels](#labels), the defaults when left blank.
 
-The process looks like:
-
-```text
-INFO Registering runner, arch=amd64, os=darwin, version=0.1.5.
-WARN Runner in user-mode.
-INFO Enter the Gitea instance URL (for example, https://gitea.com/):
-http://192.168.8.8:3000/
-INFO Enter the runner token:
-fe884e8027dc292970d4e0303fe82b14xxxxxxxx
-INFO Enter the runner name (if set empty, use hostname: Test.local):
-
-INFO Enter the runner labels, leave blank to use the default labels (comma-separated, for example, ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest):
-
-INFO Registering runner, name=Test.local, instance=http://192.168.8.8:3000/, labels=[ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04 ubuntu-20.04:docker://docker.gitea.com/runner-images:ubuntu-20.04].
-DEBU Successfully pinged the Gitea instance server
-INFO Runner registered successfully.
-```
-
-You can also register with command line arguments.
+To register without prompts:
 
 ```bash
-./gitea-runner register --instance http://192.168.8.8:3000 --token <my_runner_token> --no-interactive
+./gitea-runner register --instance https://gitea.example.com --token <token> --no-interactive
 ```
 
-If the registry succeed, it will run immediately. Next time, you could run the runner directly.
-
 ### Run
 
 ```bash
 ./gitea-runner daemon
 ```
 
+## Deployment
+
+### Windows service
+
+Register the runner first, keeping `gitea-runner.exe`, `config.yaml` and the `.runner` file in one directory. Then install and start the service from an elevated Command Prompt:
+
+```bat
+sc.exe create gitea-runner binPath= "\"C:\gitea-runner\gitea-runner.exe\" daemon --config \"C:\gitea-runner\config.yaml\"" start= auto
+sc.exe start gitea-runner
+```
+
+The service logs to `gitea-runner.log` next to the executable. Its account needs write access to that directory and access to the tools jobs use.
+
+`sc.exe stop gitea-runner` lets running jobs finish within `runner.shutdown_timeout`. To allow the same on shutdown, raise the service's preshutdown timeout above it, here to six minutes. This takes effect after the next reboot:
+
+```bat
+reg.exe add HKLM\SYSTEM\CurrentControlSet\Services\gitea-runner /v PreshutdownTimeout /t REG_DWORD /d 360000 /f
+```
+
 ### Run with docker
 
-```bash
-docker run -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> -v /var/run/docker.sock:/var/run/docker.sock --name my_runner gitea/runner:nightly
-```
-
-Mount a volume on `/data` if you want the registration file and optional config to survive container recreation (see [scripts/run.sh](scripts/run.sh)).
-
-> **`/data` does not hold the image cache.** It is the runner's working directory and contains only the `.runner` registration file and, optionally, your config file. Images pulled for jobs live in the *Docker daemon's* data root, which for the `dind` flavours is inside the container (`/var/lib/docker`, or `/home/rootless/.local/share/docker` for `dind-rootless`). To keep the image cache across restarts, give that path its own volume as well — otherwise every new container re-pulls the job images. With the `basic` flavour the images live on whichever daemon you point the runner at, so there is nothing extra to persist.
-
-### Image flavours
-
-The image is published in three flavours, all built from the single multi-stage [Dockerfile](Dockerfile) in this repository. They differ only in how a Docker daemon is made available to the jobs the runner executes; the `gitea-runner` binary inside them is identical.
-
-| Tag | Build target | Base image | Docker daemon | Process supervisor | Runs as |
-| --- | --- | --- | --- | --- | --- |
-| `latest` (and `<version>`) | `basic` | `alpine` | none — uses an external daemon you provide | [`tini`](https://github.com/krallin/tini) | `root` |
-| `latest-dind` | `dind` | `docker:dind` | bundled, started inside the container | [`s6`](https://skarnet.org/software/s6/) | `root` (privileged) |
-| `latest-dind-rootless` | `dind-rootless` | `docker:dind-rootless` | bundled, started rootless inside the container | [`s6`](https://skarnet.org/software/s6/) | `rootless` (UID 1000) |
-
-#### `latest` — basic
-
-The default flavour ships only the runner on a minimal Alpine base. It contains **no Docker daemon of its own**: jobs that use `docker://` images need a daemon supplied from outside the container, typically by bind-mounting the host's socket:
-
-```bash
-docker run -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> \
-  -v /var/run/docker.sock:/var/run/docker.sock --name my_runner gitea/runner:latest
-```
-
-`tini` is the entrypoint (it reaps zombie processes), and it just runs [`scripts/run.sh`](scripts/run.sh), which registers the runner on first start and then execs `gitea-runner daemon`. This flavour does not need `--privileged`. The trade-off is that jobs share the host's daemon, so they can see other containers and images on that daemon.
-
-#### `latest-dind` — Docker-in-Docker
-
-This flavour is based on the official `docker:dind` image and bundles its own Docker daemon, so it needs no external socket — only the `--privileged` flag that Docker-in-Docker requires:
+The recommended Docker-in-Docker image runs its own Docker daemon for jobs. Jobs never get the host's Docker socket, which is equivalent to root access on the host.
 
 ```bash
 docker run --privileged -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> \
-  --name my_runner gitea/runner:latest-dind
+  -v "$PWD/data:/data" -v runner-docker:/var/lib/docker --name my_runner gitea/runner:nightly-dind
 ```
 
-Two processes have to run side by side here (the Docker daemon and the runner), so the entrypoint is the [`s6`](https://skarnet.org/software/s6/) supervision tree under [`scripts/s6`](scripts/s6) instead of `tini`. `s6` starts `dockerd`, and the runner service waits for the daemon to come up (`s6-svwait`) before launching [`run.sh`](scripts/run.sh). Each container has a private daemon isolated from the host's, at the cost of running privileged.
+The volumes keep the registration and the image cache across container recreation. The image reads more variables, such as `GITEA_RUNNER_LABELS` and `CONFIG_FILE`, see [scripts/run.sh](scripts/run.sh) and the [Docker example](examples/docker/README.md).
 
-#### `latest-dind-rootless` — rootless Docker-in-Docker
+#### Image flavours
 
-Same idea as `dind`, but built on `docker:dind-rootless` so the bundled daemon and the runner run as an unprivileged user (`rootless`, UID 1000) rather than `root`. `DOCKER_HOST` is preset to `unix:///run/user/1000/docker.sock` so the runner talks to the rootless daemon. This reduces the blast radius compared to the privileged `dind` flavour, but rootless Docker carries the usual rootless limitations (networking, cgroups, storage drivers, and some operations that need additional host configuration such as `/etc/subuid` / `/etc/subgid` mappings and unprivileged user-namespace support).
+| Tag | Docker daemon for jobs |
+| --- | --- |
+| `latest-dind` (recommended) | Bundled, needs `--privileged`. |
+| `latest-dind-rootless` | Bundled, runs as UID 1000 for stronger isolation. Needs `--privileged` and [rootless Docker](https://docs.docker.com/engine/security/rootless/) support on the host. Its image cache is in `/home/rootless/.local/share/docker`. |
+| `latest` | None. Mount the host's `/var/run/docker.sock`, or set `DOCKER_HOST`. |
 
-> **The UID is fixed at 1000.** It comes from the `rootless` user baked into the upstream `docker:dind-rootless` base image, and the bundled daemon always listens on `/run/user/1000/docker.sock` inside the container, so running this flavour as a different user (`--user 1001`) does not work. If you need the runner to talk to a *host* rootless daemon that runs under some other UID, use the `basic` flavour instead and bind-mount that daemon's socket (see [examples/vm/rootless-docker.md](examples/vm/rootless-docker.md)); pointing `DOCKER_HOST` at a host socket from inside `dind-rootless` will not work. Changing the UID otherwise means rebuilding the image from a base with a different `rootless` user.
+Versioned and `nightly` tags take the same suffixes, like `nightly-dind`. The images target Docker, not Podman.
 
-> **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.
+### Example deployments
 
-### Configuration
+See the [examples](examples) directory for more deployments, among them systemd, Kubernetes and VMs.
 
-The runner is configured with a YAML file. Generate a starting point (this matches what ships in the tree):
+## Configuration
+
+The runner reads an optional YAML file:
 
 ```bash
-./gitea-runner generate-config > config.yaml
+./gitea-runner config init             # write config.yaml, with no option set
+./gitea-runner config generate | less  # read what the options do
+./gitea-runner -c config.yaml daemon   # -c also works on register and cache-server
 ```
 
-Pass it with `-c` / `--config` on any command that loads configuration (`register`, `daemon`, `cache-server`):
+`config generate` prints [config.example.yaml](internal/pkg/config/config.example.yaml), which documents every option. Copy the lines you need into your file and uncomment them.
+
+### Editing a config file
+
+`config` edits a file in place and keeps its comments, which suits provisioning scripts:
 
 ```bash
-./gitea-runner -c config.yaml register
-./gitea-runner -c config.yaml daemon
-./gitea-runner -c config.yaml cache-server
+./gitea-runner config set runner.capacity 4
+./gitea-runner config set runner.envs.MY_VAR value
+./gitea-runner config add runner.labels 'ubuntu:docker://node:22'
+./gitea-runner config remove runner.labels 'ubuntu:docker://node:22'
+./gitea-runner config get runner.labels
 ```
 
-Every option is described in [config.example.yaml](internal/pkg/config/config.example.yaml) (the same content `generate-config` prints).
+Keys are dotted YAML paths. Unknown keys and invalid values are refused without touching the file. Without `-c`, it uses `config.yaml` from the working directory, then from the binary's directory.
 
-#### Without a config file
+### Environment variables
 
-If you omit `-c`, built-in defaults apply (same as an empty YAML document).
+Config values can read the runner's environment as `${NAME}`, for example `capacity: ${RUNNER_CAPACITY}`. An unset variable fails the load, and `$${NAME}` stays a literal `${NAME}`.
 
-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.
+The override variables of earlier releases, such as `GITEA_RUNNER_CAPACITY`, are gone. Set those options in the file instead.
 
 ### 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.
+Labels decide which jobs a runner accepts and how it runs them. A job's `runs-on` is matched against the label names, and the first match picks where it runs.
 
-A label is written as:
+A label is written as `<name>[:<schema>[:<args>]]`, with one of these schemas:
 
-```text
-<name>[:<schema>[:<args>]]
-```
+- `docker://<image>` runs the job in a container of `<image>`.
+- `kubernetes://<image>` runs it as a Kubernetes pod, see [docs/kubernetes.md](docs/kubernetes.md).
+- `host`, the default, runs its steps directly on the runner's machine.
 
-| Part | Meaning |
-| --- | --- |
-| `name` | The name a workflow refers to in `runs-on`, e.g. `ubuntu-latest`. |
-| `schema` | Either `docker` or `host`. Defaults to `host` when omitted. |
-| `args` | Only used by the `docker` schema: the image to run the job in. |
-
-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
+With these labels, `runs-on: ubuntu-latest` runs in a container and `runs-on: macos` on the host:
 
 ```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.
+[gitea/runner-images](https://gitea.com/gitea/runner-images) has suitable images. Jobs matching no label run in `runner.default_image`, or on the host when docker is unavailable.
 
-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.
+Host jobs still need a Docker daemon for Docker actions and `docker://` steps. Windows hosts do not support those, as on GitHub. On Windows, a step's background processes end with the job unless it opts out, see [host mode](docs/host-mode.md).
 
 #### 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.
-
-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:
+Labels are set at registration, with `--labels` or the prompt. To change them later, use one of these, the leftmost set one wins:
 
 ```
---labels / GITEA_RUNNER_LABELS   >   runner.labels in the config file   >   labels in the .runner file
+daemon --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.
+Changed labels are saved to the `.runner` file and sent to Gitea on startup. When `runner.labels` is set, `register` uses it and ignores `--labels`.
 
-> **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.
+### Tool cache
 
-#### Proxy
+Setup actions like `setup-go` install tools into `RUNNER_TOOL_CACHE`. `runner.tool_cache_mode` selects what backs it:
 
-Set these variables in the runner's environment, with systemd `Environment=`, `docker run -e`, or Kubernetes `env:`:
+| Mode | Tool cache |
+| --- | --- |
+| `none` (default) | Provided by the job image. Versions it lacks are downloaded in every job. |
+| `shared` | One volume for all jobs. Only safe with `runner.capacity: 1`. |
+
+To ship tools in a job image, install them to `/opt/hostedtoolcache/<tool>/<version>/<arch>` with an empty `<arch>.complete` file next to it, as the `-full` [runner images](https://gitea.com/gitea/runner-images) do:
+
+```dockerfile
+RUN GO=$(curl -fsSL 'https://go.dev/dl/?mode=json' | grep -oP '"version": "\Kgo1\.26\.[0-9]*' | head -1); \
+  DIR="/opt/hostedtoolcache/go/${GO#go}/x64" && \
+  mkdir -p "$(dirname "$DIR")" && \
+  curl -fsSL "https://dl.google.com/go/${GO}.linux-amd64.tar.gz" | tar -xz -C /tmp && \
+  mv /tmp/go "$DIR" && \
+  touch "${DIR}.complete"
+```
+
+### Proxy
+
+Set the proxy in the runner's environment, for example with systemd `Environment=` or `docker run -e`:
 
 ```sh
 http_proxy=http://proxy.example:3128
@@ -219,108 +206,136 @@ 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.
+The runner uses it and passes it on to jobs. Jobs always reach the cache server, `localhost`, their service containers and a `tcp://` Docker daemon directly. Add Gitea to `no_proxy` if it should be reached directly too.
 
-These hosts are added to `no_proxy` for jobs, so they are always reached directly:
+To change the proxy for jobs, use `runner.envs`, a step's `env:` or `$GITHUB_ENV`. Workflow and job level `env:` have no effect on it.
 
-- the cache server
-- `localhost`, `127.0.0.1` and `::1`
-- the job's service containers
-- the Docker daemon, when it is reached over `tcp://`
+The Docker daemon pulls images with its own proxy settings. The `dind` images pass the variables above to it, for other daemons see [the Docker documentation](https://docs.docker.com/engine/daemon/proxy/).
 
-Gitea is not added. Add it to `no_proxy` yourself if it should be reached directly.
+A password in the proxy URL is hidden in logs, but every step can read it.
 
-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.
+## Jobs
 
-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.
+### Service containers
 
-Dockerfile actions are built with these variables as build arguments, so their `RUN` steps can reach the network.
+When a service declares a healthcheck, in its image or `options`, the job waits for it to become healthy:
 
-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.
+```yaml
+services:
+  postgres:
+    image: postgres:18
+    options: >-
+      --health-cmd pg_isready
+      --health-interval 5s
+      --health-retries 10
+```
 
-#### Caching (`actions/cache`)
+A service that turns unhealthy, or is not healthy within `container.service_ready_timeout`, fails the job. Steps reach a service by its id and port, like `psql -h postgres -p 5432`.
 
-Each runner starts its own cache server automatically. Cache entries are local to that runner — runners do not share a cache by default.
+Unlike GitHub, jobs running on the host start no services. Give them a `container:` to use services.
 
-**Cache service v2**
+### Docker from a job (`GITEA_DOCKER_WORKSPACE`)
 
-`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:
+Containers a job starts can bind-mount the workspace by its path, like `docker run -v "$PWD:/src"`. Where the Docker daemon sees another path, for example a remote `DOCKER_HOST`, prefix the bind with `GITEA_DOCKER_WORKSPACE`:
+
+```yaml
+volumes:
+  - ${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data
+```
+
+In most Linux container jobs, the containers, networks and volumes a job creates are removed when it ends, `docker compose` services included. Set `container.sweep: false` if jobs deploy services to the runner's Docker daemon.
+
+### Built-in actions (`uses: builtin:<name>`)
+
+`uses: builtin:checkout` checks out a repository without downloading `actions/checkout` or needing Node in the job image, see [docs/builtin-actions.md](docs/builtin-actions.md).
+
+### Caching (`actions/cache`)
+
+Each runner runs its own cache server. As on GitHub, a job restores caches of its own ref, its pull request's base branch and the default branch.
+
+#### Sharing a cache between runners
+
+Run one `gitea-runner cache-server` and point every runner at it with the same secret, for example from `openssl rand -hex 32`:
+
+```yaml
+# cache-server.yaml
+cache:
+  dir: /data/actcache
+  port: 8088
+  external_secret: "<secret>" # or external_secret_file: /path/to/secret
+```
+
+```bash
+gitea-runner -c cache-server.yaml cache-server
+```
+
+```yaml
+# each runner's config
+cache:
+  external_server: "http://<cache-server-host>:8088/"
+  external_secret: "<secret>"
+```
+
+Runners can also share one `cache.dir` on a file system with working file locks, at the cost of slower requests.
+
+#### Storing the cache in an S3-compatible bucket
+
+Runners can share a cache in an S3-compatible bucket, such as AWS S3, MinIO or RustFS, without a cache server:
 
 ```yaml
 cache:
-  v2: false
+  s3:
+    endpoint: "http://minio:9000"
+    region: "us-east-1"
+    bucket: "runner-cache"
+    prefix: "gitea-runner-cache"
+    path_style: true
+    access_key_file: "/run/secrets/cache-s3-access-key"
+    secret_key_file: "/run/secrets/cache-s3-secret-key"
 ```
 
-Those actions refuse any host they do not take for GitHub. Rather than misreport the server URL, the runner edits that check out of the action's own bundle 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.
+Eviction does not apply to the bucket. Add lifecycle rules that expire old caches and abort incomplete multipart uploads.
 
-**Shared cache across multiple runners**
+#### Eviction
 
-Run one dedicated `gitea-runner cache-server` that all runners point at.
+Entries unused for `cache.retention` (default `168h`) are removed. A repository over `cache.repo_size_limit` (default `10GB`) loses its least recently used entries. See [config.example.yaml](internal/pkg/config/config.example.yaml) for more limits.
 
-1. Create a config file for the cache server host:
+#### Cache service v2
 
-   ```yaml
-   cache:
-     dir: /data/actcache
-     port: 8088
-     external_secret: "replace-with-a-strong-random-secret"
-     # external_secret_file: /path/to/secret # secret can also be passed via a file
-   ```
+The runner serves the cache service v2 API used by current `actions/cache` releases. It patches them to use it on Gitea, which also makes the stock `actions/upload-artifact` and `actions/download-artifact` v4 work. Artifact calls then go through the cache server, so jobs must be able to reach it.
 
-2. Start the server:
+### Job hooks (`runner.hooks.job_started`, `runner.hooks.job_completed`)
 
-   ```bash
-   gitea-runner -c cache-server-config.yaml cache-server
-   ```
+Hook scripts run where the job's steps run, before the first step and after the last. They match GitHub's `ACTIONS_RUNNER_HOOK_JOB_STARTED` and `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`.
 
-3. On every runner:
+Use them for per-job setup no workflow should carry, like registry logins or masking runner-wide secrets. They block the job, and a non-zero exit fails it. See [docs/job-hooks.md](docs/job-hooks.md).
 
-   ```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
-   ```
+### Secret masking
 
-Alternatively, mount the same NFS/CIFS share on every runner and point `cache.dir` at it — simpler, but with weaker isolation between repositories.
+Secrets and `::add-mask::` values are hidden in job logs, [local job logs](#local-job-logs-logjobdir), job summaries and container names. As on GitHub, a job output containing one is dropped with a warning.
 
-**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.
+## Operation
 
-Flags `--dir`, `--host`, and `--port` on `cache-server` override the corresponding `cache.*` YAML keys; all other settings, including `external_secret`, require the config file.
+### Idle cleanup
 
-#### Official Docker image
+While idle, the runner removes leftovers of earlier jobs every `runner.idle_cleanup_interval` (default `10m`):
 
-Besides `GITEA_INSTANCE_URL` and `GITEA_RUNNER_REGISTRATION_TOKEN`, the image entrypoint supports optional variables such as `CONFIG_FILE` (passed through as `-c`), `GITEA_RUNNER_LABELS`, `GITEA_RUNNER_EPHEMERAL`, `GITEA_RUNNER_ONCE`, `GITEA_RUNNER_NAME`, `GITEA_MAX_REG_ATTEMPTS`, `RUNNER_STATE_FILE`, and `GITEA_RUNNER_REGISTRATION_TOKEN_FILE`. See [scripts/run.sh](scripts/run.sh) for exact behavior.
+- Workspaces older than `runner.workdir_cleanup_age` (default `24h`), when `container.bind_workdir` is on. This assumes no other runner shares `container.workdir_parent`.
+- Unused Docker networks and volumes of jobs the runner did not tear down.
+- Kubernetes job pods older than `runner.workdir_cleanup_age`, with their Secrets.
 
-For a fuller container-oriented walkthrough, see [examples/docker](examples/docker/README.md).
+Set either option to `0` to turn cleanup off.
 
-While the runner is idle it cleans up after earlier jobs:
-- when `container.bind_workdir` is enabled, stale task workspace directories older than `runner.workdir_cleanup_age` are removed (default: `24h`; set `0` to disable)
-- only purely numeric subdirectories under `container.workdir_parent` are treated as task workspaces and may be removed
-- cleanup assumes `container.workdir_parent` is not shared across multiple runners
-- on runners that use docker, per-job networks left behind by jobs the runner did not live to tear down are removed, identified by the `com.gitea.runner.uuid` label carrying this runner's uuid
-- cleanup runs every `runner.idle_cleanup_interval` (default: `10m`; set `0` to disable), and setting either knob to `0` disables all of the above
+### Post-task script (`runner.post_task_script`)
 
-#### Post-task script (`runner.post_task_script`)
+A host script that runs after each task's cleanup, for housekeeping like Docker pruning. The runner takes no new jobs until it exits or hits `runner.post_task_script_timeout` (default `5m`). Its output goes to the runner log.
 
-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.
+On Windows, use an `.exe`, `.bat` or `.cmd` file, PowerShell scripts are not supported. See [docs/post-task-script.md](docs/post-task-script.md).
 
-**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.
+### Local job logs (`log.job.dir`)
 
-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.
+Set `log.job.dir` to keep a copy of every task's log, masked as in Gitea, with the job's result on the last line. Copies are kept for `log.job.retention` (default `168h`), so keep it above `runner.timeout`. Only the runner's user can read them.
 
-See **[docs/post-task-script.md](docs/post-task-script.md)** for lifecycle details, environment variables, timeout interaction, and platform notes.
+### OpenTelemetry (`OTEL_*`)
 
-#### Job hooks (`runner.hooks.job_started`, `runner.hooks.job_completed`)
-
-Optional scripts that run **inside the job environment** (the job container, or the host in host mode), before the job's first step and after its last one. They are the equivalent of GitHub's `ACTIONS_RUNNER_HOOK_JOB_STARTED` / `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`, which are read when the settings are unset.
-
-Because they run where the steps run and see the job's environment, they are the place for per-job setup no workflow should have to carry: registry logins, mirror configuration, or masking runner-wide secrets with `::add-mask::`. Their output is part of the job log and is scanned for workflow commands, and they can export to the job through `$GITHUB_ENV` and `$GITHUB_PATH`.
-
-Both hooks are synchronous and block the job while they run. Either one exiting non-zero fails the job, and there is no per-hook timeout.
-
-See **[docs/job-hooks.md](docs/job-hooks.md)** for the execution order, environment, and platform notes.
-
-### Example Deployments
-
-Check out the [examples](examples) directory for sample deployment types.
+Set `OTEL_EXPORTER_OTLP_ENDPOINT` in the runner's environment to send job traces and runner metrics to an OpenTelemetry collector. See [docs/telemetry.md](docs/telemetry.md).

act/artifactcache/doc.go

@@ -6,7 +6,5 @@
 //
 // Inspired by https://github.com/sp-ricard-valverde/github-act-cache-server
 //
-// TODO: Authorization
-// TODO: Restrictions for accessing a cache, see https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache
 // TODO: Force deleting cache entries, see https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#force-deleting-cache-entries
 package artifactcache

act/artifactcache/handler_v2.go

@@ -5,7 +5,8 @@ package artifactcache
 
 import (
 	"cmp"
-	"encoding/json"
+	"encoding/json/jsontext"
+	"encoding/json/v2"
 	"encoding/xml"
 	"errors"
 	"fmt"
@@ -14,8 +15,6 @@ import (
 	"strconv"
 	"strings"
 	"time"
-
-	"github.com/julienschmidt/httprouter"
 )
 
 // The cache service v2 API. A client on this version talks twirp to
@@ -23,6 +22,9 @@ import (
 // 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.
+//
+// Responses carry the proto field names, which is what Gitea's own results API emits and the only
+// spelling the Go clients parse. The JavaScript toolkit accepts either.
 const (
 	cacheServiceV2Path = "/twirp/github.actions.results.api.v1.CacheService"
 
@@ -35,24 +37,25 @@ const (
 
 	blobUploadURLTTL = time.Hour
 
-	// twirpInternal is the only error code that is not the client's fault.
-	twirpInternal = "internal"
+	twirpInternal        = "internal"
+	twirpUnavailable     = "unavailable"
+	twirpUnauthenticated = "unauthenticated"
 )
 
-func (h *Handler) registerV2Routes(router *httprouter.Router) {
-	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))
+func (h *Handler) registerV2Routes(router *http.ServeMux) {
+	router.HandleFunc("POST "+cacheServiceV2Path+"/CreateCacheEntry", h.bearerAuth(h.v2CreateCacheEntry))
+	router.HandleFunc("POST "+cacheServiceV2Path+"/FinalizeCacheEntryUpload", h.bearerAuth(h.v2FinalizeCacheEntryUpload))
+	router.HandleFunc("POST "+cacheServiceV2Path+"/GetCacheEntryDownloadURL", h.bearerAuth(h.v2GetCacheEntryDownloadURL))
+	router.HandleFunc("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) {
+func (h *Handler) v2CreateCacheEntry(w http.ResponseWriter, r *http.Request) {
 	cred := credFromContext(r.Context())
 	req, err := decodeTwirpRequest[v2CreateRequest](r)
 	if err != nil {
-		h.twirpError(w, r, "malformed_request", err)
+		h.twirpError(w, r, "malformed", err)
 		return
 	}
 	if req.Key == "" || req.Version == "" {
@@ -70,111 +73,142 @@ func (h *Handler) v2CreateCacheEntry(w http.ResponseWriter, r *http.Request, _ h
 	// 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 {
+	if existing, err := findExactCache(db, cred, req.Key, req.Version, true); err != nil {
 		h.twirpError(w, r, twirpInternal, err)
 		return
 	} else if existing != nil {
+		h.touch(db, existing) // the client skips the upload, so this is the only sign the entry is still in use
 		h.twirpNotOK(w, r)
 		return
 	}
 
-	now := time.Now().Unix()
+	// A second live reservation is finalized by whichever job calls last, against the other's upload.
+	owner := hashedToken(bearerToken(r))
+	if pending, err := findExactCache(db, cred, req.Key, req.Version, false); err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	} else if pending != nil && pending.UsedAt > time.Now().Add(-uploadStallTimeout).Unix() {
+		if pending.Owner != owner {
+			h.twirpNotOK(w, r)
+			return
+		}
+		h.touch(db, pending)                                // still uploading, so it must not go stale under the sweep
+		h.responseJSON(w, r, http.StatusOK, map[string]any{ // this job retrying its own reservation
+			"ok":                true,
+			"signed_upload_url": h.signedURL(cred, blobPath, blobUploadPurpose, pending.ID, time.Now().Add(blobUploadURLTTL)),
+		})
+		return
+	}
+
+	now := time.Now()
 	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,
+		Repo:           cred.Repo,
+		Ref:            cred.Ref,
+		Key:            req.Key,
+		Version:        req.Version,
+		Owner:          owner,
+		Size:           -1, // the size is only known at finalize time
+		CreatedAt:      now.Unix(),
+		CreatedAtNanos: now.Nanosecond(),
+		UsedAt:         now.Unix(),
 	}
-	if err := insertCache(db, cache); err != nil {
+	if err := h.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,
+		"signed_upload_url": h.signedURL(cred, blobPath, blobUploadPurpose, cache.ID, time.Now().Add(blobUploadURLTTL)),
+	})
+}
+
+func (h *Handler) v2FinalizeCacheEntryUpload(w http.ResponseWriter, r *http.Request) {
+	cred := credFromContext(r.Context())
+	req, err := decodeTwirpRequest[v2FinalizeRequest](r)
+	if err != nil {
+		h.twirpError(w, r, "malformed", err)
+		return
+	}
+
+	db, err := h.openDB()
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	defer db.Close()
+
+	cache, err := findExactCache(db, cred, req.Key, req.Version, false)
+	if err == nil && cache != nil && cache.Owner != hashedToken(bearerToken(r)) {
+		cache = nil // not the reservation this job made, so not this job's to commit
+	}
+	if err == nil && cache == nil {
+		// A retry whose first response was lost finds the entry already committed.
+		cache, err = findExactCache(db, cred, req.Key, req.Version, true)
+	}
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	if cache == nil {
+		h.twirpNotOK(w, r)
+		return
+	}
+
+	if !cache.Complete {
+		db.Close() // commitCache needs the store closed
+		cache.Size = int64(cmp.Or(req.SizeBytes, req.SizeBytesCamel))
+		if err := h.commitCache(cache); err != nil {
+			h.logger.Errorf("finalize cache %d (%s): %v", cache.ID, cache.Key, err)
+			h.twirpNotOK(w, r)
+			return
+		}
+	}
+
+	h.responseJSON(w, r, http.StatusOK, map[string]any{
+		"ok": true,
+		// int64 fields travel as strings in the proto JSON mapping.
+		"entry_id": strconv.FormatUint(cache.ID, 10),
+	})
+}
+
+func (h *Handler) v2GetCacheEntryDownloadURL(w http.ResponseWriter, r *http.Request) {
+	cred := credFromContext(r.Context())
+	req, err := decodeTwirpRequest[v2DownloadRequest](r)
+	if err != nil {
+		h.twirpError(w, r, "malformed", 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, 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,
+		"signed_download_url": h.signedArtifactURL(cred, cache.ID, time.Now().Add(artifactURLTTL)),
+		"matched_key":         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)
+func (h *Handler) v2UploadBlob(w http.ResponseWriter, r *http.Request) {
+	id, err := strconv.ParseUint(r.PathValue("id"), 10, 64)
 	if err != nil {
 		h.responseJSON(w, r, http.StatusBadRequest, err)
 		return
@@ -209,6 +243,8 @@ func (h *Handler) v2UploadBlob(w http.ResponseWriter, r *http.Request, params ht
 		return
 	}
 
+	// The Azure SDK client dereferences this without checking, so its absence panics the caller.
+	w.Header().Set("x-ms-request-id", strconv.FormatInt(time.Now().UnixNano(), 10))
 	w.WriteHeader(http.StatusCreated)
 }
 
@@ -223,8 +259,13 @@ func (h *Handler) twirpNotOK(w http.ResponseWriter, r *http.Request) {
 func (h *Handler) twirpError(w http.ResponseWriter, r *http.Request, code string, err error) {
 	h.logger.Debugf("%s %s: %v", r.Method, r.URL.Path, err)
 	status := http.StatusBadRequest
-	if code == twirpInternal {
+	switch code {
+	case twirpInternal:
 		status = http.StatusInternalServerError
+	case twirpUnavailable:
+		status = http.StatusServiceUnavailable
+	case twirpUnauthenticated:
+		status = http.StatusUnauthorized
 	}
 	h.responseJSON(w, r, status, map[string]any{"code": code, "msg": err.Error()})
 }
@@ -239,10 +280,10 @@ type (
 	}
 
 	v2FinalizeRequest struct {
-		Key            string      `json:"key"`
-		Version        string      `json:"version"`
-		SizeBytes      json.Number `json:"size_bytes"`
-		SizeBytesCamel json.Number `json:"sizeBytes"`
+		Key            string     `json:"key"`
+		Version        string     `json:"version"`
+		SizeBytes      twirpInt64 `json:"size_bytes"`
+		SizeBytesCamel twirpInt64 `json:"sizeBytes"`
 	}
 
 	v2DownloadRequest struct {
@@ -253,6 +294,31 @@ type (
 	}
 )
 
+// twirpInt64 accepts its value as the JSON string the mapping prescribes or as a bare number.
+type twirpInt64 int64
+
+func (n *twirpInt64) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
+	val, err := dec.ReadValue()
+	if err != nil {
+		return err
+	}
+	digits := []byte(val)
+	switch val.Kind() {
+	case 'n': // absent, keep the zero value
+		return nil
+	case '"':
+		if digits, err = jsontext.AppendUnquote(nil, val); err != nil {
+			return err
+		}
+	}
+	parsed, err := strconv.ParseInt(string(digits), 10, 64)
+	if err != nil {
+		return err
+	}
+	*n = twirpInt64(parsed)
+	return nil
+}
+
 func (d v2DownloadRequest) keys() []string {
 	restoreKeys := d.RestoreKeys
 	if len(restoreKeys) == 0 {
@@ -263,6 +329,6 @@ func (d v2DownloadRequest) keys() []string {
 
 func decodeTwirpRequest[T any](r *http.Request) (T, error) {
 	var req T
-	err := json.NewDecoder(io.LimitReader(r.Body, 1<<20)).Decode(&req)
+	err := json.UnmarshalRead(io.LimitReader(r.Body, 1<<20), &req)
 	return req, err
 }

act/artifactcache/handler_v2_test.go

@@ -6,20 +6,19 @@ package artifactcache
 import (
 	"bytes"
 	"encoding/base64"
-	"encoding/json"
+	"encoding/json/v2"
 	"fmt"
 	"io"
 	"net/http"
-	"path/filepath"
+	"net/url"
 	"strconv"
+	"strings"
 	"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()
 
@@ -32,11 +31,10 @@ func v2Call(t *testing.T, handler *Handler, client *http.Client, method string,
 	require.Equal(t, http.StatusOK, resp.StatusCode)
 
 	got := map[string]any{}
-	require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+	require.NoError(t, json.UnmarshalRead(resp.Body, &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()
 
@@ -45,6 +43,9 @@ func putBlob(t *testing.T, url string, content []byte) int {
 	resp, err := http.DefaultClient.Do(req)
 	require.NoError(t, err)
 	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusCreated {
+		require.NotEmpty(t, resp.Header.Get("x-ms-request-id"))
+	}
 	return resp.StatusCode
 }
 
@@ -61,24 +62,12 @@ func getURL(t *testing.T, url string) []byte {
 	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)
+	uploadURL, _ = created["signed_upload_url"].(string)
 	require.NotEmpty(t, uploadURL)
 	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL, content))
 
@@ -88,11 +77,9 @@ func saveV2(t *testing.T, handler *Handler, key, version string, content []byte)
 	}), 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)
+	t.Parallel()
+	handler := newTestHandler(t, Policy{})
 	content := []byte("the cached archive")
 
 	unsigned := fmt.Sprintf("%s%s/1", handler.ExternalURL(), blobPath)
@@ -100,31 +87,28 @@ func TestCacheServiceV2RoundTrip(t *testing.T) {
 
 	finalized, uploadURL := saveV2(t, handler, "deps-v1", "abc123", content)
 	require.Equal(t, true, finalized["ok"])
-	assert.NotEmpty(t, finalized["entryId"])
+	assert.NotEmpty(t, finalized["entry_id"])
 
-	// 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
+	resp, err := http.Get(uploadURL)
 	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)
+	assert.Equal(t, "deps-v1", got["matched_key"])
+	downloadURL, _ := got["signed_download_url"].(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)
+	t.Parallel()
+	handler := newTestHandler(t, Policy{})
 
 	created := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "blocks", "version": "v1"})
-	uploadURL, _ := created["signedUploadUrl"].(string)
+	uploadURL, _ := created["signed_upload_url"].(string)
 	require.NotEmpty(t, uploadURL)
 
 	blocks := map[string][]byte{}
@@ -134,7 +118,6 @@ func TestCacheServiceV2BlockUpload(t *testing.T) {
 		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]))
 	}
@@ -146,6 +129,17 @@ func TestCacheServiceV2BlockUpload(t *testing.T) {
 	}
 	list.WriteString(`</BlockList>`)
 	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL+"&comp=blocklist", list.Bytes()))
+	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL+"&comp=blocklist", list.Bytes()),
+		"a client that lost the first answer retries the list it already sent")
+
+	var reordered bytes.Buffer
+	reordered.WriteString(`<?xml version="1.0" encoding="utf-8"?><BlockList>`)
+	for _, blockID := range []string{order[1], order[0], order[2]} {
+		fmt.Fprintf(&reordered, "<Latest>%s</Latest>", blockID)
+	}
+	reordered.WriteString(`</BlockList>`)
+	assert.Equal(t, http.StatusInternalServerError, putBlob(t, uploadURL+"&comp=blocklist", reordered.Bytes()),
+		"the blocks are already assembled, so a different order would silently disagree with them")
 
 	finalized := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
 		"key": "blocks", "version": "v1", "size_bytes": len("hello world!"),
@@ -154,11 +148,12 @@ func TestCacheServiceV2BlockUpload(t *testing.T) {
 
 	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))))
+	assert.Equal(t, "hello world!", string(getURL(t, got["signed_download_url"].(string))))
 }
 
 func TestCacheServiceV2Lookups(t *testing.T) {
-	handler := startTestHandler(t)
+	t.Parallel()
+	handler := newTestHandler(t, Policy{})
 	saved, _ := saveV2(t, handler, "deps-abc", "v1", []byte("x"))
 	require.Equal(t, true, saved["ok"])
 
@@ -167,15 +162,13 @@ func TestCacheServiceV2Lookups(t *testing.T) {
 		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"])
+			assert.Equal(t, "deps-abc", got["matched_key"])
 		})
 	}
 
@@ -184,13 +177,22 @@ func TestCacheServiceV2Lookups(t *testing.T) {
 		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"])
+		assert.NotEmpty(t, reserved["signed_upload_url"])
+	})
+
+	t.Run("a proxied job is handed the address its runner registered", func(t *testing.T) {
+		const proxy = "https://cache.example.invalid"
+		handler.RegisterJob("proxied", JobCredential{Repo: testRepo, PublicURL: proxy + "/"})
+		client := &http.Client{Transport: &bearerTransport{token: "proxied"}}
+
+		created := v2Call(t, handler, client, "CreateCacheEntry", map[string]any{"key": "proxied-key", "version": "v1"})
+		assert.True(t, strings.HasPrefix(created["signed_upload_url"].(string), proxy+blobPath+"/"))
+
+		got := v2Call(t, handler, client, "GetCacheEntryDownloadURL", map[string]any{"key": "deps-abc", "version": "v1"})
+		assert.True(t, strings.HasPrefix(got["signed_download_url"].(string), proxy+apiPath+"/artifacts/"))
 	})
 
 	t.Run("finalizing without a reservation is not ok", func(t *testing.T) {
@@ -200,10 +202,9 @@ func TestCacheServiceV2Lookups(t *testing.T) {
 		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")))
+		require.Equal(t, http.StatusCreated, putBlob(t, created["signed_upload_url"].(string), []byte("four")))
 
 		got := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
 			"key": "wrong-size", "version": "v1", "size_bytes": 99,
@@ -211,8 +212,6 @@ func TestCacheServiceV2Lookups(t *testing.T) {
 		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)
@@ -220,17 +219,126 @@ func TestCacheServiceV2Lookups(t *testing.T) {
 		require.Equal(t, http.StatusOK, resp.StatusCode)
 
 		got := map[string]any{}
-		require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+		require.NoError(t, json.UnmarshalRead(resp.Body, &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")
+		handler.RegisterJob("other-runtime-token", JobCredential{Repo: "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"])
 	})
+
+	t.Run("each ref saves and restores its own entry for the same key", func(t *testing.T) {
+		clients := map[string]*http.Client{"x": testClient}
+		for _, ref := range []string{"y", "z"} {
+			handler.RegisterJob(ref, JobCredential{Repo: testRepo, Ref: "refs/pull/" + ref + "/head"})
+			clients[ref] = &http.Client{Transport: &bearerTransport{token: ref}}
+			created := v2Call(t, handler, clients[ref], "CreateCacheEntry", map[string]any{"key": "deps-abc", "version": "v1"})
+			require.Equal(t, true, created["ok"])
+			require.Equal(t, http.StatusCreated, putBlob(t, created["signed_upload_url"].(string), []byte(ref)))
+		}
+		for _, ref := range []string{"y", "z"} {
+			require.Equal(t, true, v2Call(t, handler, clients[ref], "FinalizeCacheEntryUpload", map[string]any{"key": "deps-abc", "version": "v1", "size_bytes": 1})["ok"])
+		}
+		for content, client := range clients {
+			got := v2Call(t, handler, client, "GetCacheEntryDownloadURL", map[string]any{"key": "deps-abc", "version": "v1"})
+			assert.Equal(t, content, string(getURL(t, got["signed_download_url"].(string))))
+		}
+	})
+}
+
+func TestCacheServiceV2RefusalsAreTwirp(t *testing.T) {
+	t.Parallel()
+	handler := newTestHandler(t, Policy{})
+
+	tests := []struct {
+		name   string
+		token  string
+		body   string
+		status int
+		code   string
+	}{
+		{"no bearer at all", "", `{"key":"k","version":"v"}`, http.StatusUnauthorized, twirpUnauthenticated},
+		{"a bearer nobody registered", "not-a-job", `{"key":"k","version":"v"}`, http.StatusUnauthorized, twirpUnauthenticated},
+		{"a body that is not the request", testToken, `{`, http.StatusBadRequest, "malformed"},
+		{"a request missing its key", testToken, `{"version":"v"}`, http.StatusBadRequest, "invalid_argument"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req, err := http.NewRequestWithContext(t.Context(), http.MethodPost,
+				handler.ExternalURL()+cacheServiceV2Path+"/CreateCacheEntry", strings.NewReader(tt.body))
+			require.NoError(t, err)
+			if tt.token != "" {
+				req.Header.Set("Authorization", "Bearer "+tt.token)
+			}
+			resp, err := http.DefaultClient.Do(req)
+			require.NoError(t, err)
+			defer resp.Body.Close()
+
+			require.Equal(t, tt.status, resp.StatusCode)
+			got := map[string]string{}
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
+			assert.Equal(t, tt.code, got["code"])
+			assert.NotEmpty(t, got["msg"])
+		})
+	}
+}
+
+func TestCacheServiceV2ConcurrentSaveAndRetries(t *testing.T) {
+	t.Parallel()
+	handler := newTestHandler(t, Policy{})
+	content := []byte("the cached archive")
+
+	const otherJob = "another-jobs-token"
+	defer handler.RegisterJob(otherJob, JobCredential{Repo: testRepo})()
+	reserve := func(client *http.Client) map[string]any {
+		return v2Call(t, handler, client, "CreateCacheEntry", map[string]any{"key": "shared", "version": "v1"})
+	}
+	first := reserve(testClient)
+	require.Equal(t, true, first["ok"])
+	retry := reserve(testClient)
+	assert.Equal(t, true, retry["ok"], "a job retrying its own reservation is not a conflict")
+	entryOf := func(reserved map[string]any) string {
+		parsed, err := url.Parse(reserved["signed_upload_url"].(string))
+		require.NoError(t, err)
+		return parsed.Path
+	}
+	assert.Equal(t, entryOf(first), entryOf(retry), "the same reservation, however freshly its URL is signed")
+	assert.Equal(t, false, reserve(&http.Client{Transport: &bearerTransport{token: otherJob}})["ok"],
+		"another job's reservation would be finalized against the first upload")
+
+	otherClient := &http.Client{Transport: &bearerTransport{token: otherJob}}
+	reserved := v2Call(t, handler, otherClient, "CreateCacheEntry", map[string]any{"key": "owned", "version": "v1"})
+	require.Equal(t, true, reserved["ok"])
+	require.Equal(t, http.StatusCreated, putBlob(t, reserved["signed_upload_url"].(string), content))
+	assert.Equal(t, false, v2Call(t, handler, testClient, "FinalizeCacheEntryUpload",
+		map[string]any{"key": "owned", "version": "v1", "size_bytes": strconv.Itoa(len(content))})["ok"],
+		"another job's upload is not this job's to finalize")
+
+	base := handler.ExternalURL() + apiPath
+	madeByV1 := reserveCache(t, testClient, base, "v1-made", "v1", int64(len(content)))
+	upload, err := http.NewRequestWithContext(t.Context(), http.MethodPatch,
+		fmt.Sprintf("%s/caches/%d", base, madeByV1), bytes.NewReader(content))
+	require.NoError(t, err)
+	upload.Header.Set("Content-Range", fmt.Sprintf("bytes 0-%d/*", len(content)-1))
+	resp, err := testClient.Do(upload)
+	require.NoError(t, err)
+	resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	assert.Equal(t, false, v2Call(t, handler, testClient, "FinalizeCacheEntryUpload",
+		map[string]any{"key": "v1-made", "version": "v1", "size_bytes": strconv.Itoa(len(content))})["ok"],
+		"a reservation this job did not make through v2 is not its to commit")
+
+	finalized, _ := saveV2(t, handler, "deps", "v1", content)
+	require.Equal(t, true, finalized["ok"])
+	again := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+		"key": "deps", "version": "v1", "size_bytes": strconv.Itoa(len(content)),
+	})
+	assert.Equal(t, true, again["ok"], "a retry whose first answer was lost must not report a failed save")
+	assert.Equal(t, finalized["entry_id"], again["entry_id"])
 }

act/artifactcache/model.go

@@ -4,36 +4,28 @@
 
 package artifactcache
 
+import "time"
+
 type Request struct {
 	Key     string `json:"key" `
 	Version string `json:"version"`
 	Size    int64  `json:"cacheSize"`
 }
 
-func (c *Request) ToCache() *Cache {
-	if c == nil {
-		return nil
-	}
-	ret := &Cache{
-		Key:     c.Key,
-		Version: c.Version,
-		Size:    c.Size,
-	}
-	if c.Size == 0 {
-		// So the request comes from old versions of actions, like `actions/cache@v2`.
-		// It doesn't send cache size. Set it to -1 to indicate that.
-		ret.Size = -1
-	}
-	return ret
+type Cache struct {
+	ID             uint64 `json:"id"`
+	Repo           string `json:"repo"`
+	Ref            string `json:"ref,omitzero"`
+	Key            string `json:"key"`
+	Version        string `json:"version"`
+	Size           int64  `json:"cacheSize"`
+	Owner          string `json:"owner"` // hashed bearer, so a job's own retry is not another job's reservation
+	Complete       bool   `json:"complete"`
+	UsedAt         int64  `json:"usedAt"`
+	CreatedAt      int64  `json:"createdAt"`
+	CreatedAtNanos int    `json:"createdAtNanos,omitzero"`
 }
 
-type Cache struct {
-	ID        uint64 `json:"id" boltholdKey:"ID"`
-	Repo      string `json:"repo" boltholdIndex:"Repo"`
-	Key       string `json:"key" boltholdIndex:"Key"`
-	Version   string `json:"version" boltholdIndex:"Version"`
-	Size      int64  `json:"cacheSize"`
-	Complete  bool   `json:"complete" boltholdIndex:"Complete"`
-	UsedAt    int64  `json:"usedAt" boltholdIndex:"UsedAt"`
-	CreatedAt int64  `json:"createdAt" boltholdIndex:"CreatedAt"`
+func (cache *Cache) createdAtNano() int64 {
+	return cache.CreatedAt*int64(time.Second) + int64(cache.CreatedAtNanos)
 }

act/artifactcache/results.go

@@ -0,0 +1,89 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifactcache
+
+import (
+	"cmp"
+	"crypto/tls"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"strings"
+)
+
+// The results service is one origin serving every github.actions.results.api.v1 service, and
+// Gitea implements only the artifact half of it. Forwarding that half from here makes this origin
+// the whole service, so ACTIONS_RESULTS_URL can point at it truthfully, which is what the clients
+// this runner cannot patch need, docker buildx among them.
+const artifactServicePath = "/twirp/github.actions.results.api.v1.ArtifactService/"
+
+// forwardOrNotFound is the router's fallback: the artifact service of the instance the job
+// registered with, and the 404 the router would have written otherwise.
+func (h *Handler) forwardOrNotFound(w http.ResponseWriter, r *http.Request) {
+	if !strings.HasPrefix(r.URL.Path, artifactServicePath) {
+		http.NotFound(w, r)
+		return
+	}
+	cred, ok := h.lookupCredential(bearerToken(r))
+	if !ok {
+		h.twirpError(w, r, twirpUnauthenticated, errors.New("unknown bearer token"))
+		return
+	}
+	if cred.Results == "" {
+		h.twirpError(w, r, twirpInternal, errors.New("no instance is registered for this job"))
+		return
+	}
+	target, err := url.Parse(strings.TrimSuffix(cred.Results, "/"))
+	if err == nil && (target.Hostname() == "" || (target.Scheme != "http" && target.Scheme != "https")) {
+		err = errors.New("not an absolute http or https URL the job could use")
+	}
+	if err != nil {
+		h.logger.Errorf("artifact service forward to %q: %v", cred.Results, err)
+		h.twirpError(w, r, twirpInternal, fmt.Errorf("artifact service address %q is unusable: %w", cred.Results, err))
+		return
+	}
+	if !h.mustProxy(r, cred, target) {
+		redirect := target.JoinPath(r.URL.EscapedPath())
+		redirect.RawQuery = mergeQuery(target.RawQuery, r.URL.RawQuery)
+		h.logger.Debugf("%s %s: redirecting to %s", r.Method, r.URL.Path, target)
+		http.Redirect(w, r, redirect.String(), http.StatusTemporaryRedirect)
+		return
+	}
+	h.logger.Debugf("%s %s: forwarding to %s", r.Method, r.URL.Path, target)
+
+	proxy := &httputil.ReverseProxy{
+		Rewrite: func(r *httputil.ProxyRequest) {
+			r.SetURL(target)
+			// Gitea builds the URLs it hands back from this Host, and their scheme from the
+			// connection unless a forwarded header overrides it, so artifact bodies go to Gitea
+			// directly and never through here.
+			r.Out.Host = target.Host
+		},
+		ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
+			h.logger.Warnf("artifact service forward to %s: %v", target, err)
+			h.twirpError(w, r, twirpInternal, fmt.Errorf("cache server cannot reach the artifact service at %s: %w", target, err))
+		},
+	}
+	if cred.InsecureTLS {
+		proxy.Transport = insecureTransport
+	}
+	proxy.ServeHTTP(w, r)
+}
+
+// A protocol switch loses the bearer or the agent, and an untrusted instance needs skipped verification.
+func (h *Handler) mustProxy(r *http.Request, cred JobCredential, target *url.URL) bool {
+	return cred.InsecureTLS && target.Scheme == "https" || cmp.Or(r.Header.Get("X-Forwarded-Proto"), "http") != target.Scheme
+}
+
+func mergeQuery(target, request string) string {
+	if target == "" || request == "" {
+		return target + request
+	}
+	return target + "&" + request
+}
+
+// insecureTransport is shared, because a transport per request would pool no connections.
+var insecureTransport = &http.Transport{Proxy: http.ProxyFromEnvironment, TLSClientConfig: &tls.Config{InsecureSkipVerify: true}} //nolint:gosec // the runner reaches its instance on the operator's say-so

act/artifactcache/results_test.go

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

act/artifactcache/s3_storage.go

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

act/artifactcache/s3_storage_test.go

@@ -0,0 +1,141 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifactcache
+
+import (
+	"encoding/xml"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestHandler_S3SharesEntriesAndDropsExpiredOnes(t *testing.T) {
+	t.Parallel()
+	var objects sync.Map
+	var uploads atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		key := strings.TrimPrefix(request.URL.Path, "/cache/")
+		switch {
+		case request.Method == http.MethodPut:
+			if strings.Contains(key, "/blobs/") {
+				uploads.Add(1)
+			}
+			body, err := io.ReadAll(request.Body)
+			assert.NoError(t, err)
+			objects.Store(key, body)
+		case request.URL.Query().Has("list-type"):
+			_, _ = io.WriteString(writer, "<ListBucketResult>")
+			objects.Range(func(stored, _ any) bool {
+				_, _ = io.WriteString(writer, "<Contents><Key>"+stored.(string)+"</Key></Contents>")
+				return true
+			})
+			_, _ = io.WriteString(writer, "</ListBucketResult>")
+		default:
+			if body, ok := objects.Load(key); ok {
+				_, _ = writer.Write(body.([]byte))
+			} else {
+				writer.WriteHeader(http.StatusNotFound)
+			}
+		}
+	}))
+	t.Cleanup(server.Close)
+	opts := Options{S3: &S3Options{Endpoint: server.URL, Bucket: "cache", Prefix: "runners", AccessKey: "key", SecretKey: "secret"}}
+	saver, restorer := startTestHandler(t, opts), startTestHandler(t, opts)
+	entry := map[string]any{"key": "deps", "version": "v1"}
+
+	started := time.Now()
+	finalized, _ := saveV2(t, saver, "deps", "v1", []byte("archive"))
+	require.Equal(t, true, finalized["ok"])
+	assert.EqualValues(t, 1, uploads.Load())
+	id, err := strconv.ParseUint(finalized["entry_id"].(string), 10, 64)
+	require.NoError(t, err)
+	cache, err := saver.s3.fetch(t.Context(), id)
+	require.NoError(t, err)
+	assert.WithinRange(t, time.Unix(cache.CreatedAt, int64(cache.CreatedAtNanos)), started, time.Now())
+	require.NoError(t, restorer.importMetadata(t.Context()))
+	found := v2Call(t, restorer, testClient, "GetCacheEntryDownloadURL", entry)
+	require.Equal(t, true, found["ok"])
+	assert.Equal(t, []byte("archive"), getURL(t, found["signed_download_url"].(string)))
+
+	for _, cache := range []*Cache{
+		{ID: 2, Repo: testRepo, Key: "deps-old", Version: "v1", Complete: true, CreatedAt: cache.CreatedAt},
+		{ID: 1, Repo: testRepo, Key: "deps-new", Version: "v1", Complete: true, CreatedAt: cache.CreatedAt, CreatedAtNanos: 1},
+	} {
+		require.NoError(t, saver.s3.publish(cache))
+		objects.Store(saver.s3.blobKey(cache.ID), []byte(cache.Key))
+	}
+	require.NoError(t, restorer.importMetadata(t.Context()))
+	found = v2Call(t, restorer, testClient, "GetCacheEntryDownloadURL", map[string]any{"key": "deps-", "version": "v1"})
+	require.Equal(t, true, found["ok"])
+	assert.Equal(t, "deps-new", found["matched_key"])
+	assert.Equal(t, []byte("deps-new"), getURL(t, found["signed_download_url"].(string)))
+
+	objects.Clear()
+	require.NoError(t, restorer.importMetadata(t.Context()))
+	assert.Equal(t, true, v2Call(t, restorer, testClient, "CreateCacheEntry", entry)["ok"])
+}
+
+type s3TestTransport func(*http.Request) (*http.Response, error)
+
+func (transport s3TestTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	return transport(req)
+}
+
+func TestS3StorageUploadsLargeObjectsInPartsAndAbortsOnFailure(t *testing.T) {
+	t.Parallel()
+	for _, failingPart := range []string{"", "2"} {
+		var parts, aborts atomic.Int32
+		var completion struct {
+			Parts []s3Part `xml:"Part"`
+		}
+		storage := &s3Storage{bucketURL: httptest.NewRequest(http.MethodGet, "http://cache.local/bucket", nil).URL}
+		storage.client = &http.Client{Transport: s3TestTransport(func(req *http.Request) (*http.Response, error) {
+			query, response := req.URL.Query(), &http.Response{StatusCode: http.StatusOK, Header: make(http.Header), Body: http.NoBody}
+			switch {
+			case query.Has("uploads"):
+				response.Body = io.NopCloser(strings.NewReader("<InitiateMultipartUploadResult><UploadId>upload</UploadId></InitiateMultipartUploadResult>"))
+			case req.Method == http.MethodPut:
+				parts.Add(1)
+				response.Header.Set("ETag", "etag-"+query.Get("partNumber"))
+				if query.Get("partNumber") == failingPart {
+					response.StatusCode, response.Body = http.StatusBadRequest, io.NopCloser(strings.NewReader("<Error><Code>InvalidPart</Code></Error>"))
+				}
+			case req.Method == http.MethodPost:
+				require.NoError(t, xml.NewDecoder(req.Body).Decode(&completion))
+				response.Body = io.NopCloser(strings.NewReader("<CompleteMultipartUploadResult/>"))
+			case req.Method == http.MethodDelete:
+				aborts.Add(1)
+			}
+			return response, nil
+		})}
+		err := storage.upload(t.Context(), "blobs/1", strings.NewReader(""), 2*int64(s3PartSize)+1)
+		assert.EqualValues(t, 3, parts.Load())
+		if failingPart == "" {
+			require.NoError(t, err)
+			assert.Equal(t, []s3Part{{1, "etag-1"}, {2, "etag-2"}, {3, "etag-3"}}, completion.Parts)
+			assert.Zero(t, aborts.Load())
+		} else {
+			require.ErrorContains(t, err, "InvalidPart")
+			assert.EqualValues(t, 1, aborts.Load())
+		}
+	}
+}
+
+func TestS3StorageSignsLikeAWS(t *testing.T) {
+	t.Parallel()
+	storage := &s3Storage{opts: S3Options{Region: "us-east-1", AccessKey: "AKIAIOSFODNN7EXAMPLE", SecretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}
+	req := httptest.NewRequest(http.MethodGet, "https://examplebucket.s3.amazonaws.com/?max-keys=2&prefix=J", nil)
+	req.Header.Set("X-Amz-Content-Sha256", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
+	storage.sign(req, time.Date(2013, 5, 24, 0, 0, 0, 0, time.UTC))
+	assert.Equal(t, "AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7", req.Header.Get("Authorization"))
+}

act/artifactcache/storage.go

@@ -5,8 +5,10 @@
 package artifactcache
 
 import (
+	"bytes"
 	"crypto/sha256"
 	"encoding/hex"
+	"encoding/json/v2"
 	"fmt"
 	"io"
 	"net/http"
@@ -30,13 +32,11 @@ func NewStorage(rootDir string) (*Storage, error) {
 }
 
 func (s *Storage) Exist(id uint64) (bool, error) {
-	name := s.filename(id)
-	if _, err := os.Stat(name); os.IsNotExist(err) {
+	_, err := os.Stat(s.filename(id))
+	if os.IsNotExist(err) {
 		return false, nil
-	} else if err != nil {
-		return false, err
 	}
-	return true, nil
+	return err == nil, err
 }
 
 func (s *Storage) Write(id uint64, offset int64, reader io.Reader) error {
@@ -66,6 +66,18 @@ func (s *Storage) WriteBlock(id uint64, blockID string, reader io.Reader) error
 // rename pass is safe because a staged name always carries blockFilePrefix and a target name
 // never does, so no rename can collide with a block not yet moved.
 func (s *Storage) OrderBlocks(id uint64, blockIDs []string) error {
+	wanted, err := json.Marshal(blockIDs) // a block id is client-chosen, so it cannot be a separator
+	if err != nil {
+		return err
+	}
+	list := filepath.Join(s.tempDir(id), blockFilePrefix+"list")
+	if recorded, err := os.ReadFile(list); err == nil {
+		// A retry repeats the list it already sent; another one would reorder what is now staged.
+		if !bytes.Equal(recorded, wanted) {
+			return fmt.Errorf("cache %d was already assembled from a different block list", id)
+		}
+		return nil
+	}
 	for i, blockID := range blockIDs {
 		if err := os.Rename(s.blockName(id, blockID), s.tempName(id, int64(i))); err != nil {
 			if os.IsNotExist(err) {
@@ -74,13 +86,11 @@ func (s *Storage) OrderBlocks(id uint64, blockIDs []string) error {
 			return err
 		}
 	}
-	return nil
+	return os.WriteFile(list, wanted, 0o600)
 }
 
 func (s *Storage) Commit(id uint64, size int64) (int64, error) {
-	defer func() {
-		_ = os.RemoveAll(s.tempDir(id))
-	}()
+	defer func() { _ = os.RemoveAll(s.tempDir(id)) }()
 
 	name := s.filename(id)
 	tempNames, err := s.tempNames(id)
@@ -139,13 +149,16 @@ func assemble(name string, tempNames []string) (int64, error) {
 }
 
 func (s *Storage) Serve(w http.ResponseWriter, r *http.Request, id uint64) {
-	name := s.filename(id)
-	http.ServeFile(w, r, name)
+	http.ServeFile(w, r, s.filename(id))
 }
 
-func (s *Storage) Remove(id uint64) {
-	_ = os.Remove(s.filename(id))
-	_ = os.RemoveAll(s.tempDir(id))
+// Remove deletes an entry's blob and any staged parts. It reports failure so the caller can
+// keep the entry and retry, rather than dropping the only reference to bytes on disk.
+func (s *Storage) Remove(id uint64) error {
+	if err := os.Remove(s.filename(id)); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return os.RemoveAll(s.tempDir(id))
 }
 
 func (s *Storage) filename(id uint64) string {

act/artifacts/server.go

@@ -6,20 +6,20 @@ package artifacts
 
 import (
 	"context"
-	"encoding/json"
+	"encoding/json/v2"
 	"errors"
 	"fmt"
 	"io"
 	"io/fs"
+	"net"
 	"net/http"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
 	"time"
 
 	"gitea.com/gitea/runner/act/common"
-
-	"github.com/julienschmidt/httprouter"
 )
 
 type FileContainerResourceURL struct {
@@ -50,140 +50,87 @@ type ResponseMessage struct {
 	Message string `json:"message"`
 }
 
-type WritableFile interface {
-	io.WriteCloser
-}
-
-type WriteFS interface {
-	OpenWritable(name string) (WritableFile, error)
-	OpenAppendable(name string) (WritableFile, error)
-}
-
-type readWriteFSImpl struct{}
-
-func (fwfs readWriteFSImpl) Open(name string) (fs.File, error) {
-	return os.Open(name)
-}
-
-func (fwfs readWriteFSImpl) OpenWritable(name string) (WritableFile, error) {
-	if err := os.MkdirAll(filepath.Dir(name), os.ModePerm); err != nil {
-		return nil, err
-	}
-	return os.OpenFile(name, os.O_CREATE|os.O_RDWR|os.O_TRUNC, 0o644)
-}
-
-func (fwfs readWriteFSImpl) OpenAppendable(name string) (WritableFile, error) {
-	if err := os.MkdirAll(filepath.Dir(name), os.ModePerm); err != nil {
-		return nil, err
-	}
-	file, err := os.OpenFile(name, os.O_CREATE|os.O_RDWR, 0o644)
-	if err != nil {
-		return nil, err
-	}
-
-	_, err = file.Seek(0, io.SeekEnd)
-	if err != nil {
-		return nil, err
-	}
-	return file, nil
-}
-
 var gzipExtension = ".gz__"
 
 func safeResolve(baseDir, relPath string) string {
 	return filepath.Join(baseDir, filepath.Clean(filepath.Join(string(os.PathSeparator), relPath)))
 }
 
-func uploads(router *httprouter.Router, baseDir string, fsys WriteFS) {
-	router.POST("/_apis/pipelines/workflows/:runId/artifacts", func(w http.ResponseWriter, req *http.Request, params httprouter.Params) {
-		runID := params.ByName("runId")
+func writeJSON(w http.ResponseWriter, value any) {
+	data, err := json.Marshal(value)
+	if err != nil {
+		panic(err)
+	}
+	if _, err := w.Write(data); err != nil {
+		panic(err)
+	}
+}
 
-		json, err := json.Marshal(FileContainerResourceURL{
-			FileContainerResourceURL: fmt.Sprintf("http://%s/upload/%s", req.Host, runID),
+func uploads(router *http.ServeMux, baseDir string) {
+	router.HandleFunc("POST /_apis/pipelines/workflows/{runId}/artifacts", func(w http.ResponseWriter, req *http.Request) {
+		writeJSON(w, FileContainerResourceURL{
+			FileContainerResourceURL: fmt.Sprintf("http://%s/upload/%s", req.Host, req.PathValue("runId")),
 		})
-		if err != nil {
-			panic(err)
-		}
-
-		_, err = w.Write(json)
-		if err != nil {
-			panic(err)
-		}
 	})
 
-	router.PUT("/upload/:runId", func(w http.ResponseWriter, req *http.Request, params httprouter.Params) {
+	router.HandleFunc("PUT /upload/{runId}", func(w http.ResponseWriter, req *http.Request) {
 		itemPath := req.URL.Query().Get("itemPath")
-		runID := params.ByName("runId")
 
 		if req.Header.Get("Content-Encoding") == "gzip" {
 			itemPath += gzipExtension
 		}
 
-		safeRunPath := safeResolve(baseDir, runID)
-		safePath := safeResolve(safeRunPath, itemPath)
+		safePath := safeResolve(safeResolve(baseDir, req.PathValue("runId")), itemPath)
 
-		file, err := func() (WritableFile, error) {
-			contentRange := req.Header.Get("Content-Range")
-			if contentRange != "" && !strings.HasPrefix(contentRange, "bytes 0-") {
-				return fsys.OpenAppendable(safePath)
+		if err := os.MkdirAll(filepath.Dir(safePath), os.ModePerm); err != nil {
+			panic(err)
+		}
+		var start int64
+		if contentRange := req.Header.Get("Content-Range"); contentRange != "" {
+			if _, err := fmt.Sscanf(contentRange, "bytes %d-", &start); err != nil || start < 0 {
+				http.Error(w, "invalid content range", http.StatusBadRequest)
+				return
 			}
-			return fsys.OpenWritable(safePath)
-		}()
+		}
+		flags := os.O_CREATE | os.O_WRONLY
+		if start == 0 {
+			flags |= os.O_TRUNC
+		}
+		file, err := os.OpenFile(safePath, flags, 0o644)
 		if err != nil {
 			panic(err)
 		}
 		defer file.Close()
-
-		writer, ok := file.(io.Writer)
-		if !ok {
-			panic(errors.New("File is not writable"))
+		if _, err := file.Seek(start, io.SeekStart); err != nil {
+			panic(err)
 		}
-
 		if req.Body == nil {
-			panic(errors.New("No body given"))
+			panic(errors.New("no body given"))
 		}
 
-		_, err = io.Copy(writer, req.Body)
+		_, err = io.Copy(file, req.Body)
 		if err != nil {
 			panic(err)
 		}
 
-		json, err := json.Marshal(ResponseMessage{
+		writeJSON(w, ResponseMessage{
 			Message: "success",
 		})
-		if err != nil {
-			panic(err)
-		}
-
-		_, err = w.Write(json)
-		if err != nil {
-			panic(err)
-		}
 	})
 
-	router.PATCH("/_apis/pipelines/workflows/:runId/artifacts", func(w http.ResponseWriter, req *http.Request, params httprouter.Params) {
-		json, err := json.Marshal(ResponseMessage{
+	router.HandleFunc("PATCH /_apis/pipelines/workflows/{runId}/artifacts", func(w http.ResponseWriter, _req *http.Request) {
+		writeJSON(w, ResponseMessage{
 			Message: "success",
 		})
-		if err != nil {
-			panic(err)
-		}
-
-		_, err = w.Write(json)
-		if err != nil {
-			panic(err)
-		}
 	})
 }
 
-func downloads(router *httprouter.Router, baseDir string, fsys fs.FS) {
-	router.GET("/_apis/pipelines/workflows/:runId/artifacts", func(w http.ResponseWriter, req *http.Request, params httprouter.Params) {
-		runID := params.ByName("runId")
+func downloads(router *http.ServeMux, baseDir string) {
+	router.HandleFunc("GET /_apis/pipelines/workflows/{runId}/artifacts", func(w http.ResponseWriter, req *http.Request) {
+		runID := req.PathValue("runId")
 
-		safePath := safeResolve(baseDir, runID)
-
-		entries, err := fs.ReadDir(fsys, safePath)
-		if err != nil {
+		entries, err := os.ReadDir(safeResolve(baseDir, runID))
+		if err != nil && !os.IsNotExist(err) {
 			panic(err)
 		}
 
@@ -195,27 +142,22 @@ func downloads(router *httprouter.Router, baseDir string, fsys fs.FS) {
 			})
 		}
 
-		json, err := json.Marshal(NamedFileContainerResourceURLResponse{
+		writeJSON(w, NamedFileContainerResourceURLResponse{
 			Count: len(list),
 			Value: list,
 		})
-		if err != nil {
-			panic(err)
-		}
-
-		_, err = w.Write(json)
-		if err != nil {
-			panic(err)
-		}
 	})
 
-	router.GET("/download/:container", func(w http.ResponseWriter, req *http.Request, params httprouter.Params) {
-		container := params.ByName("container")
+	router.HandleFunc("GET /download/{container}", func(w http.ResponseWriter, req *http.Request) {
+		container := req.PathValue("container")
 		itemPath := req.URL.Query().Get("itemPath")
 		safePath := safeResolve(baseDir, filepath.Join(container, itemPath))
 
 		var files []ContainerItem
-		err := fs.WalkDir(fsys, safePath, func(path string, entry fs.DirEntry, err error) error {
+		err := filepath.WalkDir(safePath, func(path string, entry fs.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
 			if !entry.IsDir() {
 				rel, err := filepath.Rel(safePath, path)
 				if err != nil {
@@ -224,50 +166,37 @@ func downloads(router *httprouter.Router, baseDir string, fsys fs.FS) {
 
 				// if it was upload as gzip
 				rel = strings.TrimSuffix(rel, gzipExtension)
-				path := filepath.Join(itemPath, rel)
-
-				rel = filepath.ToSlash(rel)
-				path = filepath.ToSlash(path)
 
 				files = append(files, ContainerItem{
-					Path:            path,
+					Path:            filepath.ToSlash(filepath.Join(itemPath, rel)),
 					ItemType:        "file",
-					ContentLocation: fmt.Sprintf("http://%s/artifact/%s/%s/%s", req.Host, container, itemPath, rel),
+					ContentLocation: (&url.URL{Scheme: "http", Host: req.Host, Path: "/artifact/" + container + "/" + itemPath + "/" + filepath.ToSlash(rel)}).String(),
 				})
 			}
 			return nil
 		})
-		if err != nil {
+		if err != nil && !os.IsNotExist(err) {
 			panic(err)
 		}
 
-		json, err := json.Marshal(ContainerItemResponse{
+		writeJSON(w, ContainerItemResponse{
 			Value: files,
 		})
-		if err != nil {
-			panic(err)
-		}
-
-		_, err = w.Write(json)
-		if err != nil {
-			panic(err)
-		}
 	})
 
-	router.GET("/artifact/*path", func(w http.ResponseWriter, req *http.Request, params httprouter.Params) {
-		path := params.ByName("path")[1:]
+	router.HandleFunc("GET /artifact/{path...}", func(w http.ResponseWriter, req *http.Request) {
+		safePath := safeResolve(baseDir, req.PathValue("path"))
 
-		safePath := safeResolve(baseDir, path)
-
-		file, err := fsys.Open(safePath)
+		file, err := os.Open(safePath)
 		if err != nil {
 			// try gzip file
-			file, err = fsys.Open(safePath + gzipExtension)
+			file, err = os.Open(safePath + gzipExtension)
 			if err != nil {
 				panic(err)
 			}
 			w.Header().Add("Content-Encoding", "gzip")
 		}
+		defer file.Close()
 
 		_, err = io.Copy(w, file)
 		if err != nil {
@@ -284,24 +213,25 @@ func Serve(ctx context.Context, artifactPath, addr, port string) context.CancelF
 		return cancel
 	}
 
-	router := httprouter.New()
+	router := http.NewServeMux()
 
 	logger.Debugf("Artifacts base path '%s'", artifactPath)
-	fsys := readWriteFSImpl{}
-	uploads(router, artifactPath, fsys)
-	downloads(router, artifactPath, fsys)
+	uploads(router, artifactPath)
+	downloads(router, artifactPath)
+	registerV4(router, artifactPath)
 
 	server := &http.Server{
-		Addr:              fmt.Sprintf("%s:%s", addr, port),
+		Addr:              net.JoinHostPort(addr, port),
 		ReadHeaderTimeout: 2 * time.Second,
 		Handler:           router,
 	}
 
 	// run server
 	go func() {
-		logger.Infof("Start server on http://%s:%s", addr, port)
+		logger.Infof("Start server on http://%s", server.Addr)
 		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			logger.Fatal(err)
+			logger.Error(err)
+			os.Exit(1)
 		}
 	}()
 

act/artifacts/server_test.go

@@ -7,8 +7,7 @@ package artifacts
 import (
 	"bytes"
 	"compress/gzip"
-	"encoding/json"
-	"fmt"
+	"encoding/json/v2"
 	"io"
 	"maps"
 	"net/http"
@@ -18,238 +17,18 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
-	"testing/fstest"
 	"time"
 
-	"github.com/julienschmidt/httprouter"
-	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-type writableMapFile struct {
-	fstest.MapFile
-}
-
-func (f *writableMapFile) Write(data []byte) (int, error) {
-	f.Data = data
-	return len(data), nil
-}
-
-func (f *writableMapFile) Close() error {
-	return nil
-}
-
-type writeMapFS struct {
-	fstest.MapFS
-}
-
-func (fsys writeMapFS) OpenWritable(name string) (WritableFile, error) {
-	file := &writableMapFile{
-		MapFile: fstest.MapFile{
-			Data: []byte("content2"),
-		},
-	}
-	fsys.MapFS[name] = &file.MapFile
-
-	return file, nil
-}
-
-func (fsys writeMapFS) OpenAppendable(name string) (WritableFile, error) {
-	file := &writableMapFile{
-		MapFile: fstest.MapFile{
-			Data: []byte("content2"),
-		},
-	}
-	fsys.MapFS[name] = &file.MapFile
-
-	return file, nil
-}
-
-func TestNewArtifactUploadPrepare(t *testing.T) {
-	assert := assert.New(t)
-
-	memfs := fstest.MapFS(map[string]*fstest.MapFile{})
-
-	router := httprouter.New()
-	uploads(router, "artifact/server/path", writeMapFS{memfs})
-
-	req, _ := http.NewRequest(http.MethodPost, "http://localhost/_apis/pipelines/workflows/1/artifacts", nil)
-	rr := httptest.NewRecorder()
-
-	router.ServeHTTP(rr, req)
-
-	if status := rr.Code; status != http.StatusOK {
-		assert.Fail("Wrong status")
-	}
-
-	response := FileContainerResourceURL{}
-	err := json.Unmarshal(rr.Body.Bytes(), &response)
-	if err != nil {
-		panic(err)
-	}
-
-	assert.Equal("http://localhost/upload/1", response.FileContainerResourceURL)
-}
-
-func TestArtifactUploadBlob(t *testing.T) {
-	assert := assert.New(t)
-
-	memfs := fstest.MapFS(map[string]*fstest.MapFile{})
-
-	router := httprouter.New()
-	uploads(router, "artifact/server/path", writeMapFS{memfs})
-
-	req, _ := http.NewRequest(http.MethodPut, "http://localhost/upload/1?itemPath=some/file", strings.NewReader("content"))
-	rr := httptest.NewRecorder()
-
-	router.ServeHTTP(rr, req)
-
-	if status := rr.Code; status != http.StatusOK {
-		assert.Fail("Wrong status")
-	}
-
-	response := ResponseMessage{}
-	err := json.Unmarshal(rr.Body.Bytes(), &response)
-	if err != nil {
-		panic(err)
-	}
-
-	assert.Equal("success", response.Message)
-	assert.Equal("content", string(memfs["artifact/server/path/1/some/file"].Data))
-}
-
-func TestFinalizeArtifactUpload(t *testing.T) {
-	assert := assert.New(t)
-
-	memfs := fstest.MapFS(map[string]*fstest.MapFile{})
-
-	router := httprouter.New()
-	uploads(router, "artifact/server/path", writeMapFS{memfs})
-
-	req, _ := http.NewRequest(http.MethodPatch, "http://localhost/_apis/pipelines/workflows/1/artifacts", nil)
-	rr := httptest.NewRecorder()
-
-	router.ServeHTTP(rr, req)
-
-	if status := rr.Code; status != http.StatusOK {
-		assert.Fail("Wrong status")
-	}
-
-	response := ResponseMessage{}
-	err := json.Unmarshal(rr.Body.Bytes(), &response)
-	if err != nil {
-		panic(err)
-	}
-
-	assert.Equal("success", response.Message)
-}
-
-func TestListArtifacts(t *testing.T) {
-	assert := assert.New(t)
-
-	memfs := fstest.MapFS(map[string]*fstest.MapFile{
-		"artifact/server/path/1/file.txt": {
-			Data: []byte(""),
-		},
-	})
-
-	router := httprouter.New()
-	downloads(router, "artifact/server/path", memfs)
-
-	req, _ := http.NewRequest(http.MethodGet, "http://localhost/_apis/pipelines/workflows/1/artifacts", nil)
-	rr := httptest.NewRecorder()
-
-	router.ServeHTTP(rr, req)
-
-	if status := rr.Code; status != http.StatusOK {
-		assert.FailNow(fmt.Sprintf("Wrong status: %d", status))
-	}
-
-	response := NamedFileContainerResourceURLResponse{}
-	err := json.Unmarshal(rr.Body.Bytes(), &response)
-	if err != nil {
-		panic(err)
-	}
-
-	assert.Equal(1, response.Count)
-	assert.Equal("file.txt", response.Value[0].Name)
-	assert.Equal("http://localhost/download/1", response.Value[0].FileContainerResourceURL)
-}
-
-func TestListArtifactContainer(t *testing.T) {
-	assert := assert.New(t)
-
-	memfs := fstest.MapFS(map[string]*fstest.MapFile{
-		"artifact/server/path/1/some/file": {
-			Data: []byte(""),
-		},
-	})
-
-	router := httprouter.New()
-	downloads(router, "artifact/server/path", memfs)
-
-	req, _ := http.NewRequest(http.MethodGet, "http://localhost/download/1?itemPath=some/file", nil)
-	rr := httptest.NewRecorder()
-
-	router.ServeHTTP(rr, req)
-
-	if status := rr.Code; status != http.StatusOK {
-		assert.FailNow(fmt.Sprintf("Wrong status: %d", status))
-	}
-
-	response := ContainerItemResponse{}
-	err := json.Unmarshal(rr.Body.Bytes(), &response)
-	if err != nil {
-		panic(err)
-	}
-
-	assert.Len(response.Value, 1)
-	assert.Equal("some/file", response.Value[0].Path)
-	assert.Equal("file", response.Value[0].ItemType)
-	assert.Equal("http://localhost/artifact/1/some/file/.", response.Value[0].ContentLocation)
-}
-
-func TestDownloadArtifactFile(t *testing.T) {
-	assert := assert.New(t)
-
-	memfs := fstest.MapFS(map[string]*fstest.MapFile{
-		"artifact/server/path/1/some/file": {
-			Data: []byte("content"),
-		},
-	})
-
-	router := httprouter.New()
-	downloads(router, "artifact/server/path", memfs)
-
-	req, _ := http.NewRequest(http.MethodGet, "http://localhost/artifact/1/some/file", nil)
-	rr := httptest.NewRecorder()
-
-	router.ServeHTTP(rr, req)
-
-	if status := rr.Code; status != http.StatusOK {
-		assert.FailNow(fmt.Sprintf("Wrong status: %d", status))
-	}
-
-	data := rr.Body.Bytes()
-
-	assert.Equal("content", string(data))
-}
-
-// TestArtifactFlow drives the real Serve() artifact server over a loopback socket, exercising
-// the same upload -> finalize -> list -> download protocol the upload-artifact/download-artifact
-// actions speak. Running it in-process (rather than from a job container) keeps it network-free
-// and reachable everywhere, including when the CI job is itself a container.
 func TestArtifactFlow(t *testing.T) {
 	artifactPath := t.TempDir()
 
-	// 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)
+	router := http.NewServeMux()
+	uploads(router, artifactPath)
+	downloads(router, artifactPath)
+	registerV4(router, artifactPath)
 	server := httptest.NewServer(router)
 	defer server.Close()
 
@@ -257,8 +36,6 @@ func TestArtifactFlow(t *testing.T) {
 	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)
@@ -272,8 +49,17 @@ func TestArtifactFlow(t *testing.T) {
 		return resp.StatusCode, data
 	}
 
+	t.Run("no-artifacts", func(t *testing.T) {
+		status, data := request(t, http.MethodGet, baseURL+"/_apis/pipelines/workflows/0/artifacts", nil, nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+		var list NamedFileContainerResourceURLResponse
+		require.NoError(t, json.Unmarshal(data, &list))
+		require.Zero(t, list.Count)
+		require.Empty(t, list.Value)
+	})
+
 	t.Run("upload-and-download", func(t *testing.T) {
-		const runID, item, content = "1", "my-artifact/data.txt", "hello artifact\n"
+		const runID, item, content = "1", "my-artifact/data#1%25.txt", "hello artifact\n"
 
 		status, data := request(t, http.MethodPost, baseURL+"/_apis/pipelines/workflows/"+runID+"/artifacts", nil, nil)
 		require.Equal(t, http.StatusOK, status, string(data))
@@ -289,6 +75,8 @@ func TestArtifactFlow(t *testing.T) {
 
 		status, data = request(t, http.MethodPatch, baseURL+"/_apis/pipelines/workflows/"+runID+"/artifacts", nil, nil)
 		require.Equal(t, http.StatusOK, status, string(data))
+		require.NoError(t, json.Unmarshal(data, &msg))
+		require.Equal(t, "success", msg.Message)
 
 		status, data = request(t, http.MethodGet, baseURL+"/_apis/pipelines/workflows/"+runID+"/artifacts", nil, nil)
 		require.Equal(t, http.StatusOK, status, string(data))
@@ -303,17 +91,41 @@ func TestArtifactFlow(t *testing.T) {
 		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)
+		require.Equal(t, item, 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))
 
-		stored, err := os.ReadFile(filepath.Join(artifactPath, runID, "my-artifact", "data.txt"))
+		stored, err := os.ReadFile(filepath.Join(artifactPath, runID, filepath.FromSlash(item)))
 		require.NoError(t, err)
 		require.Equal(t, content, string(stored))
 	})
 
+	t.Run("content-range", func(t *testing.T) {
+		const rawURL = "/upload/4?itemPath=chunks.txt"
+		status, data := request(t, http.MethodPut, baseURL+rawURL, strings.NewReader("first"),
+			http.Header{"Content-Range": []string{"bytes 0-4/12"}})
+		require.Equal(t, http.StatusOK, status, string(data))
+
+		for range 2 {
+			status, data = request(t, http.MethodPut, baseURL+rawURL, strings.NewReader("-second"),
+				http.Header{"Content-Range": []string{"bytes 5-11/12"}})
+			require.Equal(t, http.StatusOK, status, string(data))
+		}
+
+		stored, err := os.ReadFile(filepath.Join(artifactPath, "4", "chunks.txt"))
+		require.NoError(t, err)
+		require.Equal(t, "first-second", string(stored))
+
+		status, data = request(t, http.MethodPut, baseURL+rawURL, strings.NewReader(""),
+			http.Header{"Content-Range": []string{"bytes 0--1/0"}})
+		require.Equal(t, http.StatusOK, status, string(data))
+		stored, err = os.ReadFile(filepath.Join(artifactPath, "4", "chunks.txt"))
+		require.NoError(t, err)
+		require.Empty(t, stored)
+	})
+
 	t.Run("gzip-roundtrip", func(t *testing.T) {
 		const runID, item, content = "2", "logs/app.log", "compressed payload\n"
 
@@ -363,11 +175,95 @@ func TestArtifactFlow(t *testing.T) {
 		require.Equal(t, http.StatusOK, status)
 		require.Equal(t, content, string(data))
 	})
+
+	t.Run("v4", func(t *testing.T) {
+		const artifactRef = `"workflow_run_backend_id":"7","name":"50% art@v1"`
+		call := func(method, body string) (int, map[string]any) {
+			status, data := request(t, http.MethodPost, baseURL+artifactServicePath+"/"+method, strings.NewReader(body), nil)
+			var out map[string]any
+			require.NoError(t, json.Unmarshal(data, &out), string(data))
+			return status, out
+		}
+		put := func(rawURL, body string) int {
+			status, _ := request(t, http.MethodPut, rawURL, strings.NewReader(body), nil)
+			return status
+		}
+		download := func() (string, http.Header) {
+			status, signed := call("GetSignedArtifactURL", "{"+artifactRef+"}")
+			require.Equal(t, http.StatusOK, status, signed)
+			resp, err := client.Get(signed["signedUrl"].(string))
+			require.NoError(t, err)
+			defer resp.Body.Close()
+			require.Equal(t, http.StatusOK, resp.StatusCode)
+			body, err := io.ReadAll(resp.Body)
+			require.NoError(t, err)
+			return string(body), resp.Header
+		}
+
+		status, created := call("CreateArtifact", "{"+artifactRef+"}")
+		require.Equal(t, http.StatusOK, status, created)
+		upload := created["signedUploadUrl"].(string)
+		require.Equal(t, http.StatusCreated, put(upload+"&comp=block&blockid=Yg", "world"))
+		require.Equal(t, http.StatusCreated, put(upload+"&comp=block&blockid=YQ", "hello "))
+		for attempt := range 2 {
+			require.Equal(t, http.StatusCreated, put(upload+"&comp=blocklist", `<?xml version="1.0"?><BlockList><Latest>YQ</Latest><Latest>Yg</Latest></BlockList>`), "commit attempt %d", attempt)
+		}
+
+		digest := "sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+		status, _ = call("FinalizeArtifact", "{"+artifactRef+`,"size":"10"}`)
+		require.Equal(t, http.StatusBadRequest, status)
+		status, finalized := call("FinalizeArtifact", "{"+artifactRef+`,"size":"11","hash":"`+digest+`"}`)
+		require.Equal(t, http.StatusOK, status, finalized)
+		id := finalized["artifactId"].(string)
+		status, refinalized := call("FinalizeArtifact", "{"+artifactRef+`,"size":"10"}`)
+		require.Equal(t, http.StatusOK, status)
+		require.Equal(t, id, refinalized["artifactId"])
+		status, conflict := call("CreateArtifact", "{"+artifactRef+"}")
+		require.Equal(t, http.StatusConflict, status)
+		require.Equal(t, "already_exists", conflict["code"])
+
+		status, listed := call("ListArtifacts", `{"workflowRunBackendId":"7","idFilter":"`+id+`"}`)
+		require.Equal(t, http.StatusOK, status)
+		artifacts := listed["artifacts"].([]any)
+		require.Len(t, artifacts, 1)
+		artifact := artifacts[0].(map[string]any)
+		require.Regexp(t, `^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$`, artifact["createdAt"])
+		delete(artifact, "createdAt")
+		require.Equal(t, map[string]any{"workflowRunBackendId": "7", "name": "50% art@v1", "size": "11", "digest": digest, "databaseId": id}, artifact)
+		_, other := call("ListArtifacts", `{"workflow_run_backend_id":"8"}`)
+		require.Empty(t, other["artifacts"])
+
+		body, header := download()
+		require.Equal(t, "hello world", body)
+		require.Equal(t, "application/zip", header.Get("Content-Type"))
+		require.Equal(t, "attachment; filename*=UTF-8''50%25%20art%40v1.zip", header.Get("Content-Disposition"))
+
+		status, _ = call("DeleteArtifact", "{"+artifactRef+"}")
+		require.Equal(t, http.StatusOK, status)
+		status, missing := call("GetSignedArtifactURL", "{"+artifactRef+"}")
+		require.Equal(t, http.StatusNotFound, status)
+		require.Equal(t, "not_found", missing["code"])
+
+		status, created = call("CreateArtifact", "{"+artifactRef+"}")
+		require.Equal(t, http.StatusOK, status, created)
+		status, _ = request(t, http.MethodPut, created["signedUploadUrl"].(string), strings.NewReader("gz"), http.Header{"X-Ms-Blob-Content-Type": {"application/gzip"}})
+		require.Equal(t, http.StatusCreated, status)
+		status, _ = call("FinalizeArtifact", "{"+artifactRef+`,"size":"2"}`)
+		require.Equal(t, http.StatusOK, status)
+		body, header = download()
+		require.Equal(t, "gz", body)
+		require.Equal(t, "application/gzip", header.Get("Content-Type"))
+		require.Equal(t, "attachment; filename*=UTF-8''50%25%20art%40v1", header.Get("Content-Disposition"))
+
+		rerun := http.NewServeMux()
+		registerV4(rerun, artifactPath)
+		recorder := httptest.NewRecorder()
+		rerun.ServeHTTP(recorder, httptest.NewRequest(http.MethodPost, artifactServicePath+"/CreateArtifact", strings.NewReader("{"+artifactRef+"}")))
+		require.Equal(t, http.StatusOK, recorder.Code, recorder.Body.String())
+	})
 }
 
-func TestMkdirFsImplSafeResolve(t *testing.T) {
-	assert := assert.New(t)
-
+func TestSafeResolve(t *testing.T) {
 	baseDir := "/foo/bar"
 
 	tests := map[string]struct {
@@ -385,97 +281,13 @@ func TestMkdirFsImplSafeResolve(t *testing.T) {
 
 	for name, tc := range tests {
 		t.Run(name, func(t *testing.T) {
-			assert.Equal(tc.want, safeResolve(baseDir, tc.input))
+			require.Equal(t, filepath.FromSlash(tc.want), safeResolve(baseDir, tc.input))
 		})
 	}
 }
 
-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)
-
-	memfs := fstest.MapFS(map[string]*fstest.MapFile{
-		"artifact/server/path/some/file": {
-			Data: []byte("content"),
-		},
-	})
-
-	router := httprouter.New()
-	downloads(router, "artifact/server/path", memfs)
-
-	req, _ := http.NewRequest(http.MethodGet, "http://localhost/artifact/2/../../some/file", nil)
-	rr := httptest.NewRecorder()
-
-	router.ServeHTTP(rr, req)
-
-	if status := rr.Code; status != http.StatusOK {
-		assert.FailNow(fmt.Sprintf("Wrong status: %d", status))
-	}
-
-	data := rr.Body.Bytes()
-
-	assert.Equal("content", string(data))
-}
-
-func TestArtifactUploadBlobUnsafePath(t *testing.T) {
-	assert := assert.New(t)
-
-	memfs := fstest.MapFS(map[string]*fstest.MapFile{})
-
-	router := httprouter.New()
-	uploads(router, "artifact/server/path", writeMapFS{memfs})
-
-	req, _ := http.NewRequest(http.MethodPut, "http://localhost/upload/1?itemPath=../../some/file", strings.NewReader("content"))
-	rr := httptest.NewRecorder()
-
-	router.ServeHTTP(rr, req)
-
-	if status := rr.Code; status != http.StatusOK {
-		assert.Fail("Wrong status")
-	}
-
-	response := ResponseMessage{}
-	err := json.Unmarshal(rr.Body.Bytes(), &response)
-	if err != nil {
-		panic(err)
-	}
-
-	assert.Equal("success", response.Message)
-	assert.Equal("content", string(memfs["artifact/server/path/1/some/file"].Data))
-}

act/artifacts/server_v4.go

@@ -0,0 +1,329 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifacts
+
+import (
+	"cmp"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json/v2"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+)
+
+type serverV4 struct { // the subset of Gitea's v4 artifact service that the toolkit uses, unauthenticated like the v3 routes beside it
+	dir     string
+	mu      sync.Mutex
+	lastID  int64
+	created map[string]bool
+}
+
+const (
+	zipMimeType   = "application/zip"
+	maxTwirpBytes = 1 << 20
+)
+
+func registerV4(router *http.ServeMux, baseDir string) {
+	server := &serverV4{dir: filepath.Join(baseDir, "v4"), lastID: time.Now().UnixMilli(), created: map[string]bool{}} // IDs stay unique across invocations sharing baseDir
+	router.HandleFunc("POST "+artifactServicePath+"/CreateArtifact", twirp(server.createArtifact))
+	router.HandleFunc("POST "+artifactServicePath+"/FinalizeArtifact", twirp(server.finalizeArtifact))
+	router.HandleFunc("POST "+artifactServicePath+"/ListArtifacts", twirp(server.listArtifacts))
+	router.HandleFunc("POST "+artifactServicePath+"/GetSignedArtifactURL", twirp(server.getSignedArtifactURL))
+	router.HandleFunc("POST "+artifactServicePath+"/DeleteArtifact", twirp(server.deleteArtifact))
+	router.HandleFunc("PUT "+artifactServicePath+"/UploadArtifact", server.uploadArtifact)
+	router.HandleFunc("GET "+artifactServicePath+"/DownloadArtifact", server.downloadArtifact)
+}
+
+type twirpError struct {
+	status int
+	code   string
+	msg    string
+}
+
+func (e *twirpError) Error() string { return e.msg }
+
+func notFound(name string) error {
+	return &twirpError{http.StatusNotFound, "not_found", fmt.Sprintf("artifact %q not found", name)}
+}
+
+func badRequest(format string, args ...any) error {
+	return &twirpError{http.StatusBadRequest, "invalid_argument", fmt.Sprintf(format, args...)}
+}
+
+func twirp[Req, Resp any](handle func(*http.Request, Req) (Resp, error)) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		var req Req
+		var resp Resp
+		err := json.UnmarshalRead(io.LimitReader(r.Body, maxTwirpBytes), &req, json.MatchCaseInsensitiveNames(true)) // also matches the toolkit's proto field names
+		if err != nil {
+			err = badRequest("malformed request: %v", err)
+		} else {
+			resp, err = handle(r, req)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		if err != nil {
+			terr := &twirpError{http.StatusInternalServerError, "internal", err.Error()}
+			errors.As(err, &terr)
+			w.WriteHeader(terr.status)
+			_ = json.MarshalWrite(w, map[string]string{"code": terr.code, "msg": terr.msg})
+			return
+		}
+		_ = json.MarshalWrite(w, resp)
+	}
+}
+
+func fileName(name string) string { // safe on any filesystem for any client-chosen name, case-insensitive ones included
+	sum := sha256.Sum256([]byte(name))
+	return hex.EncodeToString(sum[:])
+}
+
+func (s *serverV4) runDir(runID string) string {
+	return filepath.Join(s.dir, fileName(runID))
+}
+
+func (s *serverV4) artifactDir(runID, name string) string {
+	return filepath.Join(s.runDir(runID), fileName(name))
+}
+
+func (s *serverV4) urlDir(r *http.Request) string {
+	return s.artifactDir(r.URL.Query().Get("run"), r.URL.Query().Get("name"))
+}
+
+func readMeta(dir string) (*monolithArtifact, error) {
+	data, err := os.ReadFile(filepath.Join(dir, "meta.json"))
+	if err != nil {
+		return nil, err
+	}
+	var meta monolithArtifact
+	return &meta, json.Unmarshal(data, &meta)
+}
+
+func writeMeta(dir string, meta *monolithArtifact) error {
+	data, err := json.Marshal(meta)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(filepath.Join(dir, "meta.json"), data, 0o644)
+}
+
+func blobURL(r *http.Request, endpoint, runID, name string) string {
+	return "http://" + r.Host + artifactServicePath + "/" + endpoint + "?" + url.Values{"run": {runID}, "name": {name}}.Encode()
+}
+
+func (s *serverV4) createArtifact(r *http.Request, req createArtifactRequest) (createArtifactResponse, error) { // an exec invocation re-runs its workflows, so it replaces earlier invocations' artifacts but conflicts with its own
+	dir := s.artifactDir(req.WorkflowRunBackendID, req.Name)
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.created[dir] {
+		return createArtifactResponse{}, &twirpError{http.StatusConflict, "already_exists", "an artifact with this name already exists on the workflow run"}
+	}
+	if err := os.RemoveAll(dir); err != nil {
+		return createArtifactResponse{}, err
+	}
+	if err := os.MkdirAll(filepath.Join(dir, "blocks"), 0o755); err != nil {
+		return createArtifactResponse{}, err
+	}
+	s.lastID++
+	if err := writeMeta(dir, &monolithArtifact{
+		WorkflowRunBackendID: req.WorkflowRunBackendID,
+		DatabaseID:           s.lastID,
+		Name:                 req.Name,
+		CreatedAt:            time.Now().UTC().Truncate(time.Second),
+	}); err != nil {
+		return createArtifactResponse{}, err
+	}
+	s.created[dir] = true
+	return createArtifactResponse{Ok: true, SignedUploadURL: blobURL(r, "UploadArtifact", req.WorkflowRunBackendID, req.Name)}, nil
+}
+
+type blockList struct {
+	Blocks []string `xml:",any"` // Latest, Committed and Uncommitted all name a staged block
+}
+
+func (s *serverV4) uploadArtifact(w http.ResponseWriter, r *http.Request) {
+	dir := s.urlDir(r)
+	if meta, err := readMeta(dir); err != nil || meta.Digest != "" {
+		http.Error(w, "no artifact awaits an upload", http.StatusNotFound)
+		return
+	}
+	contentType := r.Header.Get("x-ms-blob-content-type")
+	var err error
+	switch comp := r.URL.Query().Get("comp"); comp {
+	case "block":
+		err = writeFile(filepath.Join(dir, "blocks", fileName(r.URL.Query().Get("blockid"))), r.Body)
+	case "blocklist":
+		err = commitBlob(dir, contentType, func(out io.Writer) error { return joinBlocks(out, dir, r.Body) })
+	case "": // Put Blob, which docker/build-push-action uses
+		err = commitBlob(dir, contentType, func(out io.Writer) error {
+			_, err := io.Copy(out, r.Body)
+			return err
+		})
+	default:
+		http.Error(w, "unsupported comp "+comp, http.StatusBadRequest)
+		return
+	}
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(http.StatusCreated)
+}
+
+func writeFile(name string, body io.Reader) error {
+	file, err := os.Create(name)
+	if err != nil {
+		return err
+	}
+	_, err = io.Copy(file, body)
+	return errors.Join(err, file.Close())
+}
+
+func commitBlob(dir, contentType string, write func(io.Writer) error) error { // replaces the blob whole and keeps its content type, as Azure does
+	out, err := os.CreateTemp(dir, "blob")
+	if err != nil {
+		return err
+	}
+	if err = errors.Join(write(out), out.Close()); err == nil {
+		err = os.Rename(out.Name(), filepath.Join(dir, "blob"))
+	}
+	if err != nil {
+		return errors.Join(err, os.Remove(out.Name()))
+	}
+	return os.WriteFile(filepath.Join(dir, "content-type"), []byte(contentType), 0o644)
+}
+
+func joinBlocks(out io.Writer, dir string, body io.Reader) error { // keeps the blocks for finalizeArtifact, so that a retried commit can join them again
+	var list blockList
+	if err := xml.NewDecoder(io.LimitReader(body, maxTwirpBytes)).Decode(&list); err != nil {
+		return err
+	}
+	for _, id := range list.Blocks {
+		if err := appendBlock(out, filepath.Join(dir, "blocks", fileName(id))); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func appendBlock(out io.Writer, name string) error {
+	in, err := os.Open(name)
+	if err != nil {
+		return err
+	}
+	defer in.Close()
+	_, err = io.Copy(out, in)
+	return err
+}
+
+func (s *serverV4) finalizeArtifact(_ *http.Request, req finalizeArtifactRequest) (finalizeArtifactResponse, error) {
+	dir := s.artifactDir(req.WorkflowRunBackendID, req.Name)
+	meta, err := readMeta(dir)
+	if err != nil {
+		return finalizeArtifactResponse{}, notFound(req.Name)
+	} else if meta.Digest != "" {
+		return finalizeArtifactResponse{Ok: true, ArtifactID: meta.DatabaseID}, nil
+	}
+	blob, err := os.Open(filepath.Join(dir, "blob"))
+	if err != nil {
+		return finalizeArtifactResponse{}, badRequest("artifact %q has no upload", req.Name)
+	}
+	defer blob.Close()
+	hash := sha256.New()
+	size, err := io.Copy(hash, blob)
+	if err != nil {
+		return finalizeArtifactResponse{}, err
+	}
+	digest := "sha256:" + hex.EncodeToString(hash.Sum(nil))
+	if size != req.Size {
+		return finalizeArtifactResponse{}, badRequest("size %d does not match the %d bytes uploaded", req.Size, size)
+	}
+	if req.Hash != "" && req.Hash != digest {
+		return finalizeArtifactResponse{}, badRequest("hash %s does not match the uploaded %s", req.Hash, digest)
+	}
+	s.mu.Lock() // only after hashing, so finalizing one large artifact does not stall the others
+	defer s.mu.Unlock()
+	if current, err := readMeta(dir); err != nil || current.DatabaseID != meta.DatabaseID {
+		return finalizeArtifactResponse{}, notFound(req.Name)
+	}
+	meta.Size, meta.Digest = size, digest
+	if err := writeMeta(dir, meta); err != nil {
+		return finalizeArtifactResponse{}, err
+	}
+	return finalizeArtifactResponse{Ok: true, ArtifactID: meta.DatabaseID}, os.RemoveAll(filepath.Join(dir, "blocks"))
+}
+
+func (s *serverV4) listArtifacts(_ *http.Request, req listArtifactsRequest) (listArtifactsResponse, error) {
+	run := s.runDir(req.WorkflowRunBackendID)
+	entries, err := os.ReadDir(run)
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return listArtifactsResponse{}, err
+	}
+	var resp listArtifactsResponse
+	for _, entry := range entries {
+		meta, err := readMeta(filepath.Join(run, entry.Name()))
+		if err != nil || meta.Digest == "" ||
+			req.NameFilter != "" && req.NameFilter != meta.Name || req.IDFilter != 0 && req.IDFilter != meta.DatabaseID {
+			continue
+		}
+		resp.Artifacts = append(resp.Artifacts, *meta)
+	}
+	slices.SortFunc(resp.Artifacts, func(left, right monolithArtifact) int { return cmp.Compare(left.DatabaseID, right.DatabaseID) })
+	return resp, nil
+}
+
+func (s *serverV4) getSignedArtifactURL(r *http.Request, req getSignedArtifactURLRequest) (getSignedArtifactURLResponse, error) {
+	if meta, err := readMeta(s.artifactDir(req.WorkflowRunBackendID, req.Name)); err != nil || meta.Digest == "" {
+		return getSignedArtifactURLResponse{}, notFound(req.Name)
+	}
+	return getSignedArtifactURLResponse{SignedURL: blobURL(r, "DownloadArtifact", req.WorkflowRunBackendID, req.Name)}, nil
+}
+
+func (s *serverV4) downloadArtifact(w http.ResponseWriter, r *http.Request) {
+	dir := s.urlDir(r)
+	meta, err := readMeta(dir)
+	if err != nil || meta.Digest == "" {
+		http.Error(w, "artifact not found", http.StatusNotFound)
+		return
+	}
+	blob, err := os.Open(filepath.Join(dir, "blob"))
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	defer blob.Close()
+	data, _ := os.ReadFile(filepath.Join(dir, "content-type"))
+	contentType, filename := string(data), meta.Name
+	if !strings.Contains(contentType, "/") {
+		contentType = zipMimeType
+	}
+	if contentType == zipMimeType && !strings.HasSuffix(filename, ".zip") {
+		filename += ".zip"
+	}
+	w.Header().Set("Content-Type", contentType)
+	w.Header().Set("Content-Disposition", "attachment; filename*=UTF-8''"+strings.ReplaceAll(url.QueryEscape(filename), "+", "%20")) // RFC 5987 attr-chars only, which the toolkit and mime.ParseMediaType both accept
+	http.ServeContent(w, r, "", meta.CreatedAt, blob)
+}
+
+func (s *serverV4) deleteArtifact(_ *http.Request, req deleteArtifactRequest) (deleteArtifactResponse, error) {
+	dir := s.artifactDir(req.WorkflowRunBackendID, req.Name)
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	meta, err := readMeta(dir)
+	if err != nil {
+		return deleteArtifactResponse{}, notFound(req.Name)
+	}
+	delete(s.created, dir)
+	return deleteArtifactResponse{Ok: true, ArtifactID: meta.DatabaseID}, os.RemoveAll(dir)
+}

act/artifacts/token.go

@@ -0,0 +1,23 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifacts
+
+import (
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/json/v2"
+	"time"
+)
+
+func LocalRuntimeToken(run string, lifetime time.Duration) string { // an unsecured JWT with the claims the toolkit and buildx read, its run hashed for scp and its jti an unguessable bearer
+	now := time.Now()
+	claims, _ := json.Marshal(map[string]any{
+		"scp": "Actions.Results:" + fileName(run) + ":1",
+		"ac":  `[{"Scope":"","Permission":3}]`,
+		"nbf": now.Unix(),
+		"exp": now.Add(lifetime).Unix(),
+		"jti": rand.Text(),
+	})
+	return base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"none","typ":"JWT"}`)) + "." + base64.RawURLEncoding.EncodeToString(claims) + "."
+}

act/artifacts/twirp.go

@@ -0,0 +1,55 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifacts
+
+import "time"
+
+const artifactServicePath = "/twirp/github.actions.results.api.v1.ArtifactService"
+
+type ( // the ArtifactService messages in the protobuf JSON mapping, which writes int64 as strings
+	createArtifactResponse struct {
+		Ok              bool   `json:"ok"`
+		SignedUploadURL string `json:"signedUploadUrl"`
+	}
+
+	finalizeArtifactRequest struct {
+		WorkflowRunBackendID string
+		Name                 string
+		Size                 int64 `json:",string"`
+		Hash                 string
+	}
+	finalizeArtifactResponse struct {
+		Ok         bool  `json:"ok"`
+		ArtifactID int64 `json:"artifactId,string"`
+	}
+
+	listArtifactsRequest struct {
+		WorkflowRunBackendID string
+		NameFilter           string
+		IDFilter             int64 `json:",string"`
+	}
+	listArtifactsResponse struct {
+		Artifacts []monolithArtifact `json:"artifacts"`
+	}
+	monolithArtifact struct {
+		WorkflowRunBackendID string    `json:"workflowRunBackendId"` // the toolkit sends it back to GetSignedArtifactURL
+		DatabaseID           int64     `json:"databaseId,string"`
+		Name                 string    `json:"name"`
+		Size                 int64     `json:"size,string"`
+		CreatedAt            time.Time `json:"createdAt"` // whole seconds, the toolkit rejects the trimmed fractions json writes
+		Digest               string    `json:"digest"`    // empty until the upload is finalized
+	}
+
+	getSignedArtifactURLRequest struct {
+		WorkflowRunBackendID string
+		Name                 string
+	}
+	getSignedArtifactURLResponse struct {
+		SignedURL string `json:"signedUrl"`
+	}
+
+	createArtifactRequest  = getSignedArtifactURLRequest
+	deleteArtifactRequest  = getSignedArtifactURLRequest
+	deleteArtifactResponse = finalizeArtifactResponse
+)

act/common/cartesian.go

@@ -1,60 +0,0 @@
-// Copyright 2026 The Gitea Authors. All rights reserved.
-// Copyright 2020 The nektos/act Authors. All rights reserved.
-// SPDX-License-Identifier: MIT
-
-package common
-
-import "slices"
-
-// CartesianProduct takes map of lists and returns list of unique tuples
-func CartesianProduct(mapOfLists map[string][]any) []map[string]any {
-	listNames := make([]string, 0)
-	lists := make([][]any, 0)
-	for k, v := range mapOfLists {
-		listNames = append(listNames, k)
-		lists = append(lists, v)
-	}
-
-	listCart := cartN(lists...)
-
-	rtn := make([]map[string]any, 0)
-	for _, list := range listCart {
-		vMap := make(map[string]any)
-		for i, v := range list {
-			vMap[listNames[i]] = v
-		}
-		rtn = append(rtn, vMap)
-	}
-	return rtn
-}
-
-func cartN(a ...[]any) [][]any {
-	c := 1
-	for _, a := range a {
-		c *= len(a)
-	}
-	if c == 0 || len(a) == 0 {
-		return nil
-	}
-	p := make([][]any, c)
-	b := make([]any, c*len(a))
-	n := make([]int, len(a))
-	s := 0
-	for i := range p {
-		e := s + len(a)
-		pi := b[s:e]
-		p[i] = pi
-		s = e
-		for j, n := range n {
-			pi[j] = a[j][n]
-		}
-		for j := range slices.Backward(n) {
-			n[j]++
-			if n[j] < len(a[j]) {
-				break
-			}
-			n[j] = 0
-		}
-	}
-	return p
-}

act/common/cartesian_test.go

@@ -1,43 +0,0 @@
-// Copyright 2026 The Gitea Authors. All rights reserved.
-// Copyright 2020 The nektos/act Authors. All rights reserved.
-// SPDX-License-Identifier: MIT
-
-package common
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestCartesianProduct(t *testing.T) {
-	assert := assert.New(t)
-	input := map[string][]any{
-		"foo": {1, 2, 3, 4},
-		"bar": {"a", "b", "c"},
-		"baz": {false, true},
-	}
-
-	output := CartesianProduct(input)
-	assert.Len(output, 24)
-
-	for _, v := range output {
-		assert.Len(v, 3)
-
-		assert.Contains(v, "foo")
-		assert.Contains(v, "bar")
-		assert.Contains(v, "baz")
-	}
-
-	input = map[string][]any{
-		"foo": {1, 2, 3, 4},
-		"bar": {},
-		"baz": {false, true},
-	}
-	output = CartesianProduct(input)
-	assert.Empty(output)
-
-	input = map[string][]any{}
-	output = CartesianProduct(input)
-	assert.Empty(output)
-}

act/common/context_helpers_test.go

@@ -4,15 +4,15 @@
 package common
 
 import (
-	"context"
 	"errors"
 	"testing"
 
-	"github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/act/common/logging/logtest"
 )
 
 func TestDryrunContext(t *testing.T) {
-	ctx := context.Background()
+	ctx := t.Context()
 	if Dryrun(ctx) {
 		t.Fatal("plain context should not be dryrun")
 	}
@@ -25,7 +25,7 @@ func TestDryrunContext(t *testing.T) {
 }
 
 func TestJobErrorContainer(t *testing.T) {
-	ctx := context.Background()
+	ctx := t.Context()
 	err := errors.New("job failed")
 
 	SetJobError(ctx, err)
@@ -40,34 +40,27 @@ func TestJobErrorContainer(t *testing.T) {
 	}
 }
 
-func TestLoggerAndHookContext(t *testing.T) {
-	ctx := context.Background()
-	if Logger(ctx) != logrus.StandardLogger() {
-		t.Fatal("plain context should use standard logger")
+func TestLoggerAndHandlerContext(t *testing.T) {
+	ctx := t.Context()
+	if Logger(ctx) != logging.Default() {
+		t.Fatal("plain context should use the default logger")
 	}
-	if LoggerHook(ctx) != nil {
-		t.Fatal("plain context should not have a logger hook")
+	if LoggerHandler(ctx) != nil {
+		t.Fatal("plain context should not have a logger handler")
+	}
+	if StepIDs(ctx) != nil {
+		t.Fatal("plain context should not have step IDs")
 	}
 
-	logger := logrus.New()
+	logger := logging.New(logtest.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")
+	handler := logtest.New()
+	ctx = WithLoggerHandler(ctx, handler)
+	if LoggerHandler(ctx) != handler {
+		t.Fatal("WithLoggerHandler should set handler")
 	}
 }
-
-type testHook struct{}
-
-func (testHook) Levels() []logrus.Level {
-	return logrus.AllLevels
-}
-
-func (testHook) Fire(*logrus.Entry) error {
-	return nil
-}

act/common/dryrun.go

@@ -14,13 +14,8 @@ const dryrunContextKeyVal = dryrunContextKey("dryrun")
 
 // Dryrun returns true if the current context is dryrun
 func Dryrun(ctx context.Context) bool {
-	val := ctx.Value(dryrunContextKeyVal)
-	if val != nil {
-		if dryrun, ok := val.(bool); ok {
-			return dryrun
-		}
-	}
-	return false
+	dryrun, _ := ctx.Value(dryrunContextKeyVal).(bool)
+	return dryrun
 }
 
 // WithDryrun adds a value to the context for dryrun

act/common/executor.go

@@ -9,7 +9,7 @@ import (
 	"fmt"
 	"runtime/debug"
 
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
 )
 
 // Executor define contract for the steps of a workflow
@@ -21,8 +21,7 @@ type Conditional func(ctx context.Context) bool
 // NewInfoExecutor is an executor that logs messages
 func NewInfoExecutor(format string, args ...any) Executor {
 	return func(ctx context.Context) error {
-		logger := Logger(ctx)
-		logger.Infof(format, args...)
+		Logger(ctx).Infof(format, args...)
 		return nil
 	}
 }
@@ -30,8 +29,7 @@ func NewInfoExecutor(format string, args ...any) Executor {
 // NewDebugExecutor is an executor that logs messages
 func NewDebugExecutor(format string, args ...any) Executor {
 	return func(ctx context.Context) error {
-		logger := Logger(ctx)
-		logger.Debugf(format, args...)
+		Logger(ctx).Debugf(format, args...)
 		return nil
 	}
 }
@@ -39,9 +37,7 @@ func NewDebugExecutor(format string, args ...any) Executor {
 // NewPipelineExecutor creates a new executor from a series of other executors
 func NewPipelineExecutor(executors ...Executor) Executor {
 	if len(executors) == 0 {
-		return func(ctx context.Context) error {
-			return nil
-		}
+		return NewErrorExecutor(nil)
 	}
 	var rtn Executor
 	for _, executor := range executors {
@@ -54,22 +50,6 @@ func NewPipelineExecutor(executors ...Executor) Executor {
 	return rtn
 }
 
-// NewConditionalExecutor creates a new executor based on conditions
-func NewConditionalExecutor(conditional Conditional, trueExecutor, falseExecutor Executor) Executor {
-	return func(ctx context.Context) error {
-		if conditional(ctx) {
-			if trueExecutor != nil {
-				return trueExecutor(ctx)
-			}
-		} else {
-			if falseExecutor != nil {
-				return falseExecutor(ctx)
-			}
-		}
-		return nil
-	}
-}
-
 // NewErrorExecutor creates a new executor that always errors out
 func NewErrorExecutor(err error) Executor {
 	return func(ctx context.Context) error {
@@ -77,6 +57,13 @@ func NewErrorExecutor(err error) Executor {
 	}
 }
 
+func RecoverPanic(err *error) { // defer directly in workers to keep stacks in host logs
+	if recovered := recover(); recovered != nil {
+		logging.Errorf("panic: %v\n%s", recovered, debug.Stack())
+		*err = fmt.Errorf("panic: %v", recovered)
+	}
+}
+
 // NewParallelExecutor creates a new executor from a parallel of other executors
 func NewParallelExecutor(parallel int, executors ...Executor) Executor {
 	if len(executors) == 0 {
@@ -90,34 +77,29 @@ func NewParallelExecutor(parallel int, executors ...Executor) Executor {
 		errs := make(chan error, len(executors))
 
 		if 1 > parallel {
-			log.Debugf("Parallel tasks (%d) below minimum, setting to 1", parallel)
+			logging.Debugf("Parallel tasks (%d) below minimum, setting to 1", parallel)
 			parallel = 1
 		}
 
-		log.Infof("NewParallelExecutor: Creating %d workers for %d executors", parallel, len(executors))
+		logging.Infof("NewParallelExecutor: Creating %d workers for %d executors", parallel, len(executors))
 
-		for i := 0; i < parallel; i++ {
-			go func(workerID int, work <-chan Executor, errs chan<- error) {
-				log.Debugf("Worker %d started", workerID)
+		for workerID := range parallel {
+			go func() {
+				logging.Debugf("Worker %d started", workerID)
 				taskCount := 0
 				for executor := range work {
 					taskCount++
-					log.Debugf("Worker %d executing task %d", workerID, taskCount)
+					logging.Debugf("Worker %d executing task %d", workerID, taskCount)
 					// Recover from panics in executors to avoid crashing the worker
 					// goroutine which would leave the runner process hung.
 					// https://gitea.com/gitea/runner/issues/371
 					errs <- func() (err error) {
-						defer func() {
-							if r := recover(); r != nil {
-								log.Errorf("panic in executor: %v\n%s", r, debug.Stack())
-								err = fmt.Errorf("panic: %v", r)
-							}
-						}()
+						defer RecoverPanic(&err)
 						return executor(ctx)
 					}()
 				}
-				log.Debugf("Worker %d finished (%d tasks executed)", workerID, taskCount)
-			}(i, work, errs)
+				logging.Debugf("Worker %d finished (%d tasks executed)", workerID, taskCount)
+			}()
 		}
 
 		for i := range executors {
@@ -166,12 +148,7 @@ func (e Executor) If(conditional Conditional) Executor {
 
 // IfNot only runs this executor if conditional is true
 func (e Executor) IfNot(conditional Conditional) Executor {
-	return func(ctx context.Context) error {
-		if !conditional(ctx) {
-			return e(ctx)
-		}
-		return nil
-	}
+	return e.If(func(ctx context.Context) bool { return !conditional(ctx) })
 }
 
 // IfBool only runs this executor if conditional is true
@@ -187,15 +164,11 @@ func (e Executor) Finally(finally Executor) Executor {
 		err := e(ctx)
 		err2 := finally(ctx)
 		if err2 != nil {
-			return fmt.Errorf("Error occurred running finally: %v (original error: %v)", err2, err)
+			if err != nil {
+				return fmt.Errorf("error occurred running finally: %w (original error: %w)", err2, err)
+			}
+			return fmt.Errorf("error occurred running finally: %w (original error: %v)", err2, err)
 		}
 		return err
 	}
 }
-
-// Not return an inverted conditional
-func (c Conditional) Not() Conditional {
-	return func(ctx context.Context) bool {
-		return !c(ctx)
-	}
-}

act/common/executor_test.go

@@ -7,8 +7,7 @@ package common
 import (
 	"context"
 	"errors"
-	"reflect"
-	"strings"
+	"fmt"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -18,79 +17,25 @@ import (
 )
 
 func TestNewWorkflow(t *testing.T) {
-	assert := assert.New(t)
+	ctx := t.Context()
+	require.NoError(t, NewPipelineExecutor()(ctx))
+	require.EqualError(t, NewErrorExecutor(errors.New("test error"))(ctx), "test error")
 
-	ctx := context.Background()
-
-	// empty
-	emptyWorkflow := NewPipelineExecutor()
-	assert.NoError(emptyWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
-
-	// error case
-	errorWorkflow := NewErrorExecutor(errors.New("test error"))
-	assert.Error(errorWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
-
-	// multiple success case
 	runcount := 0
-	successWorkflow := NewPipelineExecutor(
-		func(ctx context.Context) error {
-			runcount++
-			return nil
-		},
-		func(ctx context.Context) error {
-			runcount++
-			return nil
-		})
-	assert.NoError(successWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(2, runcount)
+	increment := func(_ctx context.Context) error {
+		runcount++
+		return nil
+	}
+	require.NoError(t, NewPipelineExecutor(increment, increment)(ctx))
+	assert.Equal(t, 2, runcount)
 }
 
-func TestNewConditionalExecutor(t *testing.T) {
-	assert := assert.New(t)
-
-	ctx := context.Background()
-
-	trueCount := 0
-	falseCount := 0
-
-	err := NewConditionalExecutor(func(ctx context.Context) bool {
-		return false
-	}, func(ctx context.Context) error {
-		trueCount++
-		return nil
-	}, func(ctx context.Context) error {
-		falseCount++
-		return nil
-	})(ctx)
-
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(0, trueCount)
-	assert.Equal(1, falseCount)
-
-	err = NewConditionalExecutor(func(ctx context.Context) bool {
-		return true
-	}, func(ctx context.Context) error {
-		trueCount++
-		return nil
-	}, func(ctx context.Context) error {
-		falseCount++
-		return nil
-	})(ctx)
-
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(1, trueCount)
-	assert.Equal(1, falseCount)
-}
-
-// concurrencyProbe returns an executor recording the peak number of concurrent copies. Copies
-// block until wantActive are in flight so the peak is exact without sleeping, and later copies
-// find the gate already open so the last one still finishes with no partner left.
 func concurrencyProbe(wantActive int32) (exec Executor, count, maxActive *atomic.Int32) {
 	var counted, active, peak atomic.Int32
 	var once sync.Once
 	reached := make(chan struct{})
 
-	return func(ctx context.Context) error {
+	return func(_ctx context.Context) error {
 		counted.Add(1)
 		running := active.Add(1)
 		for {
@@ -109,93 +54,72 @@ func concurrencyProbe(wantActive int32) (exec Executor, count, maxActive *atomic
 }
 
 func TestNewParallelExecutor(t *testing.T) {
-	ctx := context.Background()
-
-	exec, count, maxActive := concurrencyProbe(2)
-	require.NoError(t, NewParallelExecutor(2, exec, exec, exec)(ctx))
-	assert.Equal(t, int32(3), count.Load(), "should run all 3 executors")
-	assert.Equal(t, int32(2), maxActive.Load(), "should run at most 2 executors in parallel")
-
-	// parallelism below 1 falls back to a single worker
-	exec, count, maxActive = concurrencyProbe(1)
-	require.NoError(t, NewParallelExecutor(0, exec, exec, exec)(ctx))
-	assert.Equal(t, int32(3), count.Load(), "should run all 3 executors")
-	assert.Equal(t, int32(1), maxActive.Load(), "should run at most 1 executor in parallel")
+	for name, parallel := range map[string]int{"parallel": 2, "below minimum": 0} {
+		t.Run(name, func(t *testing.T) {
+			exec, count, maxActive := concurrencyProbe(int32(max(1, parallel)))
+			require.NoError(t, NewParallelExecutor(parallel, exec, exec, exec)(t.Context()))
+			assert.Equal(t, int32(3), count.Load())
+			assert.Equal(t, int32(max(1, parallel)), maxActive.Load())
+		})
+	}
 }
 
 func TestNewParallelExecutorEmpty(t *testing.T) {
 	assert := assert.New(t)
 
-	ctx := context.Background()
+	ctx := t.Context()
 	require.NoError(t, NewParallelExecutor(2)(ctx))
 
-	canceledCtx, cancel := context.WithCancel(context.Background())
+	canceledCtx, cancel := context.WithCancel(t.Context())
 	cancel()
 
 	err := NewParallelExecutor(2)(canceledCtx)
 	assert.ErrorIs(err, context.Canceled)
 }
 
-func TestNewParallelExecutorFailed(t *testing.T) {
-	assert := assert.New(t)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	count := 0
-	errorWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
-		count++
-		return errors.New("fake error")
-	})
-	err := NewParallelExecutor(1, errorWorkflow)(ctx)
-	assert.Equal(1, count)
-	assert.ErrorIs(context.Canceled, err)
-}
-
-func TestNewParallelExecutorCanceled(t *testing.T) {
-	assert := assert.New(t)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	errExpected := errors.New("fake error")
-
-	var count atomic.Int32
-	successWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
-		count.Add(1)
-		return nil
-	})
-	errorWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
-		count.Add(1)
-		return errExpected
-	})
-	err := NewParallelExecutor(3, errorWorkflow, successWorkflow, successWorkflow)(ctx)
-	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")
+func TestNewParallelExecutorRunsAllTasksAfterFailureOrCancellation(t *testing.T) {
+	for name, tc := range map[string]struct {
+		canceled        bool
+		parallel, tasks int
+	}{
+		"failure":              {false, 2, 5},
+		"canceled":             {true, 2, 5},
+		"canceled single task": {true, 1, 1},
+	} {
+		t.Run(name, func(t *testing.T) {
+			ctx, cancel := context.WithCancel(t.Context())
+			defer cancel()
+			if tc.canceled {
+				cancel()
+			}
+			var calls atomic.Int32
+			executors := make([]Executor, tc.tasks)
+			for i := range executors {
+				executors[i] = func(_ctx context.Context) error {
+					calls.Add(1)
+					if i == tc.tasks/2 {
+						return errors.New("fake error")
+					}
+					return nil
+				}
 			}
-			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")
+			err := NewParallelExecutor(tc.parallel, executors...)(ctx)
+			if tc.canceled {
+				require.ErrorIs(t, err, context.Canceled)
+			} else {
+				require.EqualError(t, err, "fake error")
+			}
+			assert.Equal(t, int32(tc.tasks), calls.Load())
+		})
+	}
 }
 
 func TestExecutorConditionalsAndFinally(t *testing.T) {
-	ctx := context.Background()
+	ctx := t.Context()
 	var calls []string
 	record := func(name string) Executor {
-		return func(ctx context.Context) error {
+		return func(_ctx context.Context) error {
 			calls = append(calls, name)
 			return nil
 		}
@@ -207,26 +131,17 @@ func TestExecutorConditionalsAndFinally(t *testing.T) {
 	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)
-	}
+	assert.Equal(t, []string{"if-true", "if-not", "if-bool", "main", "finally"}, calls)
 }
 
 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")
+	for _, mainErr := range []error{context.Canceled, nil} {
+		err := NewErrorExecutor(mainErr).Finally(NewErrorExecutor(finalErr))(t.Context())
+		require.EqualError(t, err, fmt.Sprintf("error occurred running finally: cleanup failed (original error: %v)", mainErr))
+		require.ErrorIs(t, err, finalErr)
+		if mainErr != nil {
+			require.ErrorIs(t, err, mainErr)
+		}
 	}
 }

act/common/git/fetch_action.go

@@ -0,0 +1,509 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package git
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"math/rand/v2"
+	"net"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"reflect"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"gitea.com/gitea/runner/act/common"
+)
+
+var actionFetches sync.Map
+
+var symlink = (*os.Root).Symlink
+
+var symlinkFallback = runtime.GOOS == "windows"
+
+const treeSizes = ".sizes" // beside the tree rather than in it, which is copied into job containers as it is
+
+type treeFile struct {
+	Name []byte // not a string, which JSON would turn into UTF-8, as git allows any bytes but NUL
+	Size int64
+}
+
+type actionFetch struct {
+	done     chan struct{}
+	dir, sha string
+	err      error
+	retry    bool // the leader was cancelled or panicked, so followers fetch themselves
+}
+
+var archiveRetryDelay = func(retryAfter string) time.Duration { // as actions/runner backs off
+	if seconds, err := strconv.Atoi(retryAfter); err == nil {
+		return min(max(time.Duration(seconds)*time.Second, 10*time.Second), 10*time.Minute)
+	}
+	return time.Duration(10+rand.IntN(21)) * time.Second
+}
+
+func FetchAction(ctx context.Context, input NewGitCloneExecutorInput) (string, string, error) { // input.Dir is one clone URL and ref's, holding a directory per commit
+	if !reflect.ValueOf(input).Comparable() {
+		return fetchAction(ctx, input)
+	}
+	for ctx.Err() == nil {
+		call := &actionFetch{done: make(chan struct{}), retry: true}
+		previous, loaded := actionFetches.LoadOrStore(input, call)
+		if !loaded {
+			func() {
+				defer func() { actionFetches.Delete(input); close(call.done) }()
+				call.dir, call.sha, call.err = fetchAction(ctx, input)
+				call.retry = ctx.Err() != nil
+			}()
+			if call.retry {
+				continue
+			}
+			return call.dir, call.sha, call.err
+		}
+		call, _ = previous.(*actionFetch)
+		select {
+		case <-ctx.Done():
+		case <-call.done:
+			if !call.retry && ctx.Err() == nil {
+				return call.dir, call.sha, call.err
+			}
+		}
+	}
+	return "", "", ctx.Err()
+}
+
+func fetchAction(ctx context.Context, input NewGitCloneExecutorInput) (string, string, error) {
+	unlock, err := AcquireCloneLock(ctx, input.Dir)
+	if err != nil {
+		return "", "", err
+	}
+	defer unlock()
+	if err := os.MkdirAll(input.Dir, 0o755); err != nil {
+		return "", "", err
+	}
+
+	tree := func(sha string) string { return filepath.Join(input.Dir, sha) }
+	record := filepath.Join(input.Dir, "ref")
+	data, _ := os.ReadFile(record)
+	sha, etag, _ := strings.Cut(string(data), "\n")
+	switch {
+	case !isFullObjectID(sha):
+		sha, etag = "", ""
+	case input.OfflineMode && exists(tree(sha)) && !exists(tree(sha)+treeSizes):
+		return tree(sha), sha, nil // from an older runner, with no sizes to check, so offline mode uses it as before
+	case !treeIntact(input.Dir, sha):
+		sha, etag = "", ""
+	case input.OfflineMode || isFullObjectID(input.Ref):
+		return tree(sha), sha, nil
+	}
+
+	newSha, newEtag, err := downloadArchive(ctx, input, sha, etag)
+	if err != nil && ctx.Err() == nil {
+		common.Logger(ctx).Debugf("Cloning %s@%s: %v", input.URL, input.Ref, err)
+		newEtag = ""
+		newSha, err = exportClone(ctx, input)
+	}
+	if err != nil {
+		return "", "", err
+	}
+	if newSha != sha || newEtag != etag {
+		if err := os.WriteFile(record, []byte(newSha+"\n"+newEtag), 0o600); err != nil {
+			return "", "", err
+		}
+	}
+	return tree(newSha), newSha, nil
+}
+
+func downloadArchive(ctx context.Context, input NewGitCloneExecutorInput, sha, etag string) (string, string, error) {
+	rewritten, err := gitOutput(ctx, "", "ls-remote", "--get-url", input.URL)
+	if err != nil {
+		return "", "", err
+	}
+	source, err := url.Parse(rewritten)
+	if err != nil || source.Scheme != "http" && source.Scheme != "https" || hexRefRegex.MatchString(input.Ref) && !isFullObjectID(input.Ref) { // only git tells a short commit from a branch
+		return "", "", errors.New("no archive")
+	}
+	archive := source.JoinPath("archive", input.Ref+".tar.gz")
+	if source.Host == "github.com" {
+		source.Host = "codeload.github.com"
+		archive = source.JoinPath("tar.gz", input.Ref)
+	}
+	client := &http.Client{Transport: input.Transport, Timeout: 5 * time.Minute, CheckRedirect: func(request *http.Request, via []*http.Request) error {
+		if len(via) >= 10 {
+			return errors.New("stopped after 10 redirects")
+		}
+		if request.URL.Host != via[0].URL.Host || request.URL.Scheme != via[0].URL.Scheme { // the token stays on its origin
+			request.Header.Del("Authorization")
+		}
+		return nil
+	}}
+	for attempt := 1; ; attempt++ {
+		newSha, newEtag, retryAfter, err := downloadArchiveOnce(ctx, client, archive.String(), input.Token, sha, etag, input.Dir)
+		if retryAfter == 0 || attempt == 3 || ctx.Err() != nil {
+			return newSha, newEtag, err
+		}
+		common.Logger(ctx).Warnf("Failed to download action '%s'. Error: %v. Back off %s before retry.", archive.Redacted(), err, retryAfter)
+		select {
+		case <-ctx.Done():
+			return "", "", ctx.Err()
+		case <-time.After(retryAfter):
+		}
+	}
+}
+
+func downloadArchiveOnce(ctx context.Context, client *http.Client, archive, token, sha, etag, dir string) (string, string, time.Duration, error) {
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, archive, nil)
+	if err != nil {
+		return "", "", 0, err
+	}
+	if etag != "" {
+		request.Header.Set("If-None-Match", etag)
+	}
+	if token != "" {
+		request.SetBasicAuth("token", token)
+	}
+	response, err := client.Do(request)
+	if err != nil {
+		var opErr *net.OpError
+		if errors.As(err, &opErr) && opErr.Op == "dial" {
+			return "", "", 0, err
+		}
+		return "", "", archiveRetryDelay(""), err
+	}
+	defer response.Body.Close()
+	switch status := response.StatusCode; {
+	case status == http.StatusNotModified && sha != "":
+		return sha, etag, 0, nil
+	case status == http.StatusOK:
+		newEtag := response.Header.Get("ETag")
+		gz, err := gzip.NewReader(response.Body)
+		if err == nil {
+			sha, err = extractTree(ctx, gz, dir, !strings.HasSuffix(newEtag, `-false"`)) // Gitea's mark of an unprefixed archive
+		}
+		var netErr net.Error
+		if errors.Is(err, io.ErrUnexpectedEOF) || errors.As(err, &netErr) {
+			return "", "", archiveRetryDelay(""), err
+		}
+		return sha, newEtag, 0, err
+	case status == http.StatusRequestTimeout || status == http.StatusTooManyRequests || status >= http.StatusInternalServerError:
+		return "", "", archiveRetryDelay(response.Header.Get("Retry-After")), errors.New(response.Status)
+	default:
+		return "", "", 0, errors.New(response.Status)
+	}
+}
+
+func exportClone(ctx context.Context, input NewGitCloneExecutorInput) (string, error) {
+	clone := input
+	clone.Dir = filepath.Join(input.Dir, "git")
+	sha, _, err := resolveClone(ctx, clone)
+	if err != nil || treeIntact(input.Dir, sha) {
+		return sha, err
+	}
+	archive, err := runGit(ctx, clone.Dir, nil, "archive", "--format=tar", sha)
+	if err != nil {
+		return "", err
+	}
+	_, err = extractTree(ctx, bytes.NewReader(archive), input.Dir, false)
+	return sha, err
+}
+
+func extractTree(ctx context.Context, archive io.Reader, dir string, strip bool) (string, error) { // into dir/<commit of the pax header>, strip dropping the directory wrapping the files
+	temp, err := os.MkdirTemp(dir, "tmp-")
+	if err != nil {
+		return "", err
+	}
+	defer os.RemoveAll(temp)
+	root, err := os.OpenRoot(temp)
+	if err != nil {
+		return "", err
+	}
+	defer root.Close()
+
+	sha := ""
+	sizes := map[string]int64{}
+	links := map[string]string{}
+	var deferred []string
+	reader := tar.NewReader(archive)
+	for {
+		header, err := reader.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return "", err
+		}
+		if header.Typeflag == tar.TypeXGlobalHeader {
+			if sha = header.PAXRecords["comment"]; isFullObjectID(sha) && treeIntact(dir, sha) {
+				return sha, nil
+			}
+			continue
+		}
+		name := header.Name
+		if strip {
+			_, name, _ = strings.Cut(name, "/")
+		}
+		if name = strings.TrimSuffix(name, "/"); name == "" {
+			continue
+		}
+		switch header.Typeflag {
+		case tar.TypeDir:
+			err = root.MkdirAll(name, 0o755)
+		case tar.TypeReg:
+			sizes[name], err = writeTreeFile(root, name, header.Mode, reader)
+		case tar.TypeSymlink:
+			links[filepath.Clean(name)] = header.Linkname
+			deferred = append(deferred, filepath.Clean(name))
+		}
+		if err != nil {
+			return "", err
+		}
+	}
+	if !isFullObjectID(sha) {
+		return "", errors.New("the archive names no commit")
+	}
+	linksByParent := map[string][]string{}
+	if symlinkFallback {
+		for name := range links {
+			linksByParent[filepath.Dir(name)] = append(linksByParent[filepath.Dir(name)], filepath.Base(name))
+		}
+	}
+	for requireTarget := symlinkFallback; len(deferred) > 0; {
+		unresolved := deferred[:0]
+		for _, name := range deferred {
+			if err := ctx.Err(); err != nil {
+				return "", err
+			}
+			if requireTarget {
+				if _, err := root.Stat(filepath.Dir(name) + string(filepath.Separator) + links[name]); err != nil {
+					unresolved = append(unresolved, name)
+					continue
+				}
+			}
+			if err := symlink(root, links[name], name); err == nil || !symlinkFallback {
+				if err != nil {
+					return "", err
+				}
+				continue
+			}
+			if err := copyTreeLink(ctx, root, name, links, linksByParent, sizes); err != nil {
+				return "", fmt.Errorf("materialize symlink %q: %w", filepath.ToSlash(name), err)
+			}
+		}
+		if len(unresolved) == len(deferred) {
+			requireTarget = false
+		}
+		deferred = unresolved
+	}
+	if err := root.Close(); err != nil {
+		return "", err
+	}
+	return sha, installTree(ctx, dir, sha, temp, sizes)
+}
+
+func resolveTreeLink(name string, links map[string]string) (string, bool) {
+	if !filepath.IsLocal(name) {
+		return "", false
+	}
+	parts := strings.Split(name, string(filepath.Separator))
+	var resolved []string
+	for count := 0; len(parts) > 0; {
+		part := parts[0]
+		parts = parts[1:]
+		switch part {
+		case "", ".":
+			continue
+		case "..":
+			if len(resolved) == 0 {
+				return "", false
+			}
+			resolved = resolved[:len(resolved)-1]
+			continue
+		}
+		target, ok := links[filepath.Join(append(resolved, part)...)]
+		if !ok {
+			resolved = append(resolved, part)
+			continue
+		}
+		count++
+		if target == "" || os.IsPathSeparator(target[0]) || filepath.VolumeName(target) != "" || count > 255 {
+			return "", false
+		}
+		parts = append(strings.Split(filepath.FromSlash(target), string(filepath.Separator)), parts...)
+	}
+	return filepath.Join(append([]string{"."}, resolved...)...), true
+}
+
+var (
+	errTreeLinkTarget = errors.New("unmaterializable symlink target")
+	errTreeLinkCycle  = fmt.Errorf("cyclic %w", errTreeLinkTarget)
+)
+
+func copyTreeLink(ctx context.Context, root *os.Root, name string, links map[string]string, linksByParent map[string][]string, sizes map[string]int64) error {
+	writeLinkText := func(destination, target string) error { // as git writes links it cannot create
+		if err := root.RemoveAll(destination); err != nil {
+			return err
+		}
+		for written := range sizes {
+			if written == destination || strings.HasPrefix(written, destination+string(filepath.Separator)) {
+				delete(sizes, written)
+			}
+		}
+		size, err := writeTreeFile(root, destination, 0o644, strings.NewReader(target))
+		sizes[destination] = size
+		return err
+	}
+	active := map[string]bool{}
+	var copyTarget func(string, string) error
+	copyTarget = func(source, destination string) error {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		source, ok := resolveTreeLink(source, links)
+		if !ok {
+			return errTreeLinkTarget
+		}
+		file, err := root.Open(source)
+		if err != nil {
+			if errors.Is(err, os.ErrNotExist) {
+				return errTreeLinkTarget
+			}
+			return err
+		}
+		defer file.Close()
+		info, err := file.Stat()
+		if err != nil {
+			return err
+		}
+		if info.Mode().IsRegular() {
+			sizes[destination], err = writeTreeFile(root, destination, int64(info.Mode().Perm()), file)
+			return err
+		}
+		if !info.IsDir() {
+			return errTreeLinkTarget
+		}
+		if active[source] {
+			return errTreeLinkCycle
+		}
+		active[source] = true
+		defer delete(active, source)
+		entries, err := file.ReadDir(-1)
+		if err != nil {
+			return err
+		}
+		children := map[string]bool{}
+		for _, entry := range entries {
+			children[entry.Name()] = true
+		}
+		for _, child := range linksByParent[source] {
+			children[child] = true
+		}
+		if err := root.MkdirAll(destination, info.Mode().Perm()); err != nil {
+			return err
+		}
+		for child := range children {
+			childSource, childDestination := filepath.Join(source, child), filepath.Join(destination, child)
+			err := copyTarget(childSource, childDestination)
+			if target, isLink := links[childSource]; isLink && errors.Is(err, errTreeLinkTarget) && !errors.Is(err, errTreeLinkCycle) {
+				err = writeLinkText(childDestination, target)
+			}
+			if err != nil {
+				return err
+			}
+		}
+		return nil
+	}
+	if err := copyTarget(name, name); !errors.Is(err, errTreeLinkTarget) {
+		return err
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	return writeLinkText(name, links[name])
+}
+
+var lockTree = AcquireCloneLock // replaced in tests to see installTree wait for a job holding the tree
+
+// installTree moves temp into place as dir/sha, replacing a tree that failed treeIntact.
+func installTree(ctx context.Context, dir, sha, temp string, sizes map[string]int64) error {
+	files := make([]treeFile, 0, len(sizes))
+	for name, size := range sizes {
+		files = append(files, treeFile{[]byte(name), size})
+	}
+	data, err := json.Marshal(files)
+	if err != nil {
+		return err
+	}
+	// Written before the swap: it describes the commit, not a copy of it, so it holds for whichever tree is left.
+	if err := os.WriteFile(filepath.Join(dir, sha+treeSizes), data, 0o600); err != nil { // a torn record fails treeIntact, so it needs no rename
+		return err
+	}
+	tree := filepath.Join(dir, sha)
+	if !exists(tree) {
+		return os.Rename(temp, tree)
+	}
+	stale, err := os.MkdirTemp(dir, "tmp-")
+	if err != nil {
+		return err
+	}
+	defer os.RemoveAll(stale)          // after the unlock, as no job reads the old tree once it is moved
+	unlock, err := lockTree(ctx, tree) // jobs copying the old tree hold it
+	if err != nil {
+		return err
+	}
+	defer unlock()
+	if err := os.Rename(tree, filepath.Join(stale, sha)); err != nil {
+		return err
+	}
+	return os.Rename(temp, tree)
+}
+
+// treeIntact reports whether dir/sha still holds each file extracted into it at the size it was written.
+// Only sizes are compared, not content: a stat per file is cheap enough for every job, hashing is not.
+func treeIntact(dir, sha string) bool {
+	data, err := os.ReadFile(filepath.Join(dir, sha+treeSizes))
+	if err != nil || !exists(filepath.Join(dir, sha)) {
+		return false
+	}
+	var files []treeFile
+	if json.Unmarshal(data, &files) != nil {
+		return false
+	}
+	for _, file := range files {
+		info, err := os.Lstat(filepath.Join(dir, sha, filepath.FromSlash(string(file.Name))))
+		if err != nil || !info.Mode().IsRegular() || info.Size() != file.Size {
+			return false
+		}
+	}
+	return true
+}
+
+func writeTreeFile(root *os.Root, name string, mode int64, content io.Reader) (int64, error) {
+	perm := os.FileMode(0o644)
+	if mode&0o111 != 0 {
+		perm = 0o755
+	}
+	file, err := root.OpenFile(name, os.O_CREATE|os.O_EXCL|os.O_WRONLY, perm)
+	if err != nil {
+		return 0, err
+	}
+	n, err := io.Copy(file, content)
+	return n, errors.Join(err, file.Close())
+}
+
+func exists(name string) bool {
+	_, err := os.Stat(name)
+	return err == nil
+}

act/common/git/fetch_action_test.go

@@ -0,0 +1,562 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package git
+
+import (
+	"archive/tar"
+	"bytes"
+	"context"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/cgi"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"gitea.com/gitea/runner/act/common"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestFetchAction(t *testing.T) {
+	original := archiveRetryDelay
+	archiveRetryDelay = func(_retryAfter string) time.Duration { return time.Nanosecond }
+	t.Cleanup(func() { archiveRetryDelay = original })
+
+	root := t.TempDir()
+	remote := filepath.Join(root, "org", "action")
+	require.NoError(t, gitCmd("init", "--initial-branch=main", remote))
+	require.NoError(t, os.WriteFile(filepath.Join(remote, "action.yml"), []byte("name: action\n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(remote, "run.sh"), []byte("#!/bin/sh\n"), 0o755))
+	require.NoError(t, os.Symlink("action.yml", filepath.Join(remote, "link")))
+	require.NoError(t, gitCmd("-C", remote, "add", "."))
+	require.NoError(t, gitCmd("-C", remote, "update-index", "--chmod=+x", "run.sh"))
+	require.NoError(t, gitCmd("-C", remote, "commit", "-m", "initial"))
+	require.NoError(t, gitCmd("-C", remote, "tag", "v1"))
+	expectedSha := gitRevParse(t, remote, "main")
+
+	gitPath, err := exec.LookPath("git")
+	require.NoError(t, err)
+	backend := &cgi.Handler{Path: gitPath, Args: []string{"http-backend"}, Env: []string{"GIT_PROJECT_ROOT=" + root, "GIT_HTTP_EXPORT_ALL=1"}}
+	var mu sync.Mutex
+	var archiveRequests []http.Header
+	var mirror *httptest.Server
+	archiveCache := map[string][]byte{}
+	requests, archives, failures := 0, "", 0
+	handler := http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		mu.Lock()
+		defer mu.Unlock()
+		requests++
+		ref, ok := strings.CutPrefix(request.URL.Path, "/org/action/archive/")
+		if !ok {
+			backend.ServeHTTP(writer, request)
+			return
+		}
+		archiveRequests = append(archiveRequests, request.Header.Clone())
+		switch {
+		case failures > 0:
+			failures--
+			writer.WriteHeader(http.StatusServiceUnavailable)
+			return
+		case archives == "none":
+			http.NotFound(writer, request)
+			return
+		case archives == "unreachable":
+			http.Redirect(writer, request, "http://127.0.0.1:1"+request.URL.Path, http.StatusFound)
+			return
+		case archives == "redirect" && request.Host != mirror.Listener.Addr().String():
+			http.Redirect(writer, request, mirror.URL+request.URL.Path, http.StatusFound)
+			return
+		}
+		sha, _ := gitOutput(request.Context(), remote, "rev-parse", strings.TrimSuffix(ref, ".tar.gz"))
+		etag := fmt.Sprintf(`W/"%s-tar.gz-%t"`, sha, archives != "unprefixed")
+		if request.Header.Get("If-None-Match") == etag {
+			writer.WriteHeader(http.StatusNotModified)
+			return
+		}
+		args := []string{"archive", "--format=tar.gz", sha}
+		if archives != "unprefixed" {
+			args = append(args, "--prefix=action/")
+		}
+		archiveKey := strings.Join(args, "\x00")
+		archive, ok := archiveCache[archiveKey]
+		if !ok {
+			archive, _ = runGit(request.Context(), remote, nil, args...)
+			archiveCache[archiveKey] = archive
+		}
+		writer.Header().Set("ETag", etag)
+		_, _ = writer.Write(archive)
+	})
+	server := httptest.NewServer(handler)
+	mirror = httptest.NewServer(handler)
+	t.Cleanup(server.Close)
+	t.Cleanup(mirror.Close)
+	serve := func(mode string, failing int) {
+		mu.Lock()
+		defer mu.Unlock()
+		requests, archives, failures, archiveRequests = 0, mode, failing, nil
+	}
+	served := func() (int, []http.Header) {
+		mu.Lock()
+		defer mu.Unlock()
+		return requests, append([]http.Header(nil), archiveRequests...)
+	}
+	newInput := func(ref string) NewGitCloneExecutorInput {
+		return NewGitCloneExecutorInput{URL: server.URL + "/org/action", Ref: ref, Dir: t.TempDir(), Token: "secret"}
+	}
+
+	t.Run("shares identical fetches and isolates cancellation, panics and differing inputs", func(t *testing.T) {
+		for _, scenario := range []string{"shared", "leader cancelled", "leader panics", "different token"} {
+			t.Run(scenario, func(t *testing.T) {
+				serve("prefixed", 0)
+				input := newInput("main")
+				started, release := make(chan struct{}), make(chan struct{})
+				releaseFetches := sync.OnceFunc(func() { close(release) })
+				t.Cleanup(releaseFetches)
+				var once sync.Once
+				var panicked atomic.Bool
+				transport := actionFetchTransport(func(request *http.Request) (*http.Response, error) {
+					once.Do(func() { close(started) })
+					select {
+					case <-request.Context().Done():
+						return nil, request.Context().Err()
+					case <-release:
+					}
+					if scenario == "leader panics" && panicked.CompareAndSwap(false, true) {
+						panic("broken archive")
+					}
+					return http.DefaultTransport.RoundTrip(request)
+				})
+				input.Transport = &transport
+				leaderCtx, cancelLeader := context.WithCancel(t.Context())
+				defer cancelLeader()
+				waiting := &actionFetchContext{Context: t.Context(), waiting: make(chan struct{})}
+				followerInput := input
+				expectedRequests := 1
+				if scenario == "different token" {
+					followerInput.Token, expectedRequests = "other", 2
+				}
+				leaderDone, followerDone := make(chan error, 1), make(chan error, 1)
+				fetch := func(ctx context.Context, input NewGitCloneExecutorInput, done chan<- error) {
+					var err error
+					defer func() { done <- err }()
+					defer common.RecoverPanic(&err)
+					var tree, sha string
+					if tree, sha, err = FetchAction(ctx, input); err == nil {
+						assert.Equal(t, expectedSha, sha)
+						assert.Equal(t, filepath.Join(input.Dir, sha), tree)
+					}
+				}
+				go fetch(leaderCtx, input, leaderDone)
+				<-started
+				go fetch(waiting, followerInput, followerDone)
+				<-waiting.waiting
+				if scenario == "leader cancelled" {
+					cancelLeader()
+					require.ErrorIs(t, <-leaderDone, context.Canceled)
+				}
+				releaseFetches()
+				switch scenario {
+				case "leader cancelled":
+				case "leader panics":
+					require.ErrorContains(t, <-leaderDone, "panic: broken archive")
+				default:
+					require.NoError(t, <-leaderDone)
+				}
+				require.NoError(t, <-followerDone)
+				_, headers := served()
+				assert.Len(t, headers, expectedRequests)
+				if scenario == "different token" {
+					assert.NotEqual(t, headers[0].Get("Authorization"), headers[1].Get("Authorization"))
+				}
+			})
+		}
+	})
+
+	t.Run("downloads, revalidates and follows a moved tag", func(t *testing.T) {
+		serve("prefixed", 0)
+		input := newInput("v1")
+		tree, sha, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		assert.Equal(t, expectedSha, sha)
+		assert.Equal(t, filepath.Join(input.Dir, sha), tree)
+		assert.NoDirExists(t, filepath.Join(tree, ".git"))
+		info, err := os.Stat(filepath.Join(tree, "run.sh"))
+		require.NoError(t, err)
+		if runtime.GOOS != "windows" {
+			assert.EqualValues(t, 0o755, info.Mode().Perm())
+		}
+		link, err := os.Readlink(filepath.Join(tree, "link"))
+		require.NoError(t, err)
+		assert.Equal(t, "action.yml", link)
+
+		again, _, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		assert.Equal(t, tree, again)
+
+		require.NoError(t, gitCmd("-C", remote, "commit", "--allow-empty", "-m", "moved"))
+		require.NoError(t, gitCmd("-C", remote, "tag", "--force", "v1"))
+		expectedSha = gitRevParse(t, remote, "v1")
+		moved, movedSha, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		assert.Equal(t, expectedSha, movedSha)
+		assert.NotEqual(t, tree, moved)
+		assert.FileExists(t, filepath.Join(tree, "action.yml"))
+
+		input.OfflineMode = true
+		_, offlineSha, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		assert.Equal(t, movedSha, offlineSha)
+		require.NoError(t, os.Truncate(filepath.Join(moved, "action.yml"), 4)) // fetched again, offline or not
+		_, _, err = FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		require.NoError(t, os.Remove(moved+treeSizes)) // from an older runner, used as it is offline
+		reused, _, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		assert.Equal(t, moved, reused)
+
+		requests, headers := served()
+		assert.Equal(t, 4, requests)
+		require.Len(t, headers, 4)
+		assert.Equal(t, "Basic "+base64.StdEncoding.EncodeToString([]byte("token:secret")), headers[0].Get("Authorization"))
+		assert.Empty(t, headers[0].Get("If-None-Match"))
+		assert.Equal(t, fmt.Sprintf(`W/"%s-tar.gz-true"`, sha), headers[1].Get("If-None-Match"))
+		assert.Equal(t, headers[1].Get("If-None-Match"), headers[2].Get("If-None-Match"))
+	})
+
+	t.Run("downloads a pinned commit once and rejects a short one", func(t *testing.T) {
+		serve("prefixed", 0)
+		sha := expectedSha
+		input := newInput(sha)
+		for range 2 {
+			tree, got, err := FetchAction(t.Context(), input)
+			require.NoError(t, err)
+			assert.Equal(t, sha, got)
+			assert.FileExists(t, filepath.Join(tree, "action.yml"))
+		}
+		_, _, err := FetchAction(t.Context(), newInput(sha[:7]))
+		require.ErrorIs(t, err, ErrShortRef)
+		_, headers := served()
+		assert.Len(t, headers, 1)
+		assert.NoDirExists(t, filepath.Join(input.Dir, "git"))
+	})
+
+	t.Run("downloads again over a tree whose files changed size or that has no record, not under a job copying it", func(t *testing.T) {
+		sha := gitRevParse(t, remote, "main")
+		for _, mode := range []string{"prefixed", "none"} {
+			serve(mode, 0)
+			input := newInput(sha)
+			tree, _, err := FetchAction(t.Context(), input)
+			require.NoError(t, err, mode)
+			yml := filepath.Join(tree, "action.yml")
+			require.NoError(t, os.WriteFile(filepath.Join(tree, "trampoline.js"), nil, 0o644)) // the runner's own, no damage
+			_, _, err = FetchAction(t.Context(), input)
+			require.NoError(t, err, mode)
+			for _, damage := range []func() error{
+				func() error { return os.Truncate(yml, 4) },
+				func() error { return os.Remove(tree + treeSizes) },
+			} {
+				require.NoError(t, damage(), mode)
+				_, _, err := FetchAction(t.Context(), input)
+				require.NoError(t, err, mode)
+				body, err := os.ReadFile(yml)
+				require.NoError(t, err, mode)
+				assert.Equal(t, "name: action\n", string(body), mode)
+			}
+			_, headers := served()
+			assert.Len(t, headers, 3, mode)
+		}
+
+		serve("prefixed", 0)
+		input := newInput(sha)
+		tree, _, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		yml := filepath.Join(tree, "action.yml")
+		require.NoError(t, os.Truncate(yml, 4))
+		unlock, err := AcquireCloneLock(t.Context(), tree)
+		require.NoError(t, err)
+		release := sync.OnceFunc(unlock)
+		defer release()
+		waiting := make(chan struct{})
+		lockTree = func(ctx context.Context, dir string) (func(), error) {
+			close(waiting)
+			return AcquireCloneLock(ctx, dir)
+		}
+		t.Cleanup(func() { lockTree = AcquireCloneLock })
+		done := make(chan error, 1)
+		go func() {
+			_, _, err := FetchAction(t.Context(), input)
+			done <- err
+		}()
+		select {
+		case err := <-done:
+			t.Fatalf("FetchAction replaced the tree without waiting for the job holding it: %v", err)
+		case <-waiting:
+		}
+		info, err := os.Stat(yml)
+		require.NoError(t, err)
+		assert.Equal(t, int64(4), info.Size(), "the tree a job holds is left alone")
+		release()
+		require.NoError(t, <-done)
+		body, err := os.ReadFile(yml)
+		require.NoError(t, err)
+		assert.Equal(t, "name: action\n", string(body))
+	})
+
+	t.Run("retries a failing download and drops the token on a redirect to another origin", func(t *testing.T) {
+		serve("redirect", 2)
+		input := newInput("main")
+		_, sha, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		assert.Equal(t, expectedSha, sha)
+		assert.NoDirExists(t, filepath.Join(input.Dir, "git"))
+		_, headers := served()
+		require.Len(t, headers, 4)
+		assert.NotEmpty(t, headers[2].Get("Authorization"))
+		assert.Empty(t, headers[3].Get("Authorization"))
+	})
+
+	t.Run("keeps an unprefixed archive whole, downloads where insteadOf points and exports a clone without an archive or from an unreachable host", func(t *testing.T) {
+		for _, mode := range []string{"unprefixed", "none", "unreachable"} {
+			serve(mode, 0)
+			tree, sha, err := FetchAction(t.Context(), newInput("main"))
+			require.NoError(t, err, mode)
+			assert.Equal(t, expectedSha, sha, mode)
+			assert.FileExists(t, filepath.Join(tree, "action.yml"), mode)
+			assert.NoDirExists(t, filepath.Join(tree, ".git"), mode)
+			_, headers := served()
+			assert.Len(t, headers, 1, mode)
+		}
+
+		serve("prefixed", 0)
+		config := filepath.Join(t.TempDir(), "gitconfig")
+		require.NoError(t, os.WriteFile(config, []byte("[url \""+server.URL+"/org/\"]\n\tinsteadOf = https://example.invalid/org/\n"), 0o644))
+		t.Setenv("GIT_CONFIG_GLOBAL", config)
+		input := newInput("main")
+		input.URL = "https://example.invalid/org/action"
+		_, sha, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		assert.Equal(t, expectedSha, sha)
+		_, headers := served()
+		assert.Len(t, headers, 1)
+		assert.NoDirExists(t, filepath.Join(input.Dir, "git"))
+	})
+}
+
+type actionFetchTransport func(*http.Request) (*http.Response, error)
+
+func (transport actionFetchTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+	return transport(request)
+}
+
+type actionFetchContext struct {
+	context.Context
+	waiting chan struct{}
+	once    sync.Once
+}
+
+func (ctx *actionFetchContext) Done() <-chan struct{} {
+	ctx.once.Do(func() { close(ctx.waiting) })
+	return ctx.Context.Done()
+}
+
+func TestExtractTreeConfinesEntries(t *testing.T) {
+	outside := t.TempDir()
+	for name, entries := range map[string][]*tar.Header{
+		"parent path":       {{Name: "../escape", Typeflag: tar.TypeReg}},
+		"through a symlink": {{Name: "out", Typeflag: tar.TypeSymlink, Linkname: outside}, {Name: "out/escape", Typeflag: tar.TypeReg}},
+	} {
+		t.Run(name, func(t *testing.T) {
+			var archive bytes.Buffer
+			writer := tar.NewWriter(&archive)
+			require.NoError(t, writer.WriteHeader(&tar.Header{Typeflag: tar.TypeXGlobalHeader, PAXRecords: map[string]string{"comment": strings.Repeat("a", 40)}}))
+			for _, entry := range entries {
+				require.NoError(t, writer.WriteHeader(entry))
+			}
+			require.NoError(t, writer.Close())
+
+			dir := t.TempDir()
+			_, err := extractTree(t.Context(), &archive, dir, false)
+			require.Error(t, err)
+			assert.NoFileExists(t, filepath.Join(dir, "escape"))
+			assert.NoFileExists(t, filepath.Join(outside, "escape"))
+		})
+	}
+}
+
+func TestExtractTreeCopiesDeferredLinks(t *testing.T) {
+	originalSymlink, originalFallback := symlink, symlinkFallback
+	symlink = func(_root *os.Root, _target, _name string) error { return errors.New("symlink privilege unavailable") }
+	symlinkFallback = true
+	t.Cleanup(func() { symlink, symlinkFallback = originalSymlink, originalFallback })
+
+	for _, test := range []struct {
+		name  string
+		links [][2]string
+		files []string
+		text  bool
+	}{
+		{name: "file chain", links: [][2]string{{"index.js", "entry.js"}, {"entry.js", "dist/index.js"}}, files: []string{"index.js", "entry.js"}},
+		{name: "directory chain", links: [][2]string{{"lib", "bundle"}, {"bundle", "dist"}, {"dist/entry.js", "index.js"}}, files: []string{"lib/index.js", "lib/entry.js", "lib/nested/index.js", "bundle/index.js", "bundle/entry.js", "bundle/nested/index.js"}},
+		{name: "directory in target path", links: [][2]string{{"index.js", "bundle/nested/index.js"}, {"bundle", "dist"}}, files: []string{"index.js", "bundle/nested/index.js"}},
+		{name: "parent after directory link", links: [][2]string{{"index.js", "bundle/../index.js"}, {"bundle", "dist/nested"}}, files: []string{"index.js", "bundle/index.js"}},
+		{name: "outside", links: [][2]string{{"index.js", "../outside.js"}}, text: true},
+		{name: "absolute", links: [][2]string{{"index.js", t.TempDir()}}, text: true},
+		{name: "dangling", links: [][2]string{{"index.js", "missing.js"}}, text: true},
+		{name: "dangling child of directory link", links: [][2]string{{"lib", "dist"}, {"dist/optional", "missing.js"}}, files: []string{"lib/index.js", "lib/nested/index.js"}},
+		{name: "cycle", links: [][2]string{{"index.js", "entry.js"}, {"entry.js", "index.js"}}, text: true},
+		{name: "directory cycle", links: [][2]string{{"dist/loop", "."}}, text: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			sha := strings.Repeat("a", 40)
+			var archive bytes.Buffer
+			writer := tar.NewWriter(&archive)
+			require.NoError(t, writer.WriteHeader(&tar.Header{Typeflag: tar.TypeXGlobalHeader, PAXRecords: map[string]string{"comment": sha}}))
+			require.NoError(t, writer.WriteHeader(&tar.Header{Name: "dist", Typeflag: tar.TypeDir, Mode: 0o755}))
+			require.NoError(t, writer.WriteHeader(&tar.Header{Name: "dist/nested", Typeflag: tar.TypeDir, Mode: 0o755}))
+			for _, link := range test.links {
+				require.NoError(t, writer.WriteHeader(&tar.Header{Name: link[0], Typeflag: tar.TypeSymlink, Linkname: link[1]}))
+			}
+			content := "console.log('action');\n"
+			for _, name := range []string{"dist/index.js", "dist/nested/index.js"} {
+				require.NoError(t, writer.WriteHeader(&tar.Header{Name: name, Typeflag: tar.TypeReg, Mode: 0o755, Size: int64(len(content))}))
+				_, err := writer.Write([]byte(content))
+				require.NoError(t, err)
+			}
+			require.NoError(t, writer.Close())
+
+			dir := t.TempDir()
+			_, err := extractTree(t.Context(), &archive, dir, false)
+			require.NoError(t, err)
+			assert.True(t, treeIntact(dir, sha))
+			if test.text {
+				for _, link := range test.links {
+					data, err := os.ReadFile(filepath.Join(dir, sha, link[0]))
+					require.NoError(t, err)
+					assert.Equal(t, link[1], string(data))
+					info, err := os.Lstat(filepath.Join(dir, sha, link[0]))
+					require.NoError(t, err)
+					assert.True(t, info.Mode().IsRegular())
+				}
+			}
+			for _, name := range test.files {
+				data, err := os.ReadFile(filepath.Join(dir, sha, name))
+				require.NoError(t, err)
+				assert.Equal(t, content, string(data))
+				info, err := os.Lstat(filepath.Join(dir, sha, name))
+				require.NoError(t, err)
+				assert.True(t, info.Mode().IsRegular())
+				if runtime.GOOS != "windows" {
+					assert.Equal(t, os.FileMode(0o755), info.Mode().Perm())
+				}
+				require.NoError(t, os.WriteFile(filepath.Join(dir, sha, name), nil, 0o644))
+				assert.False(t, treeIntact(dir, sha), name)
+				require.NoError(t, os.WriteFile(filepath.Join(dir, sha, name), []byte(content), 0o755))
+			}
+		})
+	}
+}
+
+func TestTreeIntactFindsNamesThatAreNotUTF8(t *testing.T) {
+	if runtime.GOOS != "linux" {
+		t.Skip("macOS and Windows store no name that is not UTF-8")
+	}
+	sha := strings.Repeat("a", 40)
+	var archive bytes.Buffer
+	writer := tar.NewWriter(&archive)
+	require.NoError(t, writer.WriteHeader(&tar.Header{Typeflag: tar.TypeXGlobalHeader, PAXRecords: map[string]string{"comment": sha}}))
+	require.NoError(t, writer.WriteHeader(&tar.Header{Name: "caf\xe9.js", Typeflag: tar.TypeReg, Mode: 0o644, Size: 1, Format: tar.FormatGNU}))
+	_, err := writer.Write([]byte("x"))
+	require.NoError(t, err)
+	require.NoError(t, writer.Close())
+
+	dir := t.TempDir()
+	_, err = extractTree(t.Context(), &archive, dir, false)
+	require.NoError(t, err)
+	require.FileExists(t, filepath.Join(dir, sha, "caf\xe9.js"))
+	assert.True(t, treeIntact(dir, sha))
+}
+
+func TestExtractTreeCreatesLinksInPlatformOrder(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("requires symlink privileges")
+	}
+	original, originalFallback := symlink, symlinkFallback
+	var created []string
+	symlink = func(root *os.Root, target, name string) error {
+		created = append(created, name)
+		return root.Symlink(target, name)
+	}
+	t.Cleanup(func() { symlink, symlinkFallback = original, originalFallback })
+
+	var archive bytes.Buffer
+	writer := tar.NewWriter(&archive)
+	require.NoError(t, writer.WriteHeader(&tar.Header{Typeflag: tar.TypeXGlobalHeader, PAXRecords: map[string]string{"comment": strings.Repeat("a", 40)}}))
+	for _, entry := range []*tar.Header{
+		{Name: "a", Typeflag: tar.TypeSymlink, Linkname: "b"},
+		{Name: "b", Typeflag: tar.TypeSymlink, Linkname: "dist"},
+		{Name: "dangling", Typeflag: tar.TypeSymlink, Linkname: "missing"},
+		{Name: "dist", Typeflag: tar.TypeDir, Mode: 0o755},
+	} {
+		require.NoError(t, writer.WriteHeader(entry))
+	}
+	require.NoError(t, writer.Close())
+	for _, test := range []struct {
+		name     string
+		fallback bool
+		want     []string
+	}{
+		{name: "native", want: []string{"a", "b", "dangling"}},
+		{name: "fallback", fallback: true, want: []string{"b", "a", "dangling"}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			symlinkFallback = test.fallback
+			created = nil
+			_, err := extractTree(t.Context(), bytes.NewReader(archive.Bytes()), t.TempDir(), false)
+			require.NoError(t, err)
+			assert.Equal(t, test.want, created)
+		})
+	}
+}
+
+func TestCopyTreeLinkCancellationBetweenEntries(t *testing.T) {
+	root, err := os.OpenRoot(t.TempDir())
+	require.NoError(t, err)
+	defer root.Close()
+	require.NoError(t, root.Mkdir("source", 0o755))
+	for _, name := range []string{"first", "second"} {
+		_, err := writeTreeFile(root, filepath.Join("source", name), 0o644, strings.NewReader("content"))
+		require.NoError(t, err)
+	}
+	sizes := map[string]int64{}
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+	observed := &treeCopyContext{Context: ctx, check: func() {
+		if len(sizes) == 1 {
+			cancel()
+		}
+	}}
+	require.ErrorIs(t, copyTreeLink(observed, root, "copy", map[string]string{"copy": "source"}, nil, sizes), context.Canceled)
+	assert.Len(t, sizes, 1)
+}
+
+type treeCopyContext struct {
+	context.Context
+	check func()
+}
+
+func (ctx *treeCopyContext) Err() error {
+	ctx.check()
+	return ctx.Context.Err()
+}

act/common/git/git.go

@@ -5,46 +5,71 @@
 package git
 
 import (
+	"bytes"
 	"context"
+	"crypto/sha256"
+	"encoding/base64"
 	"errors"
 	"fmt"
 	"io"
+	"net/http"
+	"net/url"
 	"os"
+	"os/exec"
 	"path"
+	"path/filepath"
 	"regexp"
+	"runtime"
+	"slices"
+	"strconv"
 	"strings"
-	"sync"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/common/logging"
 	"gitea.com/gitea/runner/internal/pkg/lock"
-
-	"github.com/go-git/go-git/v5"
-	"github.com/go-git/go-git/v5/config"
-	"github.com/go-git/go-git/v5/plumbing"
-	"github.com/go-git/go-git/v5/plumbing/storer"
-	"github.com/go-git/go-git/v5/plumbing/transport/http"
-	"github.com/mattn/go-isatty"
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/internal/pkg/process"
 )
 
 var (
 	codeCommitHTTPRegex = regexp.MustCompile(`^https?://git-codecommit\.(.+)\.amazonaws.com/v1/repos/(.+)$`)
 	codeCommitSSHRegex  = regexp.MustCompile(`ssh://git-codecommit\.(.+)\.amazonaws.com/v1/repos/(.+)$`)
-	githubHTTPRegex     = regexp.MustCompile(`^https?://.*github.com.*/(.+)/(.+?)(?:.git)?$`)
-	githubSSHRegex      = regexp.MustCompile(`github.com[:/](.+)/(.+?)(?:.git)?$`)
+	hexRefRegex         = regexp.MustCompile(`^[0-9a-fA-F]+$`)
+
+	LocalEnvVars = []string{ // `git rev-parse --local-env-vars`, inherited ones point git at another repository
+		"GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT", "GIT_OBJECT_DIRECTORY",
+		"GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE", "GIT_INDEX_FILE", "GIT_NO_REPLACE_OBJECTS",
+		"GIT_REPLACE_REF_BASE", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_COMMON_DIR",
+	}
 
 	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")
 )
 
-// AcquireCloneLock returns an unlock function after locking the per-directory mutex for dir.
-// Only concurrent operations targeting the same directory are serialized; clones into different directories run in parallel.
-// Callers reading files inside dir (e.g. tarring a checked-out action into a job container) must hold this lock too,
-// otherwise a concurrent NewGitCloneExecutor on the same dir can mutate the worktree mid-read.
-func AcquireCloneLock(dir string) func() {
-	return cloneLocks.Lock(dir)
+// AcquireCloneLock serializes access to dir across runner processes, or within this one where no lock file can be created. Readers of dir must hold it too.
+func AcquireCloneLock(ctx context.Context, dir string) (func(), error) {
+	dir = filepath.Clean(dir)
+	if runtime.GOOS == "plan9" {
+		return cloneLocks.Lock(dir), nil
+	}
+	if err := os.MkdirAll(filepath.Dir(dir), 0o755); err != nil {
+		return nil, err
+	}
+	for {
+		release, err := lock.TryLock(dir)
+		if err == nil {
+			return func() { _ = release() }, nil
+		}
+		if !errors.Is(err, lock.ErrLocked) {
+			return cloneLocks.Lock(dir), nil
+		}
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(50 * time.Millisecond):
+		}
+	}
 }
 
 type Error struct {
@@ -52,199 +77,97 @@ type Error struct {
 	commit string
 }
 
-func (e *Error) Error() string {
-	return e.err.Error()
-}
-
-func (e *Error) Unwrap() error {
-	return e.err
-}
-
-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
+func (e *Error) Error() string  { return e.err.Error() }
+func (e *Error) Unwrap() error  { return e.err }
+func (e *Error) Commit() string { return e.commit }
 
 // 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) {
+func FindGitRevision(ctx context.Context, file string) (string, error) {
 	logger := common.Logger(ctx)
-
-	gitDir, err := git.PlainOpenWithOptions(
-		file,
-		&git.PlainOpenOptions{
-			DetectDotGit:          true,
-			EnableDotGitCommonDir: true,
-		},
-	)
+	sha, err := gitOutput(ctx, file, "rev-parse", "--verify", "HEAD^{commit}")
 	if err != nil {
 		logger.WithError(err).Error("path", file, "not located inside a git repository")
-		return "", "", err
+		return "", err
 	}
-
-	head, err := gitDir.Reference(plumbing.HEAD, true)
-	if err != nil {
-		return "", "", err
+	if len(sha) < 7 {
+		return "", errors.New("HEAD could not be resolved")
 	}
-
-	if head.Hash().IsZero() {
-		return "", "", errors.New("HEAD sha1 could not be resolved")
-	}
-
-	hash := head.Hash().String()
-
-	logger.Debugf("Found revision: %s", hash)
-	return hash[:7], strings.TrimSpace(hash), nil
+	logger.Debugf("Found revision: %s", sha)
+	return sha, nil
 }
 
 // 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)
+	revision, err := FindGitRevision(ctx, file)
 	if err != nil {
 		return "", err
 	}
+	logger.Debugf("HEAD points to '%s'", revision)
 
-	logger.Debugf("HEAD points to '%s'", ref)
-
-	// Prefer the git library to iterate over the references and find a matching tag or branch.
-	refTag := ""
-	refBranch := ""
-	repo, err := git.PlainOpenWithOptions(
-		file,
-		&git.PlainOpenOptions{
-			DetectDotGit:          true,
-			EnableDotGitCommonDir: true,
-		},
-	)
+	refs, err := gitOutput(ctx, file, "for-each-ref", "--points-at=HEAD", "--format=%(refname)", "refs/tags", "refs/heads")
 	if err != nil {
 		return "", err
 	}
-
-	iter, err := repo.References()
-	if err != nil {
-		return "", err
-	}
-
-	// find the reference that matches the revision's has
-	err = iter.ForEach(func(r *plumbing.Reference) error {
-		/* tags and branches will have the same hash
-		 * when a user checks out a tag, it is not mentioned explicitly
-		 * in the go-git package, we must identify the revision
-		 * then check if any tag matches that revision,
-		 * if so then we checked out a tag
-		 * else we look for branches and if matches,
-		 * it means we checked out a branch
-		 *
-		 * If a branches matches first we must continue and check all tags (all references)
-		 * in case we match with a tag later in the interation
-		 */
-		if r.Hash().String() == ref {
-			if r.Name().IsTag() {
-				refTag = r.Name().String()
-			}
-			if r.Name().IsBranch() {
-				refBranch = r.Name().String()
-			}
+	var tag, branch string
+	for ref := range strings.FieldsSeq(refs) {
+		switch {
+		case strings.HasPrefix(ref, "refs/tags/"):
+			tag = ref
+		case strings.HasPrefix(ref, "refs/heads/"):
+			branch = ref
 		}
-
-		// we found what we where looking for
-		if refTag != "" && refBranch != "" {
-			return storer.ErrStop
-		}
-
-		return nil
-	})
-	if err != nil {
-		return "", err
 	}
-
-	// order matters here see above comment.
-	if refTag != "" {
-		return refTag, nil
+	if tag != "" {
+		return tag, nil
 	}
-	if refBranch != "" {
-		return refBranch, nil
+	if branch != "" {
+		return branch, nil
 	}
-
-	return "", fmt.Errorf("failed to identify reference (tag/branch) for the checked-out revision '%s'", ref)
+	return "", fmt.Errorf("failed to identify reference (tag/branch) for the checked-out revision '%s'", revision)
 }
 
 // FindGithubRepo get the repo
-func FindGithubRepo(ctx context.Context, file, githubInstance, remoteName string) (string, error) {
-	goGitMu.Lock()
-	defer goGitMu.Unlock()
-	if remoteName == "" {
-		remoteName = "origin"
-	}
-
-	url, err := findGitRemoteURL(ctx, file, remoteName)
+func FindGithubRepo(ctx context.Context, file string) (string, error) {
+	url, err := findGitRemoteURL(ctx, file)
 	if err != nil {
 		return "", err
 	}
-	_, slug, err := findGitSlug(url, githubInstance)
-	return slug, err
+	return findGitSlug(url)
 }
 
-func findGitRemoteURL(_ context.Context, file, remoteName string) (string, error) {
-	repo, err := git.PlainOpenWithOptions(
-		file,
-		&git.PlainOpenOptions{
-			DetectDotGit:          true,
-			EnableDotGitCommonDir: true,
-		},
-	)
+func findGitRemoteURL(ctx context.Context, file string) (string, error) {
+	urls, err := gitOutput(ctx, file, "config", "--get-all", "remote.origin.url") // `remote get-url` applies insteadOf
 	if err != nil {
 		return "", err
 	}
-
-	remote, err := repo.Remote(remoteName)
-	if err != nil {
-		return "", err
+	if urls == "" {
+		return "", errors.New("remote 'origin' exists but has no URL")
 	}
-
-	if len(remote.Config().URLs) < 1 {
-		return "", fmt.Errorf("remote '%s' exists but has no URL", remoteName)
-	}
-
-	return remote.Config().URLs[0], nil
+	url, _, _ := strings.Cut(urls, "\n")
+	return url, nil
 }
 
-func findGitSlug(url, githubInstance string) (string, string, error) { //nolint:unparam // pre-existing issue from nektos/act
-	if matches := codeCommitHTTPRegex.FindStringSubmatch(url); matches != nil {
-		return "CodeCommit", matches[2], nil
-	} else if matches := codeCommitSSHRegex.FindStringSubmatch(url); matches != nil {
-		return "CodeCommit", matches[2], nil
-	} else if matches := githubHTTPRegex.FindStringSubmatch(url); matches != nil {
-		return "GitHub", fmt.Sprintf("%s/%s", matches[1], matches[2]), nil
-	} else if matches := githubSSHRegex.FindStringSubmatch(url); matches != nil {
-		return "GitHub", fmt.Sprintf("%s/%s", matches[1], matches[2]), nil
-	} else if githubInstance != "github.com" {
-		gheHTTPRegex := regexp.MustCompile(fmt.Sprintf(`^https?://%s/(.+)/(.+?)(?:.git)?$`, githubInstance))
-		gheSSHRegex := regexp.MustCompile(githubInstance + "[:/](.+)/(.+?)(?:.git)?$")
-		if matches := gheHTTPRegex.FindStringSubmatch(url); matches != nil {
-			return "GitHubEnterprise", fmt.Sprintf("%s/%s", matches[1], matches[2]), nil
-		} else if matches := gheSSHRegex.FindStringSubmatch(url); matches != nil {
-			return "GitHubEnterprise", fmt.Sprintf("%s/%s", matches[1], matches[2]), nil
-		}
+func findGitSlug(remoteURL string) (string, error) {
+	if matches := codeCommitHTTPRegex.FindStringSubmatch(remoteURL); matches != nil {
+		return matches[2], nil
+	} else if matches := codeCommitSSHRegex.FindStringSubmatch(remoteURL); matches != nil {
+		return matches[2], nil
 	}
-	return "", url, nil
+	if host, repoPath, ok := strings.Cut(remoteURL, ":"); ok && filepath.VolumeName(remoteURL) == "" && !strings.Contains(host, "/") && !strings.HasPrefix(repoPath, "//") {
+		remoteURL = "ssh://" + host + "/" + repoPath // scp-like [user@]host:path
+	}
+	parsed, err := url.Parse(remoteURL)
+	if err != nil {
+		return "", errors.New("cannot parse the origin remote URL")
+	}
+	owner, repo := path.Split(strings.TrimSuffix(strings.Trim(parsed.Path, "/"), ".git"))
+	owner = path.Base(owner)
+	if parsed.Host == "" || repo == "" || owner == "." || owner == "/" {
+		return "", errors.New("cannot determine owner and repository from the origin remote URL")
+	}
+	return owner + "/" + repo, nil
 }
 
 // NewGitCloneExecutorInput the input for the NewGitCloneExecutor
@@ -259,284 +182,318 @@ type NewGitCloneExecutorInput struct {
 	// 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
+	InsecureSkipTLS               bool
+	ClientCertFile, ClientKeyFile string            // PEM, absolute as git runs in other directories
+	Transport                     http.RoundTripper // for FetchAction's archive downloads, nil for http.DefaultTransport
 }
 
-// CloneIfRequired returns the repository and a boolean indicating whether an existing local clone was reused.
-func CloneIfRequired(ctx context.Context, refName plumbing.ReferenceName, input NewGitCloneExecutorInput, logger log.FieldLogger) (*git.Repository, bool, error) {
-	r, err := git.PlainOpen(input.Dir)
+// CloneIfRequired reports whether an existing local clone was reused.
+func CloneIfRequired(ctx context.Context, input NewGitCloneExecutorInput, logger *logging.Logger) (bool, error) {
+	var origin string
+	_, err := os.Stat(filepath.Join(input.Dir, ".git")) // without it git would discover a repository around Dir
 	if err == nil {
-		// Verify the cached clone still points to the resolved URL before reusing it.
-		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)
-		}
+		origin, err = findGitRemoteURL(ctx, input.Dir)
 	}
-
-	var progressWriter io.Writer
-	if isatty.IsTerminal(os.Stdout.Fd()) || isatty.IsCygwinTerminal(os.Stdout.Fd()) {
-		if entry, ok := logger.(*log.Entry); ok {
-			progressWriter = entry.WriterLevel(log.DebugLevel)
-		} else if lgr, ok := logger.(*log.Logger); ok {
-			progressWriter = lgr.WriterLevel(log.DebugLevel)
-		} else {
-			log.Errorf("Unable to get writer from logger (type=%T)", logger)
-			progressWriter = os.Stdout
-		}
+	if err == nil && origin == input.URL {
+		return true, nil
 	}
-
-	cloneOptions := git.CloneOptions{
-		URL:      input.URL,
-		Progress: progressWriter,
-
-		InsecureSkipTLS: input.InsecureSkipTLS, // For Gitea
+	if ctxErr := ctx.Err(); ctxErr != nil { // a cancelled origin lookup must not discard a valid clone
+		return false, ctxErr
 	}
-	if input.Token != "" {
-		cloneOptions.Auth = &http.BasicAuth{
-			Username: "token",
-			Password: input.Token,
-		}
+	if err == nil {
+		logger.Debugf("Removing cached clone at %s because origin URL changed from %s to %s", input.Dir, origin, input.URL)
+	} else if _, statErr := os.Stat(input.Dir); statErr == nil {
+		logger.Debugf("Removing cached clone at %s because origin cannot be read: %v", input.Dir, err)
 	}
-
-	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
+	if err := os.RemoveAll(input.Dir); err != nil {
+		return false, fmt.Errorf("remove cached clone %s: %w", input.Dir, err)
 	}
-
-	if err = os.Chmod(input.Dir, 0o755); err != nil {
-		return nil, false, err
+	if err := clone(ctx, input); err != nil {
+		return false, err
 	}
-
-	return r, false, nil
-}
-
-func gitOptions(token string) (fetchOptions git.FetchOptions, pullOptions git.PullOptions) {
-	fetchOptions.RefSpecs = []config.RefSpec{"refs/*:refs/*", "HEAD:refs/heads/HEAD"}
-	fetchOptions.Force = true
-	pullOptions.Force = true
-
-	if token != "" {
-		auth := &http.BasicAuth{
-			Username: "token",
-			Password: token,
-		}
-		fetchOptions.Auth = auth
-		pullOptions.Auth = auth
+	if err := os.Chmod(input.Dir, 0o755); err != nil {
+		return false, err
 	}
-
-	return fetchOptions, pullOptions
+	return false, nil
 }
 
 // NewGitCloneExecutor creates an executor to clone git repos
 func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
 		logger := common.Logger(ctx)
-		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.Infof("git clone '%s' # ref=%s", input.URL, input.Ref)
 		logger.Debugf("  cloning %s to %s", input.URL, input.Dir)
-
-		defer AcquireCloneLock(input.Dir)()
-
-		refName := plumbing.ReferenceName("refs/heads/" + input.Ref)
-		r, reused, err := CloneIfRequired(ctx, refName, input, logger)
+		unlock, err := AcquireCloneLock(ctx, input.Dir)
 		if err != nil {
 			return err
 		}
+		defer unlock()
 
-		isOfflineMode := input.OfflineMode
-
-		// fetch latest changes
-		fetchOptions, pullOptions := gitOptions(input.Token)
-
-		if input.InsecureSkipTLS { // For Gitea
-			fetchOptions.InsecureSkipTLS = true
-			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) {
-				return err
-			}
-		}
-
-		var hash *plumbing.Hash
-		rev := plumbing.Revision(input.Ref)
-		if hash, err = r.ResolveRevision(rev); err != nil {
-			// ResolveRevision returns a nil hash on error, and a branch ref legitimately fails
-			// here (no local refs/heads/<ref>); the duck-typing below resolves it.
-			logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
-		} else if hash.String() != input.Ref && strings.HasPrefix(hash.String(), input.Ref) {
-			return &Error{
-				err:    ErrShortRef,
-				commit: hash.String(),
-			}
-		}
-
-		// At this point we need to know if it's a tag or a branch
-		// And the easiest way to do it is duck typing
-		//
-		// If err is nil, it's a tag so let's proceed with that hash like we would if
-		// it was a sha
-		refType := "tag"
-		rev = plumbing.Revision(path.Join("refs", "tags", input.Ref))
-		if _, err := r.Tag(input.Ref); errors.Is(err, git.ErrTagNotFound) {
-			rName := plumbing.ReferenceName(path.Join("refs", "remotes", "origin", input.Ref))
-			if _, err := r.Reference(rName, false); errors.Is(err, plumbing.ErrReferenceNotFound) {
-				refType = "sha"
-				rev = plumbing.Revision(input.Ref)
-			} else {
-				refType = "branch"
-				rev = plumbing.Revision(rName)
-			}
-		}
-
-		if hash, err = r.ResolveRevision(rev); err != nil {
-			logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
+		resolved, reused, err := resolveClone(ctx, input)
+		if err != nil {
 			return err
 		}
-
-		var w *git.Worktree
-		if w, err = r.Worktree(); err != nil {
-			return err
+		if _, err := runGit(ctx, input.Dir, nil, "checkout", "--force", "--detach", resolved); err != nil {
+			return fmt.Errorf("checkout %s: %w", resolved, err)
 		}
-
-		// If the hash resolved doesn't match the ref provided in a workflow then we're
-		// using a branch or tag ref, not a sha
-		//
-		// Repos on disk point to commit hashes, and need to checkout input.Ref before
-		// we try and pull down any changes
-		if hash.String() != input.Ref && refType == "branch" {
-			logger.Debugf("Provided ref is not a sha. Checking out branch before pulling changes")
-			sourceRef := plumbing.ReferenceName(path.Join("refs", "remotes", "origin", input.Ref))
-			if err = w.Checkout(&git.CheckoutOptions{
-				Branch: sourceRef,
-				Force:  true,
-			}); err != nil {
-				logger.Errorf("Unable to checkout %s: %v", sourceRef, err)
-				return err
-			}
-		}
-
 		reusedMsg := ""
-
-		switch {
-		case !isOfflineMode && !shallow:
-			// In shallow mode the depth-limited fetch above already advanced the ref.
-			if err = w.Pull(&pullOptions); err != nil && err != git.NoErrAlreadyUpToDate {
-				logger.Debugf("Unable to pull %s: %v", refName, err)
-			}
-		case isOfflineMode && reused:
+		if input.OfflineMode && reused {
 			reusedMsg = " (reused in offline mode)"
 		}
-
 		logger.Debugf("Cloned %s to %s%s", input.URL, input.Dir, reusedMsg)
-
-		if hash.String() != input.Ref && refType == "branch" {
-			logger.Debugf("Provided ref is not a sha. Updating branch ref after pull")
-			if hash, err = r.ResolveRevision(rev); err != nil {
-				logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
-				return err
-			}
-		}
-		if err = w.Checkout(&git.CheckoutOptions{
-			Hash:  *hash,
-			Force: true,
-		}); err != nil {
-			logger.Errorf("Unable to checkout %s: %v", *hash, err)
-			return err
-		}
-
-		if err = w.Reset(&git.ResetOptions{
-			Mode:   git.HardReset,
-			Commit: *hash,
-		}); err != nil {
-			logger.Errorf("Unable to reset to %s: %v", hash.String(), err)
-			return err
-		}
-
 		logger.Debugf("Checked out %s", input.Ref)
 		return nil
 	}
 }
 
-// cloneAtDepth clones input.URL into input.Dir using opts.
-// With input.Depth > 0 it first tries a shallow, single-branch clone of input.Ref, falling back when error.
-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
+func resolveClone(ctx context.Context, input NewGitCloneExecutorInput) (string, bool, error) { // the caller holds input.Dir's lock
+	logger := common.Logger(ctx)
+	reused, err := CloneIfRequired(ctx, input, logger)
+	if err != nil {
+		return "", false, err
+	}
+	resolved, err := resolveRef(ctx, input.Dir, input.Ref)
+	if errors.Is(err, ErrShortRef) || (err != nil && input.OfflineMode) {
+		return "", false, err
+	}
+	if !input.OfflineMode && (err != nil || (reused && !isFullHash(input.Ref, resolved))) {
+		if err := fetch(ctx, input); err != nil {
+			return "", false, err
+		}
+		resolved, err = resolveRef(ctx, input.Dir, input.Ref)
+	}
+	if err != nil {
+		logger.Errorf("Unable to resolve %s: %v", input.Ref, err)
+	}
+	return resolved, reused, err
+}
 
-			r, err := git.PlainCloneContext(ctx, input.Dir, false, &shallowOpts)
-			if err == nil {
-				return r, nil
+func clone(ctx context.Context, input NewGitCloneExecutorInput) error {
+	if input.Depth > 0 && isFullObjectID(input.Ref) {
+		if err := shallowPinnedClone(ctx, input); err == nil {
+			return nil
+		} else if err := removePartialClone(input.Dir); err != nil {
+			return err
+		}
+	}
+	args := []string{"clone", "--no-checkout"}
+	if input.Depth > 0 {
+		args = append(args, "--no-local", "--depth", strconv.Itoa(input.Depth), "--no-tags")
+		if input.Ref != "HEAD" && !strings.HasPrefix(input.Ref, "refs/") {
+			args = append(args, "--branch", input.Ref)
+		}
+	}
+	args = append(args, input.URL, input.Dir)
+	if _, err := runGit(ctx, "", &input, args...); err == nil {
+		return nil
+	} else if input.Depth == 0 {
+		return err
+	}
+	if err := removePartialClone(input.Dir); err != nil {
+		return err
+	}
+	_, err := runGit(ctx, "", &input, "clone", "--no-checkout", input.URL, input.Dir)
+	return err
+}
+
+func shallowPinnedClone(ctx context.Context, input NewGitCloneExecutorInput) error {
+	if _, err := runGit(ctx, "", &input, "init", "--object-format="+ObjectFormat(input.Ref), input.Dir); err != nil {
+		return err
+	}
+	if _, err := runGit(ctx, input.Dir, &input, "remote", "add", "origin", input.URL); err != nil {
+		return err
+	}
+	_, err := runGit(ctx, input.Dir, &input, "fetch", "--depth", strconv.Itoa(input.Depth), "--no-tags", "origin", "+"+input.Ref+":refs/pinned/"+input.Ref)
+	return err
+}
+
+func fetch(ctx context.Context, input NewGitCloneExecutorInput) error {
+	args := []string{"fetch", "--force", "--no-prune"}
+	if _, err := os.Stat(filepath.Join(input.Dir, ".git", "shallow")); err == nil {
+		args = append(args, "--depth", "1", "--no-tags")
+	}
+	_, err := runGit(ctx, input.Dir, &input, append(args, "origin", "+"+input.Ref+":"+cachedRef(input.Ref))...) // git picks the remote ref, a tag before a branch
+	return err
+}
+
+func cachedRef(ref string) string {
+	return fmt.Sprintf("refs/runner/%x", sha256.Sum256([]byte(ref)))
+}
+
+func resolveRef(ctx context.Context, dir, ref string) (string, error) {
+	if !isFullObjectID(ref) {
+		revisions := []string{cachedRef(ref) + "^{commit}", "refs/tags/" + ref + "^{commit}", "refs/remotes/origin/" + ref + "^{commit}"}
+		if strings.ContainsAny(ref, "\x00\n") {
+			for _, revision := range revisions {
+				if sha, err := gitOutput(ctx, dir, "rev-parse", "--verify", revision); err == nil {
+					return sha, 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)
+		} else if output, err := runGitWithStdin(ctx, dir, nil, strings.NewReader(strings.Join(revisions, "\n")+"\n"), "cat-file", "--batch-check=%(objectname)"); err == nil {
+			for sha := range strings.SplitSeq(string(output), "\n") {
+				if isFullObjectID(sha) {
+					return sha, nil
+				}
 			}
 		}
-		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)
+	sha, err := gitOutput(ctx, dir, "rev-parse", "--verify", ref+"^{commit}")
+	if err == nil && hexRefRegex.MatchString(ref) && len(sha) != len(ref) {
+		return "", &Error{err: ErrShortRef, commit: sha}
+	}
+	return sha, err
 }
 
-// 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
+func isFullObjectID(ref string) bool {
+	return ObjectFormat(ref) != ""
 }
 
-// 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
+func isFullHash(ref, resolved string) bool {
+	return isFullObjectID(ref) && len(ref) == len(resolved)
+}
+
+// ObjectFormat returns the object format of a full commit hash, empty for anything else.
+func ObjectFormat(sha string) string {
+	switch {
+	case !hexRefRegex.MatchString(sha):
+		return ""
+	case len(sha) == 40:
+		return "sha1"
+	case len(sha) == 64:
+		return "sha256"
+	}
+	return ""
+}
+
+func removePartialClone(dir string) error {
+	if err := os.RemoveAll(dir); err != nil {
+		return fmt.Errorf("remove partial clone %s: %w", dir, err)
+	}
+	return nil
+}
+
+func gitOutput(ctx context.Context, dir string, args ...string) (string, error) {
+	output, err := runGit(ctx, dir, nil, args...)
+	return strings.TrimSpace(string(output)), err
+}
+
+func RemoteConfig(token string, insecureSkipTLS bool) []string {
+	var config []string
+	if insecureSkipTLS {
+		config = append(config, "http.sslVerify=false")
+	}
+	if token != "" {
+		config = append(config, "http.extraHeader=", "http.extraHeader=Authorization: Basic "+base64.StdEncoding.EncodeToString([]byte("token:"+token)))
+	}
+	return config
+}
+
+func ClientCertConfig(prefix, certFile, keyFile, executionOS string) []string {
+	if certFile == "" {
+		return nil
+	}
+	config := []string{prefix + "sslCert=" + certFile, prefix + "sslKey=" + keyFile}
+	if strings.EqualFold(executionOS, "windows") {
+		config = append(config, prefix+"sslBackend=openssl")
+	}
+	return config
+}
+
+// ConfigEnv applies `-c` style entries through the environment, keeping secrets out of argv.
+func ConfigEnv(config ...string) map[string]string {
+	env := map[string]string{"GIT_CONFIG_COUNT": strconv.Itoa(len(config))}
+	for i, entry := range config {
+		key, value, _ := strings.Cut(entry, "=")
+		env["GIT_CONFIG_KEY_"+strconv.Itoa(i)] = key
+		env["GIT_CONFIG_VALUE_"+strconv.Itoa(i)] = value
+	}
+	return env
+}
+
+func ListFiles(ctx context.Context, dir string) ([]string, error) {
+	listed, err := runGit(ctx, dir, nil, "ls-files", "-z", "-t", "--stage", "--others", "--exclude-standard")
+	if err != nil {
+		return nil, err
+	}
+	var files, repos []string
+	for entry := range strings.SplitSeq(string(listed), "\x00") {
+		tag, file, ok := strings.Cut(entry, " ")
+		if tag != "?" {
+			var meta string
+			meta, file, ok = strings.Cut(file, "\t")
+			if strings.HasPrefix(meta, "160000 ") {
+				file += "/"
+			}
+		}
+		if repo, isRepo := strings.CutSuffix(file, "/"); isRepo {
+			repos = append(repos, repo)
+		} else if ok {
+			files = append(files, file)
+		}
+	}
+	slices.Sort(repos)
+	for _, repo := range slices.Compact(repos) {
+		files = append(files, repo)
+		if _, err := os.Lstat(filepath.Join(dir, repo, ".git")); err != nil {
+			continue // git lists an uninitialized submodule as "./" from inside it
+		}
+		nested, err := ListFiles(ctx, filepath.Join(dir, repo))
+		if err != nil {
+			return nil, err
+		}
+		for _, file := range nested {
+			files = append(files, repo+"/"+file)
+		}
+	}
+	return files, nil
+}
+
+func runGit(ctx context.Context, dir string, input *NewGitCloneExecutorInput, args ...string) ([]byte, error) {
+	return runGitWithStdin(ctx, dir, input, nil, args...)
+}
+
+func runGitWithStdin(ctx context.Context, dir string, input *NewGitCloneExecutorInput, stdin io.Reader, args ...string) ([]byte, error) {
+	config := []string{"core.autocrlf=false", "core.eol=lf"} // keep action files LF
+	if input != nil {
+		config = append(config, RemoteConfig(input.Token, input.InsecureSkipTLS)...)
+		config = append(config, ClientCertConfig("http.", input.ClientCertFile, input.ClientKeyFile, runtime.GOOS)...)
+	}
+	if dir != "" {
+		args = append([]string{"-C", dir}, args...)
+	}
+	cmd := exec.CommandContext(ctx, "git", args...)
+	cmd.Stdin = stdin
+	cmd.Env = slices.DeleteFunc(os.Environ(), func(entry string) bool {
+		name, _, _ := strings.Cut(entry, "=")
+		return slices.Contains(LocalEnvVars, name)
+	})
+	for key, value := range ConfigEnv(config...) {
+		cmd.Env = append(cmd.Env, key+"="+value)
+	}
+	cmd.Env = append(cmd.Env, "GIT_TERMINAL_PROMPT=0")
+	var treeKill *process.TreeKill
+	if runtime.GOOS == "windows" {
+		treeKill = process.NewTreeKill(cmd) // a cancelled git leaves its remote helper holding the repository otherwise
+	} else {
+		cmd.Cancel = func() error { return cmd.Process.Signal(os.Interrupt) } // lets git remove its lock files
+	}
+	cmd.WaitDelay = time.Second
+	var stdout bytes.Buffer
+	var stderr strings.Builder
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	err := cmd.Start()
+	if err == nil {
+		if treeKill != nil {
+			if killer, captureErr := treeKill.Capture(cmd.Process); captureErr == nil {
+				defer killer.Close()
+			}
+		}
+		err = cmd.Wait()
+	}
+	if err != nil {
+		return stdout.Bytes(), fmt.Errorf("git %s: %w: %s", strings.Join(args, " "), err, strings.TrimSpace(stderr.String()))
+	}
+	return stdout.Bytes(), nil
 }

act/common/git/git_test.go

@@ -6,50 +6,98 @@ package git
 
 import (
 	"context"
+	"encoding/base64"
 	"fmt"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"testing"
+	"testing/synctest"
 	"time"
 
-	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/act/common/logging/logtest"
+	"gitea.com/gitea/runner/internal/pkg/lock"
 
-	log "github.com/sirupsen/logrus"
-	logrustest "github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-func TestFindGitSlug(t *testing.T) {
-	assert := assert.New(t)
+var gitFixtureDir string
 
-	slugTests := []struct {
-		url      string // input
-		provider string // expected result
-		slug     string // expected result
-	}{
-		{"https://git-codecommit.us-east-1.amazonaws.com/v1/repos/my-repo-name", "CodeCommit", "my-repo-name"},
-		{"ssh://git-codecommit.us-west-2.amazonaws.com/v1/repos/my-repo", "CodeCommit", "my-repo"},
-		{"git@github.com:nektos/act.git", "GitHub", "nektos/act"},
-		{"git@github.com:nektos/act", "GitHub", "nektos/act"},
-		{"https://github.com/nektos/act.git", "GitHub", "nektos/act"},
-		{"http://github.com/nektos/act.git", "GitHub", "nektos/act"},
-		{"https://github.com/nektos/act", "GitHub", "nektos/act"},
-		{"http://github.com/nektos/act", "GitHub", "nektos/act"},
-		{"git+ssh://git@github.com/owner/repo.git", "GitHub", "owner/repo"},
-		{"http://myotherrepo.com/act.git", "", "http://myotherrepo.com/act.git"},
+func TestMain(m *testing.M) {
+	var err error
+	gitFixtureDir, err = os.MkdirTemp("", "runner-git-fixture-")
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
 	}
+	code := 1
+	if err = gitCmd("init", "--quiet", "--template=", "--bare", "--initial-branch=main", filepath.Join(gitFixtureDir, "remote")); err == nil {
+		err = gitCmd("init", "--quiet", "--template=", "--initial-branch=main", filepath.Join(gitFixtureDir, "work"))
+	}
+	if err == nil {
+		code = m.Run()
+	} else {
+		fmt.Fprintln(os.Stderr, err)
+	}
+	if err := os.RemoveAll(gitFixtureDir); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		code = 1
+	}
+	os.Exit(code)
+}
 
-	for _, tt := range slugTests {
-		provider, slug, err := findGitSlug(tt.url, "github.com")
+func TestClientCertConfig(t *testing.T) {
+	for _, testcase := range []struct {
+		prefix, certFile, executionOS string
+		expected                      []string
+	}{
+		{"http.", "cert.pem", "windows", []string{"http.sslCert=cert.pem", "http.sslKey=key.pem", "http.sslBackend=openssl"}},
+		{"http.https://example.com/.", "cert.pem", "Windows", []string{"http.https://example.com/.sslCert=cert.pem", "http.https://example.com/.sslKey=key.pem", "http.https://example.com/.sslBackend=openssl"}},
+		{"http.", "cert.pem", "Linux", []string{"http.sslCert=cert.pem", "http.sslKey=key.pem"}},
+		{"http.", "", "Windows", nil},
+	} {
+		t.Run(testcase.prefix+testcase.certFile+testcase.executionOS, func(t *testing.T) {
+			assert.Equal(t, testcase.expected, ClientCertConfig(testcase.prefix, testcase.certFile, "key.pem", testcase.executionOS))
+		})
+	}
+}
 
-		assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
-		assert.Equal(tt.provider, provider)
-		assert.Equal(tt.slug, slug)
+func TestFindGitSlug(t *testing.T) {
+	for _, testcase := range []struct {
+		remoteURL string
+		slug      string
+	}{
+		{"https://git-codecommit.us-east-1.amazonaws.com/v1/repos/my-repo-name", "my-repo-name"},
+		{"ssh://git-codecommit.us-west-2.amazonaws.com/v1/repos/my-repo", "my-repo"},
+		{"git@github.com:nektos/act.git", "nektos/act"},
+		{"git@github.com:nektos/act", "nektos/act"},
+		{"https://github.com/nektos/act.git", "nektos/act"},
+		{"http://github.com/nektos/act.git", "nektos/act"},
+		{"https://github.com/nektos/act", "nektos/act"},
+		{"http://github.com/nektos/act", "nektos/act"},
+		{"git+ssh://git@github.com/owner/repo.git", "owner/repo"},
+		{"https://example.com:3000/gitea/owner/repo.git/", "owner/repo"},
+		{"ssh://git@example.com:2222/gitea/owner/repo.git", "owner/repo"},
+		{"example.com:owner/repo.git", "owner/repo"},
+		{"http://myotherrepo.com/act.git", ""},
+		{"https://user:secret@example.com/act.git", ""},
+		{"/tmp/owner/repo.git", ""},
+		{"./owner/repo:branch", ""},
+	} {
+		t.Run(testcase.remoteURL, func(t *testing.T) {
+			slug, err := findGitSlug(testcase.remoteURL)
+			assert.Equal(t, testcase.slug == "", err != nil)
+			assert.NotContains(t, fmt.Sprint(err), "secret")
+			assert.Equal(t, testcase.slug, slug)
+		})
 	}
 }
 
@@ -60,169 +108,120 @@ func TestErrorWrapsCommitAndCause(t *testing.T) {
 	require.Equal(t, "abc123", err.Commit())
 }
 
-func cleanGitHooks(dir string) error {
-	hooksDir := filepath.Join(dir, ".git", "hooks")
-	files, err := os.ReadDir(hooksDir)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return nil
-		}
-		return err
-	}
-	for _, f := range files {
-		if f.IsDir() {
-			continue
-		}
-		relName := filepath.Join(hooksDir, f.Name())
-		if err := os.Remove(relName); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func TestFindGitRemoteURL(t *testing.T) {
-	assert := assert.New(t)
-
+func TestFindGitMetadataOfSHA256RepositoryUsesOrigin(t *testing.T) {
+	t.Parallel()
 	basedir := t.TempDir()
-	err := gitCmd("init", basedir)
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
-	err = cleanGitHooks(basedir)
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	const remoteURL = "https://github.com/owner/repo.git"
+	require.NoError(t, gitCmd("init", "--object-format=sha256", "--initial-branch=main", basedir))
+	require.NoError(t, os.RemoveAll(filepath.Join(basedir, ".git", "hooks")))
+	require.NoError(t, gitCmd("-C", basedir, "commit", "--allow-empty", "-m", "init"))
+	require.NoError(t, gitCmd("-C", basedir, "remote", "add", "origin", remoteURL))
+	require.NoError(t, gitCmd("-C", basedir, "config", "--add", "remote.origin.url", "https://github.com/other/repo.git"))
 
-	remoteURL := "https://git-codecommit.us-east-1.amazonaws.com/v1/repos/my-repo-name"
-	err = gitCmd("-C", basedir, "remote", "add", "origin", remoteURL)
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+	sha, err := FindGitRevision(t.Context(), basedir)
+	require.NoError(t, err)
+	require.Equal(t, gitRevParse(t, basedir, "HEAD"), sha)
+	require.Len(t, sha, 64)
 
-	u, err := findGitRemoteURL(context.Background(), basedir, "origin")
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(remoteURL, u)
+	ref, err := FindGitRef(t.Context(), basedir)
+	require.NoError(t, err)
+	require.Equal(t, "refs/heads/main", ref)
 
-	remoteURL = "git@github.com/AwesomeOwner/MyAwesomeRepo.git"
-	err = gitCmd("-C", basedir, "remote", "add", "upstream", remoteURL)
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
-	u, err = findGitRemoteURL(context.Background(), basedir, "upstream")
-	assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(remoteURL, u)
-}
+	url, err := findGitRemoteURL(t.Context(), basedir)
+	require.NoError(t, err)
+	require.Equal(t, remoteURL, url)
 
-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", "git@git.example.com:team/project.git"))
-
-	slug, err := FindGithubRepo(context.Background(), basedir, "github.com", "")
+	slug, err := FindGithubRepo(t.Context(), basedir)
 	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) {
+	t.Parallel()
 	basedir := t.TempDir()
 
 	for name, tt := range map[string]struct {
-		Prepare func(t *testing.T, dir string)
-		Assert  func(t *testing.T, ref string, err error)
+		commands [][]string
+		ref      string
 	}{
-		"new_repo": {
-			Prepare: func(t *testing.T, dir string) {},
-			Assert: func(t *testing.T, ref string, err error) {
-				require.Error(t, err)
-			},
-		},
+		"new_repo": {},
 		"new_repo_with_commit": {
-			Prepare: func(t *testing.T, dir string) {
-				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "msg"))
-			},
-			Assert: func(t *testing.T, ref string, err error) {
-				require.NoError(t, err)
-				require.Equal(t, "refs/heads/master", ref)
-			},
+			commands: [][]string{{"commit", "--allow-empty", "-m", "msg"}},
+			ref:      "refs/heads/master",
 		},
 		"current_head_is_tag": {
-			Prepare: func(t *testing.T, dir string) {
-				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "commit msg"))
-				require.NoError(t, gitCmd("-C", dir, "tag", "v1.2.3"))
-				require.NoError(t, gitCmd("-C", dir, "checkout", "v1.2.3"))
-			},
-			Assert: func(t *testing.T, ref string, err error) {
-				require.NoError(t, err)
-				require.Equal(t, "refs/tags/v1.2.3", ref)
+			commands: [][]string{
+				{"commit", "--allow-empty", "-m", "commit msg"},
+				{"tag", "v1.2.3"},
+				{"checkout", "v1.2.3"},
 			},
+			ref: "refs/tags/v1.2.3",
 		},
 		"current_head_is_same_as_tag": {
-			Prepare: func(t *testing.T, dir string) {
-				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "1.4.2 release"))
-				require.NoError(t, gitCmd("-C", dir, "tag", "v1.4.2"))
-			},
-			Assert: func(t *testing.T, ref string, err error) {
-				require.NoError(t, err)
-				require.Equal(t, "refs/tags/v1.4.2", ref)
+			commands: [][]string{
+				{"commit", "--allow-empty", "-m", "1.4.2 release"},
+				{"tag", "v1.4.2"},
 			},
+			ref: "refs/tags/v1.4.2",
 		},
 		"current_head_is_not_tag": {
-			Prepare: func(t *testing.T, dir string) {
-				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "msg"))
-				require.NoError(t, gitCmd("-C", dir, "tag", "v1.4.2"))
-				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "msg2"))
-			},
-			Assert: func(t *testing.T, ref string, err error) {
-				require.NoError(t, err)
-				require.Equal(t, "refs/heads/master", ref)
+			commands: [][]string{
+				{"commit", "--allow-empty", "-m", "msg"},
+				{"tag", "v1.4.2"},
+				{"commit", "--allow-empty", "-m", "msg2"},
 			},
+			ref: "refs/heads/master",
 		},
 		"current_head_is_another_branch": {
-			Prepare: func(t *testing.T, dir string) {
-				require.NoError(t, gitCmd("-C", dir, "checkout", "-b", "mybranch"))
-				require.NoError(t, gitCmd("-C", dir, "commit", "--allow-empty", "-m", "msg"))
-			},
-			Assert: func(t *testing.T, ref string, err error) {
-				require.NoError(t, err)
-				require.Equal(t, "refs/heads/mybranch", ref)
+			commands: [][]string{
+				{"checkout", "-b", "mybranch"},
+				{"commit", "--allow-empty", "-m", "msg"},
 			},
+			ref: "refs/heads/mybranch",
 		},
 	} {
 		t.Run(name, func(t *testing.T) {
 			dir := filepath.Join(basedir, name)
-			require.NoError(t, os.MkdirAll(dir, 0o755))
-			require.NoError(t, gitCmd("-C", dir, "init", "--initial-branch=master"))
-			require.NoError(t, cleanGitHooks(dir))
-			tt.Prepare(t, dir)
-			ref, err := FindGitRef(context.Background(), dir)
-			tt.Assert(t, ref, err)
+			require.NoError(t, os.CopyFS(dir, os.DirFS(filepath.Join(gitFixtureDir, "work"))))
+			require.NoError(t, os.WriteFile(filepath.Join(dir, ".git", "HEAD"), []byte("ref: refs/heads/master\n"), 0o644))
+			for _, command := range tt.commands {
+				require.NoError(t, gitCmd(append([]string{"-C", dir}, command...)...))
+			}
+			ref, err := FindGitRef(t.Context(), dir)
+			if tt.ref == "" {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+				require.Equal(t, tt.ref, ref)
+			}
 		})
 	}
 }
 
 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"))
+	remoteDir, workDir := newGitRemote(t)
+	require.NoError(t, os.WriteFile(filepath.Join(workDir, "action.sh"), []byte("#!/bin/sh\necho hi\n"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(workDir, ".gitattributes"), []byte("*.sh text\n"), 0o644))
+	require.NoError(t, gitCmd("-C", workDir, "add", "action.sh", ".gitattributes"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "-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))
+	fullSha := gitRevParse(t, workDir, "main")
 
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "main:refs/heads/"+fullSha[:4]))
+
+	hostConfig := filepath.Join(t.TempDir(), "gitconfig")
+	require.NoError(t, os.WriteFile(hostConfig, []byte("[core]\n\tautocrlf = true\n\teol = crlf\n[url "+strconv.Quote(remoteDir)+"]\n\tinsteadOf = https://example.invalid/action\n"), 0o644))
+	t.Setenv("GIT_CONFIG_GLOBAL", hostConfig)
+	t.Setenv("GIT_DIR", t.TempDir())
+
+	var clones sync.WaitGroup
 	for name, tt := range map[string]struct {
 		Err error
 		Ref string
@@ -243,34 +242,47 @@ func TestGitCloneExecutor(t *testing.T) {
 			Err: &Error{ErrShortRef, fullSha},
 			Ref: fullSha[:7],
 		},
+		"HEAD": {
+			Ref: "HEAD",
+		},
+		"hex branch named like its own commit": {
+			Ref: fullSha[:4],
+		},
 	} {
-		t.Run(name, func(t *testing.T) {
-			clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
-				URL: remoteDir,
-				Ref: tt.Ref,
-				Dir: t.TempDir(),
-			})
+		clones.Go(func() {
+			t.Run(name, func(t *testing.T) {
+				dir := t.TempDir()
+				clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
+					URL: "https://example.invalid/action",
+					Ref: tt.Ref,
+					Dir: dir,
+				})
 
-			err := clone(context.Background())
-			if tt.Err != nil {
-				assert.Error(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-				assert.Equal(t, tt.Err, err)
-			} else {
-				assert.Empty(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-			}
+				err := clone(t.Context())
+				if tt.Err != nil {
+					require.Error(t, err)
+					assert.Equal(t, tt.Err, err)
+					assert.Equal(t, tt.Err, clone(t.Context()), "a retry on the cache keeps the error")
+					return
+				}
+				require.NoError(t, err)
+				marker := filepath.Join(dir, "marker")
+				require.NoError(t, os.WriteFile(marker, nil, 0o644))
+				require.NoError(t, clone(t.Context()))
+				assert.FileExists(t, marker, "an insteadOf rewrite must not evict the cache")
+				script, err := os.ReadFile(filepath.Join(dir, "action.sh"))
+				require.NoError(t, err)
+				assert.Equal(t, "#!/bin/sh\necho hi\n", string(script), "host core.autocrlf must not convert action files")
+			})
 		})
 	}
+	clones.Wait()
 }
 
 func TestGitCloneExecutorReclonesWhenOriginURLChanges(t *testing.T) {
+	t.Parallel()
 	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))
+		remoteDir, workDir := newGitRemote(t, message)
 		require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
 
 		return remoteDir
@@ -286,16 +298,27 @@ func TestGitCloneExecutorReclonesWhenOriginURLChanges(t *testing.T) {
 		Dir: cacheDir,
 	})(t.Context()))
 
+	nested := filepath.Join(cacheDir, "nested")
+	require.NoError(t, os.Mkdir(nested, 0o755))
+	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{URL: oldRemoteDir, Ref: "main", Dir: nested})(t.Context()))
+	assert.DirExists(t, filepath.Join(nested, ".git"), "an empty cache dir inside a clone of the same URL gets its own repository")
+
 	markerPath := filepath.Join(cacheDir, "stale-marker")
 	require.NoError(t, os.WriteFile(markerPath, []byte("stale"), 0o644))
 
+	cancelled, cancel := context.WithCancel(t.Context())
+	cancel()
+	_, err := CloneIfRequired(cancelled, NewGitCloneExecutorInput{URL: oldRemoteDir, Ref: "main", Dir: cacheDir}, logging.New(logtest.New()))
+	require.ErrorIs(t, err, context.Canceled)
+	require.FileExists(t, markerPath)
+
 	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
 		URL: newRemoteDir,
 		Ref: "main",
 		Dir: cacheDir,
 	})(t.Context()))
 
-	originURL, err := findGitRemoteURL(t.Context(), cacheDir, "origin")
+	originURL, err := findGitRemoteURL(t.Context(), cacheDir)
 	require.NoError(t, err)
 	assert.Equal(t, newRemoteDir, originURL)
 
@@ -307,87 +330,58 @@ func TestGitCloneExecutorReclonesWhenOriginURLChanges(t *testing.T) {
 	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.
-
-	// 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))
-
-	// We need a working clone to push commits from.
-	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"))
+func TestGitCloneExecutorFollowsRemoteRefChanges(t *testing.T) {
+	t.Parallel()
+	remoteDir, workDir := newGitRemote(t, "initial", "feature-1")
 	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
 
-	// Create a feature branch (simulates refs/pull/N/head).
-	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "feature"))
-	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "feature-1"))
-	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "feature"))
+	dir := t.TempDir()
+	clone := NewGitCloneExecutor(NewGitCloneExecutorInput{URL: remoteDir, Ref: "main", Dir: dir})
+	require.NoError(t, clone(t.Context()))
+	require.NoError(t, gitCmd("-C", dir, "config", "fetch.prune", "true"))
+	require.NoError(t, clone(t.Context()))
 
-	// First clone via the executor — should succeed and cache the repo.
-	cloneDir := t.TempDir()
-	clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
-		URL: remoteDir,
-		Ref: "main",
-		Dir: cloneDir,
-	})
-	require.NoError(t, clone(context.Background()))
-
-	// Now force-push the feature branch to a non-fast-forward commit (simulates
-	// a PR rebase). This makes refs/heads/feature non-fast-forward.
-	require.NoError(t, gitCmd("-C", workDir, "checkout", "main"))
-	require.NoError(t, gitCmd("-C", workDir, "branch", "-D", "feature"))
-	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "feature"))
+	require.NoError(t, gitCmd("-C", workDir, "reset", "--hard", "HEAD~1"))
 	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "feature-rewritten"))
-	require.NoError(t, gitCmd("-C", workDir, "push", "--force", "origin", "feature"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "--force", "origin", "main"))
+	require.NoError(t, clone(t.Context()), "a non-fast-forward ref must update")
+	assert.Equal(t, "feature-rewritten", gitHeadSubject(t, dir))
 
-	// Also advance main so we can verify the clone picks up the new commit.
-	require.NoError(t, gitCmd("-C", workDir, "checkout", "main"))
-	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "second"))
-	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "main"))
+	tagDir := t.TempDir()
+	tagClone := NewGitCloneExecutor(NewGitCloneExecutorInput{URL: remoteDir, Ref: "v9", Dir: tagDir})
+	require.Error(t, tagClone(t.Context()))
+	require.NoError(t, gitCmd("-C", workDir, "tag", "v9"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "v9"))
+	require.NoError(t, tagClone(t.Context()), "a tag published after a failed lookup must be fetched")
 
-	// Second clone to the same directory — before the fix this returned ErrForceNeeded
-	// and left the working tree at the old commit.
-	err := clone(context.Background())
-	require.NoError(t, err, "fetch with non-fast-forward refs must not fail when Force=true")
-
-	// Verify the working tree was actually updated to the latest main commit.
-	out, err := exec.Command("git", "-C", cloneDir, "log", "--oneline", "-1", "--format=%s").Output()
-	require.NoError(t, err)
-	assert.Equal(t, "second", strings.TrimSpace(string(out)), "working tree should be at the latest commit")
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "tag-moved"))
+	require.NoError(t, gitCmd("-C", workDir, "tag", "--force", "v9"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "--force", "origin", "v9"))
+	for range 2 {
+		require.NoError(t, tagClone(t.Context()), "a moved tag must update and stay current")
+		assert.Equal(t, "tag-moved", gitHeadSubject(t, tagDir))
+	}
 }
 
 func TestGitCloneExecutorOfflineMode(t *testing.T) {
-	// Build a local "remote" with a single commit on main.
-	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"))
+	t.Parallel()
+	remoteDir, workDir := newGitRemote(t, "initial")
 	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
 
-	// Prime the cache with an online clone of main.
 	cacheDir := t.TempDir()
 	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
 		URL: remoteDir,
 		Ref: "main",
 		Dir: cacheDir,
-	})(context.Background()))
+	})(t.Context()))
 
 	t.Run("cached branch resolves without fetching", func(t *testing.T) {
-		// Offline reuse of a cached branch must succeed even though ResolveRevision(input.Ref)
-		// finds no local refs/heads/<ref>.
 		err := NewGitCloneExecutor(NewGitCloneExecutorInput{
 			URL:         remoteDir,
 			Ref:         "main",
 			Dir:         cacheDir,
 			OfflineMode: true,
-		})(context.Background())
+		})(t.Context())
 		require.NoError(t, err)
 
 		out, err := exec.Command("git", "-C", cacheDir, "log", "--oneline", "-1", "--format=%s").Output()
@@ -396,120 +390,147 @@ func TestGitCloneExecutorOfflineMode(t *testing.T) {
 	})
 
 	t.Run("unresolvable cached ref returns error", func(t *testing.T) {
-		// The ref was never cached; offline mode cannot resolve it and must return an error.
 		err := NewGitCloneExecutor(NewGitCloneExecutorInput{
 			URL:         remoteDir,
 			Ref:         "never-fetched",
 			Dir:         cacheDir,
 			OfflineMode: true,
-		})(context.Background())
+		})(t.Context())
 		require.Error(t, err)
 	})
 }
 
-func TestGitCloneExecutorQuietDemotesCloneLine(t *testing.T) {
-	remoteDir := t.TempDir()
-	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
-	workDir := t.TempDir()
-	require.NoError(t, gitCmd("clone", remoteDir, workDir))
-	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
-	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "initial"))
-	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))
-	}
+	t.Parallel()
+	remoteDir, workDir := newGitRemote(t, "c1", "c2", "c3")
 	require.NoError(t, gitCmd("-C", workDir, "tag", "v1"))
-	sha := gitRevParse(t, workDir, "HEAD~1") // c2, a SHA that go-git cannot shallow-clone
+	unadvertisedSHA := gitRevParse(t, workDir, "HEAD~1")
 	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
 	require.NoError(t, gitCmd("-C", workDir, "push", "origin", "v1"))
 
 	shallowMarker := func(dir string) string { return filepath.Join(dir, ".git", "shallow") }
 
-	t.Run("branch is cloned shallowly", func(t *testing.T) {
+	for name, ref := range map[string]string{"branch is cloned shallowly": "main", "tag is cloned shallowly": "v1"} {
+		t.Run(name, func(t *testing.T) {
+			dir := t.TempDir()
+			require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: remoteDir, Ref: ref, 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))
+		})
+	}
+
+	unadvertisedRemote := func(t *testing.T, allowUnadvertised bool) string {
+		remote := filepath.Join(t.TempDir(), "remote.git")
+		require.NoError(t, gitCmd("clone", "--bare", remoteDir, remote))
+		require.NoError(t, gitCmd("-C", remote, "config", "uploadpack.allowAnySHA1InWant", strconv.FormatBool(allowUnadvertised)))
+		return remote
+	}
+
+	t.Run("commit hash resolves when the remote accepts a direct shallow fetch", func(t *testing.T) {
 		dir := t.TempDir()
 		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
-			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
+			URL: unadvertisedRemote(t, false), Ref: unadvertisedSHA, 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))
+		assert.Equal(t, unadvertisedSHA, gitRevParse(t, dir, "HEAD"))
 	})
 
-	t.Run("tag is cloned shallowly", func(t *testing.T) {
+	t.Run("commit hash is fetched shallowly, moved to another hash, then reused without reaching the remote", func(t *testing.T) {
+		remote := unadvertisedRemote(t, true)
 		dir := t.TempDir()
-		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
-			URL: remoteDir, Ref: "v1", Dir: dir, Depth: 1,
-		})(t.Context()))
-		assert.FileExists(t, shallowMarker(dir), "clone should be shallow")
+		cloneAt := func(ref string) error {
+			return NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: remote, Ref: ref, Dir: dir, Depth: 1,
+			})(t.Context())
+		}
+
+		require.NoError(t, cloneAt(unadvertisedSHA))
+		assert.FileExists(t, shallowMarker(dir))
 		assert.Equal(t, 1, gitRevCount(t, dir))
-		assert.Equal(t, "c3", gitHeadSubject(t, dir))
+		assert.Equal(t, unadvertisedSHA, gitRevParse(t, dir, "HEAD"))
+
+		olderSHA := gitRevParse(t, workDir, "HEAD~2")
+		require.NoError(t, cloneAt(olderSHA))
+		assert.Equal(t, olderSHA, gitRevParse(t, dir, "HEAD"))
+
+		require.NoError(t, os.RemoveAll(remote))
+		require.NoError(t, cloneAt(olderSHA))
+		assert.Equal(t, olderSHA, gitRevParse(t, dir, "HEAD"))
 	})
 
-	t.Run("SHA falls back to a full clone", func(t *testing.T) {
+	t.Run("moving hexadecimal-named branch updates while staying shallow", func(t *testing.T) {
+		require.NoError(t, gitCmd("-C", workDir, "push", "origin", "main:deadbeef"))
 		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()))
+		clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "deadbeef", Dir: dir, Depth: 1,
+		})
+		require.NoError(t, clone(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, gitCmd("-C", workDir, "push", "origin", "main:deadbeef"))
 
-		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
-			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
-		})(t.Context()))
+		require.NoError(t, clone(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))
 	})
+
+	t.Run("sha256 full hash is cloned shallowly, reused without the remote, and its 40-character prefix is short", func(t *testing.T) {
+		remote := filepath.Join(t.TempDir(), "remote.git")
+		require.NoError(t, gitCmd("init", "--bare", "--object-format=sha256", "--initial-branch=main", remote))
+		work := t.TempDir()
+		require.NoError(t, gitCmd("init", "--object-format=sha256", "--initial-branch=main", work))
+		require.NoError(t, gitCmd("-C", work, "remote", "add", "origin", remote))
+		require.NoError(t, gitCmd("-C", work, "commit", "--allow-empty", "-m", "pinned"))
+		require.NoError(t, gitCmd("-C", work, "push", "origin", "main"))
+		sha := gitRevParse(t, work, "HEAD")
+		dir := t.TempDir()
+		clone := NewGitCloneExecutor(NewGitCloneExecutorInput{URL: remote, Ref: sha, Dir: dir, Depth: 1})
+		require.NoError(t, clone(t.Context()))
+		assert.FileExists(t, shallowMarker(dir))
+		require.ErrorIs(t, NewGitCloneExecutor(NewGitCloneExecutorInput{URL: remote, Ref: sha[:40], Dir: dir, Depth: 1, OfflineMode: true})(t.Context()), ErrShortRef)
+		require.NoError(t, os.RemoveAll(remote))
+		require.NoError(t, clone(t.Context()))
+		assert.Equal(t, sha, gitRevParse(t, dir, "HEAD"))
+	})
+}
+
+func TestGitCloneExecutorPinnedHashIgnoresShadowingRef(t *testing.T) {
+	t.Parallel()
+	remoteDir, workDir := newGitRemote(t, "pinned")
+	pinned := gitRevParse(t, workDir, "HEAD")
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "decoy"))
+	require.NoError(t, gitCmd("-C", workDir, "tag", pinned))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", pinned))
+
+	for name, depth := range map[string]int{"shallow": 1, "full clone": 0} {
+		t.Run(name, func(t *testing.T) {
+			dir := t.TempDir()
+			require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: remoteDir, Ref: pinned, Dir: dir, Depth: depth,
+			})(t.Context()))
+			assert.Equal(t, pinned, gitRevParse(t, dir, "HEAD"))
+		})
+	}
+}
+
+func newGitRemote(t *testing.T, messages ...string) (string, string) {
+	t.Helper()
+	remoteDir, workDir := t.TempDir(), t.TempDir()
+	require.NoError(t, os.CopyFS(remoteDir, os.DirFS(filepath.Join(gitFixtureDir, "remote"))))
+	require.NoError(t, os.CopyFS(workDir, os.DirFS(filepath.Join(gitFixtureDir, "work"))))
+	config, err := os.ReadFile(filepath.Join(workDir, ".git", "config"))
+	require.NoError(t, err)
+	require.NoError(t, os.WriteFile(filepath.Join(workDir, ".git", "config"),
+		fmt.Appendf(config, "\n[remote \"origin\"]\n\turl = %s\n\tfetch = +refs/heads/*:refs/remotes/origin/*\n", strconv.Quote(remoteDir)), 0o644))
+	for _, message := range messages {
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", message))
+	}
+	return remoteDir, workDir
 }
 
 func gitRevParse(t *testing.T, dir, rev string) string {
@@ -539,9 +560,6 @@ 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",
 		"GIT_AUTHOR_EMAIL=test@test.com",
@@ -562,14 +580,42 @@ func gitCmd(args ...string) error {
 }
 
 func TestAcquireCloneLock(t *testing.T) {
+	t.Run("blocks on a lock held by another process despite a trailing separator", func(t *testing.T) {
+		dir := filepath.Join(t.TempDir(), "cache")
+		release, err := lock.TryLock(dir)
+		require.NoError(t, err)
+		defer func() { require.NoError(t, release()) }()
+		synctest.Test(t, func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(t.Context(), time.Second)
+			defer cancel()
+			_, err := AcquireCloneLock(ctx, dir+string(filepath.Separator))
+			require.ErrorIs(t, err, context.DeadlineExceeded)
+		})
+	})
+
+	t.Run("read-only parent falls back to an in-process lock", func(t *testing.T) {
+		parent := t.TempDir()
+		dir := filepath.Join(parent, "cache")
+		require.NoError(t, os.Mkdir(dir, 0o755))
+		require.NoError(t, os.Chmod(parent, 0o555))
+		defer func() { require.NoError(t, os.Chmod(parent, 0o755)) }()
+		unlock, err := AcquireCloneLock(t.Context(), dir)
+		require.NoError(t, err)
+		unlock()
+	})
+
 	t.Run("same directory serializes", func(t *testing.T) {
 		dir := t.TempDir()
 
-		unlock1 := AcquireCloneLock(dir)
+		unlock1, err := AcquireCloneLock(t.Context(), dir)
+		require.NoError(t, err)
 
 		secondAcquired := make(chan struct{})
 		go func() {
-			unlock := AcquireCloneLock(dir)
+			unlock, err := AcquireCloneLock(t.Context(), dir)
+			if !assert.NoError(t, err) {
+				return
+			}
 			close(secondAcquired)
 			unlock()
 		}()
@@ -593,12 +639,16 @@ func TestAcquireCloneLock(t *testing.T) {
 		dirA := t.TempDir()
 		dirB := t.TempDir()
 
-		unlockA := AcquireCloneLock(dirA)
+		unlockA, err := AcquireCloneLock(t.Context(), dirA)
+		require.NoError(t, err)
 		defer unlockA()
 
 		done := make(chan struct{})
 		go func() {
-			unlock := AcquireCloneLock(dirB)
+			unlock, err := AcquireCloneLock(t.Context(), dirB)
+			if !assert.NoError(t, err) {
+				return
+			}
 			unlock()
 			close(done)
 		}()
@@ -610,3 +660,49 @@ func TestAcquireCloneLock(t *testing.T) {
 		}
 	})
 }
+
+func TestNewGitCloneExecutorFetchSendsTokenAndHonoursContext(t *testing.T) {
+	t.Parallel()
+	block := make(chan struct{})
+	reached := make(chan struct{})
+	var once sync.Once
+	var authorization string
+	server := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, request *http.Request) {
+		once.Do(func() {
+			authorization = request.Header.Get("Authorization")
+			close(reached)
+		})
+		<-block
+	}))
+	t.Cleanup(func() {
+		close(block)
+		server.Close()
+	})
+
+	dir := filepath.Join(t.TempDir(), "cached-action")
+	require.NoError(t, gitCmd("init", dir))
+	require.NoError(t, gitCmd("-C", dir, "remote", "add", "origin", server.URL))
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	done := make(chan error, 1)
+	go func() {
+		done <- NewGitCloneExecutor(NewGitCloneExecutorInput{URL: server.URL, Ref: "main", Dir: dir, Token: "secret"})(ctx)
+	}()
+
+	select {
+	case <-reached:
+	case err := <-done:
+		t.Fatalf("the executor finished before reaching the remote: %v", err)
+	}
+	assert.Equal(t, "Basic "+base64.StdEncoding.EncodeToString([]byte("token:secret")), authorization)
+	cancel()
+
+	select {
+	case err := <-done:
+		require.Error(t, err)
+	case <-time.After(10 * time.Second):
+		t.Fatal("fetch ignored context cancellation")
+	}
+}

act/common/job_error.go

@@ -14,13 +14,8 @@ const jobErrorContextKeyVal = jobErrorContextKey("job.error")
 
 // JobError returns the job error for current context if any
 func JobError(ctx context.Context) error {
-	val := ctx.Value(jobErrorContextKeyVal)
-	if val != nil {
-		if container, ok := val.(map[string]error); ok {
-			return container["error"]
-		}
-	}
-	return nil
+	container, _ := ctx.Value(jobErrorContextKeyVal).(map[string]error)
+	return container["error"]
 }
 
 func SetJobError(ctx context.Context, err error) {
@@ -31,6 +26,5 @@ func SetJobError(ctx context.Context, err error) {
 
 // WithJobErrorContainer adds a value to the context as a container for an error
 func WithJobErrorContainer(ctx context.Context) context.Context {
-	container := map[string]error{}
-	return context.WithValue(ctx, jobErrorContextKeyVal, container)
+	return context.WithValue(ctx, jobErrorContextKeyVal, map[string]error{})
 }

act/common/line_writer.go

@@ -26,9 +26,7 @@ type lineWriter struct {
 
 // NewLineWriter creates a new instance of a line writer
 func NewLineWriter(handlers ...LineHandler) io.Writer {
-	w := new(lineWriter)
-	w.handlers = handlers
-	return w
+	return &lineWriter{handlers: handlers}
 }
 
 // FlushWriter flushes w if it implements Flusher. It is a no-op otherwise, so
@@ -39,24 +37,15 @@ func FlushWriter(w io.Writer) {
 	}
 }
 
-func (lw *lineWriter) Write(p []byte) (n int, err error) {
-	pBuf := bytes.NewBuffer(p)
-	written := 0
-	for {
-		line, err := pBuf.ReadString('\n')
-		w, _ := lw.buffer.WriteString(line)
-		written += w
-		if err == nil {
+func (lw *lineWriter) Write(p []byte) (int, error) {
+	for line := range bytes.SplitAfterSeq(p, []byte{'\n'}) {
+		_, _ = lw.buffer.Write(line)
+		if len(line) > 0 && line[len(line)-1] == '\n' {
 			lw.handleLine(lw.buffer.String())
 			lw.buffer.Reset()
-		} else if err == io.EOF {
-			break
-		} else {
-			return written, err
 		}
 	}
-
-	return written, nil
+	return len(p), nil
 }
 
 // Flush emits any buffered, not-yet-newline-terminated content as a final line.
@@ -72,8 +61,7 @@ func (lw *lineWriter) Flush() {
 
 func (lw *lineWriter) handleLine(line string) {
 	for _, h := range lw.handlers {
-		ok := h(line)
-		if !ok {
+		if !h(line) {
 			break
 		}
 	}

act/common/line_writer_test.go

@@ -9,24 +9,24 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
-func TestLineWriter(t *testing.T) {
-	lines := make([]string, 0)
-	lineHandler := func(s string) bool {
+func TestLineWriterBuffersAndFlushesLines(t *testing.T) {
+	var lines []string
+	lineWriter := NewLineWriter(func(s string) bool {
 		lines = append(lines, s)
 		return true
-	}
-
-	lineWriter := NewLineWriter(lineHandler)
+	})
 
 	assert := assert.New(t)
 	write := func(s string) {
 		n, err := lineWriter.Write([]byte(s))
-		assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+		require.NoError(t, err)
 		assert.Equal(len(s), n, s)
 	}
 
+	write("")
 	write("hello")
 	write(" ")
 	write("world!!\nextra")
@@ -34,39 +34,17 @@ func TestLineWriter(t *testing.T) {
 	write(" line\n")
 	write("no newline here...")
 
-	assert.Len(lines, 4)
-	assert.Equal("hello world!!\n", lines[0])
-	assert.Equal("extra line\n", lines[1])
-	assert.Equal(" and another\n", lines[2])
-	assert.Equal("last line\n", lines[3])
-}
+	expected := []string{"hello world!!\n", "extra line\n", " and another\n", "last line\n"}
+	assert.Equal(expected, lines)
 
-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)
+	expected = append(expected, "no newline here...")
+	assert.Equal(expected, lines)
 
-	// Flushing again is a no-op: nothing is buffered.
 	FlushWriter(lineWriter)
-	assert.Len(lines, 2)
+	assert.Equal(expected, lines)
 }
 
 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/logger.go

@@ -7,46 +7,51 @@ package common
 import (
 	"context"
 
-	"github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
 )
 
 type loggerContextKey string
 
-const loggerContextKeyVal = loggerContextKey("logrus.FieldLogger")
+const loggerContextKeyVal = loggerContextKey("logging.Logger")
 
 // Logger returns the appropriate logger for current context
-func Logger(ctx context.Context) logrus.FieldLogger {
-	val := ctx.Value(loggerContextKeyVal)
-	if val != nil {
-		if logger, ok := val.(logrus.FieldLogger); ok {
-			return logger
-		}
+func Logger(ctx context.Context) *logging.Logger {
+	if logger, ok := ctx.Value(loggerContextKeyVal).(*logging.Logger); ok {
+		return logger
 	}
-	return logrus.StandardLogger()
+	return logging.Default()
 }
 
 // WithLogger adds a value to the context for the logger
-func WithLogger(ctx context.Context, logger logrus.FieldLogger) context.Context {
+func WithLogger(ctx context.Context, logger *logging.Logger) context.Context {
 	return context.WithValue(ctx, loggerContextKeyVal, logger)
 }
 
-type loggerHookKey string
+type loggerHandlerKey string
 
-const loggerHookKeyVal = loggerHookKey("logrus.Hook")
+const loggerHandlerKeyVal = loggerHandlerKey("logging.Handler")
 
-// LoggerHook returns the appropriate logger hook for current context
-// the hook affects job logger, not global logger
-func LoggerHook(ctx context.Context) logrus.Hook {
-	val := ctx.Value(loggerHookKeyVal)
-	if val != nil {
-		if hook, ok := val.(logrus.Hook); ok {
-			return hook
-		}
-	}
-	return nil
+// LoggerHandler returns the extra handler the job logger sends its records to, or nil.
+// It affects the job logger, not the global logger.
+func LoggerHandler(ctx context.Context) logging.Handler {
+	h, _ := ctx.Value(loggerHandlerKeyVal).(logging.Handler)
+	return h
 }
 
-// WithLoggerHook adds a value to the context for the logger hook
-func WithLoggerHook(ctx context.Context, hook logrus.Hook) context.Context {
-	return context.WithValue(ctx, loggerHookKeyVal, hook)
+// WithLoggerHandler adds the extra handler for the job logger to the context
+func WithLoggerHandler(ctx context.Context, h logging.Handler) context.Context {
+	return context.WithValue(ctx, loggerHandlerKeyVal, h)
+}
+
+type stepIDsContextKey struct{}
+
+// StepIDs returns the IDs of the step and the composite steps enclosing the current one, outermost first.
+func StepIDs(ctx context.Context) []string {
+	ids, _ := ctx.Value(stepIDsContextKey{}).([]string)
+	return ids
+}
+
+// WithStepIDs replaces the step IDs in the context
+func WithStepIDs(ctx context.Context, ids []string) context.Context {
+	return context.WithValue(ctx, stepIDsContextKey{}, ids)
 }

act/common/logging/console.go

@@ -0,0 +1,284 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"maps"
+	"reflect"
+	"runtime"
+	"slices"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	ansiReset    = "\x1b[0m"
+	ansiRed      = "\x1b[31m"
+	ansiYellow   = "\x1b[33m"
+	ansiCyan     = "\x1b[36m"
+	ansiDimCyan  = "\x1b[2;36m"
+	ansiDimWhite = "\x1b[2;37m"
+)
+
+// consoleStart is the zero of the elapsed-seconds stamp used when full timestamps are off.
+var consoleStart = time.Now()
+
+// console is the state shared by every consoleHandler derived from one another.
+type console struct {
+	mu           sync.Mutex
+	out          io.Writer
+	terminal     bool
+	opts         TextOptions
+	reportCaller bool
+	level        slog.LevelVar
+}
+
+func newConsole(out io.Writer) *console {
+	c := &console{}
+	c.setOutput(out)
+	return c
+}
+
+func (c *console) setOutput(w io.Writer) {
+	terminal := checkIfTerminal(w)
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.out, c.terminal = w, terminal
+}
+
+// consoleHandler is a slog.Handler writing the text format the runner has always used, so that
+// moving off logrus changes nothing a user can see: sorted key=value fields on a plain stream,
+// and a colored prefix with elapsed or full time on a terminal.
+type consoleHandler struct {
+	c     *console
+	attrs []slog.Attr
+}
+
+func (h *consoleHandler) Enabled(_ context.Context, level slog.Level) bool {
+	return level >= h.c.level.Level()
+}
+
+func (h *consoleHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return &consoleHandler{c: h.c, attrs: append(slices.Clone(h.attrs), attrs...)}
+}
+
+// WithGroup is a no-op, as only NewSlogHandler wraps a consoleHandler and it never groups.
+func (h *consoleHandler) WithGroup(string) slog.Handler { return h }
+
+func (h *consoleHandler) Handle(_ context.Context, r slog.Record) error {
+	c := h.c
+	c.mu.Lock()
+	opts, reportCaller, terminal := c.opts, c.reportCaller, c.terminal
+	c.mu.Unlock()
+
+	data := make(map[string]any, len(h.attrs)+r.NumAttrs())
+	for _, a := range h.attrs {
+		data[a.Key] = a.Value.Resolve().Any()
+	}
+	r.Attrs(func(a slog.Attr) bool {
+		data[a.Key] = a.Value.Resolve().Any()
+		return true
+	})
+
+	var caller *runtime.Frame
+	if reportCaller && r.PC != 0 {
+		frame, _ := runtime.CallersFrames([]uintptr{r.PC}).Next()
+		caller = &frame
+	}
+	prefixFieldClashes(data, caller != nil)
+
+	keys := slices.Sorted(maps.Keys(data))
+
+	var b bytes.Buffer
+	if terminal && !opts.DisableColors {
+		printColored(&b, opts, r, caller, keys, data)
+	} else {
+		printPlain(&b, opts, r, caller, keys, data)
+	}
+
+	line := b.Bytes()
+	if opts.Filter != nil {
+		line = opts.Filter(line)
+	}
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	_, err := c.out.Write(line)
+	return err
+}
+
+// prefixFieldClashes moves fields that share a name with a fixed key out of its way.
+func prefixFieldClashes(data map[string]any, reportCaller bool) {
+	for _, key := range []string{"time", "level", "msg"} {
+		if v, ok := data[key]; ok {
+			data["fields."+key] = v
+			delete(data, key)
+		}
+	}
+	if reportCaller {
+		for _, key := range []string{"func", "file"} {
+			if v, ok := data[key]; ok {
+				data["fields."+key] = v
+			}
+		}
+	}
+}
+
+func printPlain(b *bytes.Buffer, opts TextOptions, r slog.Record, caller *runtime.Frame, keys []string, data map[string]any) {
+	if !opts.DisableTimestamp {
+		appendKeyValue(b, "time", r.Time.Format(time.RFC3339))
+	}
+	appendKeyValue(b, "level", plainLevel(Level(r.Level)))
+	if r.Message != "" {
+		appendKeyValue(b, "msg", r.Message)
+	}
+	if caller != nil {
+		funcVal, fileVal := callerText(opts, caller)
+		if funcVal != "" {
+			appendKeyValue(b, "func", funcVal)
+		}
+		if fileVal != "" {
+			appendKeyValue(b, "file", fileVal)
+		}
+	}
+	for _, k := range keys {
+		appendKeyValue(b, k, data[k])
+	}
+	b.WriteByte('\n')
+}
+
+func callerText(opts TextOptions, caller *runtime.Frame) (funcVal, fileVal string) {
+	if opts.CallerPrettyfier != nil {
+		return opts.CallerPrettyfier(caller)
+	}
+	return caller.Function, caller.File + ":" + strconv.Itoa(caller.Line)
+}
+
+func printColored(b *bytes.Buffer, opts TextOptions, r slog.Record, caller *runtime.Frame, keys []string, data map[string]any) {
+	msg := strings.TrimSuffix(r.Message, "\n")
+
+	var callerStr string
+	if caller != nil {
+		funcVal, fileVal := callerText(opts, caller)
+		if opts.CallerPrettyfier == nil && caller.Function != "" {
+			funcVal += "()"
+		}
+		switch {
+		case fileVal == "":
+			callerStr = funcVal
+		case funcVal == "":
+			callerStr = fileVal
+		default:
+			callerStr = fileVal + " " + funcVal
+		}
+	}
+
+	level := Level(r.Level)
+	prefix := colorize(level, strings.ToUpper(plainLevel(level))[:4])
+	switch {
+	case opts.DisableTimestamp:
+		fmt.Fprintf(b, "%s%s %-44s ", prefix, callerStr, msg)
+	case !opts.FullTimestamp:
+		fmt.Fprintf(b, "%s[%04d]%s %-44s ", prefix, int(r.Time.Sub(consoleStart)/time.Second), callerStr, msg)
+	default:
+		fmt.Fprintf(b, "%s[%s]%s %-44s ", prefix, r.Time.Format(time.RFC3339), callerStr, msg)
+	}
+	for _, k := range keys {
+		b.WriteByte(' ')
+		b.WriteString(colorize(level, k))
+		b.WriteByte('=')
+		appendValue(b, data[k])
+	}
+	b.WriteByte('\n')
+}
+
+// plainLevel spells Warn the way logrus did, as "warning".
+func plainLevel(l Level) string {
+	if s := l.String(); s != "warn" {
+		return s
+	}
+	return "warning"
+}
+
+func colorize(l Level, s string) string {
+	var color string
+	switch {
+	case l <= LevelTrace:
+		color = ansiDimWhite
+	case l <= LevelDebug:
+		color = ansiDimCyan
+	case l <= LevelInfo:
+		color = ansiCyan
+	case l <= LevelWarn:
+		color = ansiYellow
+	default:
+		color = ansiRed
+	}
+	return color + s + ansiReset
+}
+
+func appendKeyValue(b *bytes.Buffer, key string, value any) {
+	if b.Len() > 0 {
+		b.WriteByte(' ')
+	}
+	b.WriteString(key)
+	b.WriteByte('=')
+	appendValue(b, value)
+}
+
+func appendValue(b *bytes.Buffer, value any) {
+	switch v := value.(type) {
+	case string:
+		appendString(b, v)
+	case []byte:
+		appendString(b, string(v))
+	case error:
+		appendFormatted(b, v, v.Error)
+	case fmt.Stringer:
+		appendFormatted(b, v, v.String)
+	default:
+		appendString(b, fmt.Sprint(value))
+	}
+}
+
+// appendFormatted writes what get returns, and "<nil>" if that panics on a nil receiver.
+func appendFormatted(b *bytes.Buffer, v any, get func() string) {
+	defer func() {
+		if r := recover(); r != nil {
+			if rv := reflect.ValueOf(v); rv.Kind() == reflect.Pointer && rv.IsNil() {
+				appendString(b, "<nil>")
+			} else {
+				appendString(b, fmt.Sprintf("%%!v(PANIC=%v)", r))
+			}
+		}
+	}()
+	appendString(b, get())
+}
+
+func appendString(b *bytes.Buffer, s string) {
+	if needsQuoting(s) {
+		b.WriteString(strconv.Quote(s))
+		return
+	}
+	b.WriteString(s)
+}
+
+func needsQuoting(s string) bool {
+	for i := range len(s) {
+		c := s[i]
+		switch {
+		case c >= 'a' && c <= 'z', c >= 'A' && c <= 'Z', c >= '0' && c <= '9':
+		case c == '-', c == '.', c == '_', c == '/', c == '@', c == '^', c == '+':
+		default:
+			return true
+		}
+	}
+	return false
+}

act/common/logging/console_test.go

@@ -0,0 +1,78 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging
+
+import (
+	"bytes"
+	"errors"
+	"log/slog"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func consoleLine(t *testing.T, opts TextOptions, terminal, reportCaller bool, build func(*Logger)) string {
+	t.Helper()
+	var out bytes.Buffer
+	c := newConsole(&out)
+	c.opts, c.terminal, c.reportCaller = opts, terminal, reportCaller
+	c.level.Set(slog.LevelDebug)
+	build(New(NewSlogHandler(&consoleHandler{c: c})))
+	return out.String()
+}
+
+func TestConsolePlain(t *testing.T) {
+	line := consoleLine(t, TextOptions{DisableTimestamp: true}, false, false, func(l *Logger) {
+		l.With("job", "build x", "n", 3).WithError(errors.New("boom")).Warnf("hello world")
+		l.With("msg", "clash", "empty", "").Info("")
+	})
+	assert.Equal(t, "level=warning msg=\"hello world\" error=boom job=\"build x\" n=3\n"+
+		"level=info empty= fields.msg=clash\n", line)
+}
+
+func TestConsolePlainTimeFilterAndCaller(t *testing.T) {
+	opts := TextOptions{
+		CallerPrettyfier: func(f *runtime.Frame) (string, string) {
+			return "[fn]", "[" + strings.TrimPrefix(f.Function, "x") + "]"
+		},
+		Filter: func(b []byte) []byte { return bytes.ReplaceAll(b, []byte("secret"), []byte("***")) },
+	}
+	line := consoleLine(t, opts, false, true, func(l *Logger) { l.With("k", "secret").Debugf("a secret") })
+	assert.Regexp(t, `^time="[^"]+" level=debug msg="a \*\*\*" func="\[fn\]" file="\[.*TestConsolePlainTimeFilterAndCaller[^"]*\]" k=\*\*\*\n$`, line)
+}
+
+func TestConsoleColored(t *testing.T) {
+	line := consoleLine(t, TextOptions{DisableTimestamp: true}, true, false, func(l *Logger) {
+		l.With("job", "j").Warn("careful")
+	})
+	assert.Equal(t, "\x1b[33mWARN\x1b[0m "+"careful"+strings.Repeat(" ", 44-len("careful"))+"  \x1b[33mjob\x1b[0m=j\n", line)
+
+	full := consoleLine(t, TextOptions{FullTimestamp: true}, true, false, func(l *Logger) { l.Error("bad") })
+	assert.Regexp(t, `^\x1b\[31mERRO\x1b\[0m\[\d{4}-\d\d-\d\dT[^\]]+\] bad`, full)
+
+	elapsed := consoleLine(t, TextOptions{}, true, false, func(l *Logger) { l.Info("x") })
+	assert.Regexp(t, `^\x1b\[36mINFO\x1b\[0m\[\d{4}\] x`, elapsed)
+
+	plain := consoleLine(t, TextOptions{DisableColors: true, DisableTimestamp: true}, true, false, func(l *Logger) { l.Info("x") })
+	assert.Equal(t, "level=info msg=x\n", plain)
+}
+
+func TestConsoleLevelAndOutput(t *testing.T) {
+	var out bytes.Buffer
+	c := newConsole(&out)
+	h := &consoleHandler{c: c}
+	assert.False(t, h.Enabled(t.Context(), slog.LevelDebug)) // info unless raised
+	c.level.Set(slog.LevelError)
+	assert.False(t, h.Enabled(t.Context(), slog.LevelWarn))
+	assert.True(t, h.Enabled(t.Context(), slog.LevelError))
+
+	rec := slog.NewRecord(time.Unix(0, 0), slog.LevelError, "m", 0)
+	rec.AddAttrs(slog.String("c", "3"))
+	require.NoError(t, h.WithAttrs([]slog.Attr{slog.Int("a", 1)}).Handle(t.Context(), rec))
+	assert.Contains(t, out.String(), "a=1 c=3")
+}

act/common/logging/global.go

@@ -0,0 +1,83 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging
+
+import (
+	"io"
+	"log/slog"
+	"os"
+	"runtime"
+	"sync/atomic"
+)
+
+// TextOptions describes how the process-wide Logger writes a record as text.
+type TextOptions struct {
+	DisableColors    bool
+	DisableTimestamp bool
+	FullTimestamp    bool
+	// CallerPrettyfier renames the function and file reported with a record when ReportCaller is on.
+	CallerPrettyfier func(*runtime.Frame) (function, file string)
+	// Filter rewrites each formatted line, for example to mask secrets.
+	Filter func(line []byte) []byte
+}
+
+var (
+	std      atomic.Pointer[Logger]
+	stdState = newConsole(os.Stderr)
+)
+
+func init() {
+	std.Store(New(NewSlogHandler(&consoleHandler{c: stdState})))
+}
+
+// Default returns the process-wide Logger.
+func Default() *Logger { return std.Load() }
+
+// SetDefault replaces the process-wide Logger, which tests use to capture what the package
+// functions log. SetLevel, GetLevel, SetOutput and the format functions keep configuring the
+// initial console Logger.
+func SetDefault(l *Logger) { std.Store(l) }
+
+// SetLevel sets the minimum level of the initial process-wide Logger.
+func SetLevel(level Level) { stdState.level.Set(slog.Level(level)) }
+
+// GetLevel returns the minimum level of the initial process-wide Logger.
+func GetLevel() Level { return Level(stdState.level.Level()) }
+
+// SetOutput sets where the initial process-wide Logger writes.
+func SetOutput(w io.Writer) { stdState.setOutput(w) }
+
+// Output returns where the initial process-wide Logger writes.
+func Output() io.Writer {
+	stdState.mu.Lock()
+	defer stdState.mu.Unlock()
+	return stdState.out
+}
+
+// SetTextFormat sets the text format of the initial process-wide Logger.
+func SetTextFormat(o TextOptions) {
+	stdState.mu.Lock()
+	defer stdState.mu.Unlock()
+	stdState.opts = o
+}
+
+// SetReportCaller makes the initial process-wide Logger record where each call came from, which costs time.
+func SetReportCaller(on bool) {
+	stdState.mu.Lock()
+	defer stdState.mu.Unlock()
+	stdState.reportCaller = on
+}
+
+func Enabled(level Level) bool { return Default().Enabled(level) }
+
+func With(args ...any) *Logger          { return Default().With(args...) }
+func WithError(err error) *Logger       { return Default().WithError(err) }
+func Debugf(format string, args ...any) { Default().logf(LevelDebug, format, args) }
+func Infof(format string, args ...any)  { Default().logf(LevelInfo, format, args) }
+func Warnf(format string, args ...any)  { Default().logf(LevelWarn, format, args) }
+func Errorf(format string, args ...any) { Default().logf(LevelError, format, args) }
+func Debug(args ...any)                 { Default().log(LevelDebug, args) }
+func Info(args ...any)                  { Default().log(LevelInfo, args) }
+func Warn(args ...any)                  { Default().log(LevelWarn, args) }
+func Error(args ...any)                 { Default().log(LevelError, args) }

act/common/logging/handler.go

@@ -0,0 +1,114 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging
+
+import (
+	"context"
+	"errors"
+	"slices"
+	"time"
+)
+
+// Attr is a structured key/value pair attached to a log record.
+type Attr struct {
+	Key   string
+	Value any
+}
+
+// Record is one log event. Attrs holds the call-site attributes only, the ones added with
+// Logger.With are accumulated by the Handler.
+type Record struct {
+	Time    time.Time
+	Level   Level
+	Message string
+	PC      uintptr // program counter of the logging call, 0 if unknown
+	Attrs   []Attr
+}
+
+// Attr returns the value of the last attribute named key.
+func (r Record) Attr(key string) (any, bool) {
+	for _, a := range slices.Backward(r.Attrs) {
+		if a.Key == key {
+			return a.Value, true
+		}
+	}
+	return nil, false
+}
+
+// Handler consumes records, and is shaped like slog.Handler so that a slog backend can replace
+// the current one without touching callers. Handle must not modify the Attrs slice it is given.
+type Handler interface {
+	Enabled(ctx context.Context, level Level) bool
+	Handle(ctx context.Context, r Record) error
+	// WithAttrs returns a Handler that adds attrs to every record it handles.
+	WithAttrs(attrs []Attr) Handler
+}
+
+type multiHandler []Handler
+
+// NewMultiHandler fans every record out to all handlers that have its level enabled.
+func NewMultiHandler(handlers ...Handler) Handler {
+	return multiHandler(handlers)
+}
+
+func (m multiHandler) Enabled(ctx context.Context, level Level) bool {
+	for _, h := range m {
+		if h.Enabled(ctx, level) {
+			return true
+		}
+	}
+	return false
+}
+
+func (m multiHandler) Handle(ctx context.Context, r Record) error {
+	var errs []error
+	for _, h := range m {
+		if h.Enabled(ctx, r.Level) {
+			errs = append(errs, h.Handle(ctx, r))
+		}
+	}
+	return errors.Join(errs...)
+}
+
+func (m multiHandler) WithAttrs(attrs []Attr) Handler {
+	out := make(multiHandler, len(m))
+	for i, h := range m {
+		out[i] = h.WithAttrs(attrs)
+	}
+	return out
+}
+
+type discardHandler struct{}
+
+// DiscardHandler drops every record.
+var DiscardHandler Handler = discardHandler{}
+
+func (discardHandler) Enabled(context.Context, Level) bool  { return false }
+func (discardHandler) Handle(context.Context, Record) error { return nil }
+func (d discardHandler) WithAttrs([]Attr) Handler           { return d }
+
+type levelHandler struct {
+	h        Handler
+	minLevel Level
+}
+
+// NewLevelHandler passes only records at or above minLevel on to h.
+func NewLevelHandler(h Handler, minLevel Level) Handler {
+	return levelHandler{h: h, minLevel: minLevel}
+}
+
+func (l levelHandler) Enabled(ctx context.Context, level Level) bool {
+	return level >= l.minLevel && l.h.Enabled(ctx, level)
+}
+
+func (l levelHandler) Handle(ctx context.Context, r Record) error {
+	if r.Level < l.minLevel {
+		return nil
+	}
+	return l.h.Handle(ctx, r)
+}
+
+func (l levelHandler) WithAttrs(attrs []Attr) Handler {
+	return levelHandler{h: l.h.WithAttrs(attrs), minLevel: l.minLevel}
+}

act/common/logging/level.go

@@ -0,0 +1,53 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Level is a log severity. The values match log/slog, with Trace added below Debug.
+type Level int
+
+const (
+	LevelTrace Level = -8
+	LevelDebug Level = -4
+	LevelInfo  Level = 0
+	LevelWarn  Level = 4
+	LevelError Level = 8
+)
+
+func (l Level) String() string {
+	switch {
+	case l <= LevelTrace:
+		return "trace"
+	case l <= LevelDebug:
+		return "debug"
+	case l <= LevelInfo:
+		return "info"
+	case l <= LevelWarn:
+		return "warn"
+	default:
+		return "error"
+	}
+}
+
+// ParseLevel accepts every name logrus does. "fatal" and "panic" map to LevelError because
+// the Logger has no level above it.
+func ParseLevel(s string) (Level, error) {
+	switch strings.ToLower(s) {
+	case "trace":
+		return LevelTrace, nil
+	case "debug":
+		return LevelDebug, nil
+	case "info":
+		return LevelInfo, nil
+	case "warn", "warning":
+		return LevelWarn, nil
+	case "error", "fatal", "panic":
+		return LevelError, nil
+	}
+	return LevelInfo, fmt.Errorf("not a valid log level: %q", s)
+}

act/common/logging/logger.go

@@ -0,0 +1,105 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging
+
+import (
+	"context"
+	"fmt"
+	"runtime"
+	"time"
+)
+
+const badKey = "!BADKEY"
+
+// Logger writes printf-style messages with structured attributes to a Handler.
+type Logger struct {
+	h   Handler
+	ctx context.Context
+}
+
+func New(h Handler) *Logger {
+	return &Logger{h: h, ctx: context.Background()}
+}
+
+// With returns a Logger that adds the key/value pairs to every record, like slog.Logger.With.
+func (l *Logger) With(args ...any) *Logger {
+	if len(args) == 0 {
+		return l
+	}
+	return &Logger{h: l.h.WithAttrs(argsToAttrs(args)), ctx: l.ctx}
+}
+
+func (l *Logger) WithError(err error) *Logger {
+	return l.With("error", err)
+}
+
+// WithContext returns a Logger that passes ctx to its Handler.
+func (l *Logger) WithContext(ctx context.Context) *Logger {
+	return &Logger{h: l.h, ctx: ctx}
+}
+
+func (l *Logger) Enabled(level Level) bool {
+	return l.h.Enabled(l.ctx, level)
+}
+
+func (l *Logger) Debugf(format string, args ...any) { l.logf(LevelDebug, format, args) }
+func (l *Logger) Infof(format string, args ...any)  { l.logf(LevelInfo, format, args) }
+func (l *Logger) Warnf(format string, args ...any)  { l.logf(LevelWarn, format, args) }
+func (l *Logger) Errorf(format string, args ...any) { l.logf(LevelError, format, args) }
+
+// Trace and the methods below format their arguments like fmt.Sprint.
+func (l *Logger) Trace(args ...any) { l.log(LevelTrace, args) }
+func (l *Logger) Debug(args ...any) { l.log(LevelDebug, args) }
+func (l *Logger) Info(args ...any)  { l.log(LevelInfo, args) }
+func (l *Logger) Warn(args ...any)  { l.log(LevelWarn, args) }
+func (l *Logger) Error(args ...any) { l.log(LevelError, args) }
+
+func (l *Logger) logf(level Level, format string, args []any) {
+	if !l.Enabled(level) {
+		return
+	}
+	l.emit(callerPC(4), level, fmt.Sprintf(format, args...))
+}
+
+func (l *Logger) log(level Level, args []any) {
+	if !l.Enabled(level) {
+		return
+	}
+	l.emit(callerPC(4), level, fmt.Sprint(args...))
+}
+
+// emit drops the Handler error, as a logger has nowhere to report it.
+func (l *Logger) emit(pc uintptr, level Level, msg string) {
+	_ = l.h.Handle(l.ctx, Record{Time: time.Now(), Level: level, Message: msg, PC: pc})
+}
+
+// callerPC returns the program counter skip frames up, 4 being the caller of an exported method.
+func callerPC(skip int) uintptr {
+	var pcs [1]uintptr
+	runtime.Callers(skip, pcs[:])
+	return pcs[0]
+}
+
+func argsToAttrs(args []any) []Attr {
+	attrs := make([]Attr, 0, len(args)/2+1)
+	for len(args) > 0 {
+		switch k := args[0].(type) {
+		case Attr:
+			attrs = append(attrs, k)
+			args = args[1:]
+		case string:
+			if len(args) == 1 {
+				attrs = append(attrs, Attr{Key: badKey, Value: k})
+				args = nil
+			} else {
+				attrs = append(attrs, Attr{Key: k, Value: args[1]})
+				args = args[2:]
+			}
+		default:
+			attrs = append(attrs, Attr{Key: badKey, Value: k})
+			args = args[1:]
+		}
+	}
+	return attrs
+}

act/common/logging/logging_test.go

@@ -0,0 +1,145 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging_test
+
+import (
+	"errors"
+	"log/slog"
+	"runtime"
+	"strings"
+	"testing"
+
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/act/common/logging/logtest"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseLevel(t *testing.T) {
+	for in, want := range map[string]logging.Level{
+		"trace": logging.LevelTrace, "DEBUG": logging.LevelDebug, "info": logging.LevelInfo,
+		"warn": logging.LevelWarn, "warning": logging.LevelWarn,
+		"error": logging.LevelError, "fatal": logging.LevelError, "panic": logging.LevelError,
+	} {
+		got, err := logging.ParseLevel(in)
+		require.NoError(t, err, in)
+		assert.Equal(t, want, got, in)
+	}
+	_, err := logging.ParseLevel("loud")
+	require.Error(t, err)
+	assert.Equal(t, "warn", logging.LevelWarn.String())
+}
+
+type countingStringer struct{ n *int }
+
+func (c countingStringer) String() string { *c.n++; return "x" }
+
+func TestLogger(t *testing.T) {
+	h := logtest.NewWithLevel(logging.LevelTrace)
+	assert.Nil(t, h.LastRecord())
+	l := logging.New(h)
+
+	l.With("job", "j1").WithError(errors.New("boom")).Warnf("step %d", 2)
+	l.Info("a", 1, 2, "b")
+	l.With("k").With(7).Debug("x")
+
+	recs := h.AllRecords()
+	require.Len(t, recs, 3)
+	assert.Equal(t, "step 2", recs[0].Message)
+	assert.Equal(t, logging.LevelWarn, recs[0].Level)
+	assert.False(t, recs[0].Time.IsZero())
+	job, _ := recs[0].Attr("job")
+	assert.Equal(t, "j1", job)
+	errv, _ := recs[0].Attr("error")
+	require.EqualError(t, errv.(error), "boom")
+	assert.Equal(t, "a1 2b", recs[1].Message)
+	bad, _ := recs[2].Attr("!BADKEY")
+	assert.Equal(t, 7, bad)
+}
+
+func TestLoggerSkipsFormattingWhenDisabled(t *testing.T) {
+	n := 0
+	l := logging.New(logging.NewLevelHandler(logtest.NewWithLevel(logging.LevelTrace), logging.LevelWarn))
+	l.Debugf("%v", countingStringer{&n})
+	assert.Zero(t, n)
+	assert.False(t, l.Enabled(logging.LevelInfo))
+}
+
+func TestMultiHandler(t *testing.T) {
+	assert.False(t, logging.DiscardHandler.Enabled(t.Context(), logging.LevelError))
+	all, warnOnly := logtest.New(), logtest.NewWithLevel(logging.LevelTrace)
+	l := logging.New(logging.NewMultiHandler(all, logging.NewLevelHandler(warnOnly, logging.LevelWarn), logging.DiscardHandler)).With("a", 1)
+	l.Info("i")
+	l.Error("e")
+	assert.Len(t, all.AllRecords(), 2)
+	require.Len(t, warnOnly.AllRecords(), 1)
+	v, _ := warnOnly.LastRecord().Attr("a")
+	assert.Equal(t, 1, v)
+}
+
+func frameOf(t *testing.T, pc uintptr) runtime.Frame {
+	t.Helper()
+	require.NotZero(t, pc)
+	f, _ := runtime.CallersFrames([]uintptr{pc}).Next()
+	return f
+}
+
+func TestCallerPC(t *testing.T) {
+	l, h := logtest.NewLogger()
+	l.Infof("method")
+	l.Info("method")
+
+	prev := logging.Default()
+	t.Cleanup(func() { logging.SetDefault(prev) })
+	logging.SetDefault(l)
+	logging.Infof("global")
+	logging.Error("global")
+
+	require.Len(t, h.AllRecords(), 4)
+	for _, r := range h.AllRecords() {
+		assert.True(t, strings.HasSuffix(frameOf(t, r.PC).Function, "TestCallerPC"), r.Message)
+	}
+}
+
+func TestDefaultLevel(t *testing.T) {
+	prev := logging.GetLevel()
+	t.Cleanup(func() { logging.SetLevel(prev) })
+
+	logging.SetLevel(logging.LevelWarn)
+	assert.Equal(t, logging.LevelWarn, logging.GetLevel())
+	assert.True(t, logging.Enabled(logging.LevelError))
+	assert.False(t, logging.Enabled(logging.LevelInfo))
+}
+
+func TestSlogHandler(t *testing.T) {
+	var buf strings.Builder
+	l := logging.New(logging.NewSlogHandler(slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug}))).With("job", "j1")
+
+	assert.False(t, l.Enabled(logging.LevelTrace))
+	l.WithError(errors.New("boom")).Errorf("fail %s", "x")
+
+	out := buf.String()
+	assert.Contains(t, out, "level=ERROR")
+	assert.Contains(t, out, `msg="fail x"`)
+	assert.Contains(t, out, "job=j1")
+	assert.Contains(t, out, "error=boom")
+}
+
+func TestSlogBridge(t *testing.T) {
+	h := logtest.SetDefault(t)
+	slog.With("lib", "actionslib").Warn("from a library", "n", 1)
+	_, _, line, _ := runtime.Caller(0)
+	slog.Debug("dropped")
+
+	recs := h.AllRecords()
+	require.Len(t, recs, 1)
+	assert.Equal(t, "from a library", recs[0].Message)
+	assert.Equal(t, logging.LevelWarn, recs[0].Level)
+	lib, _ := recs[0].Attr("lib")
+	assert.Equal(t, "actionslib", lib)
+	n, _ := recs[0].Attr("n")
+	assert.EqualValues(t, 1, n)
+	assert.Equal(t, line-1, frameOf(t, recs[0].PC).Line)
+}

act/common/logging/logtest/logtest.go

@@ -0,0 +1,83 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+// Package logtest provides a Handler that keeps records in memory for assertions.
+package logtest
+
+import (
+	"context"
+	"slices"
+	"sync"
+	"testing"
+
+	"gitea.com/gitea/runner/act/common/logging"
+)
+
+type store struct {
+	mu      sync.Mutex
+	records []logging.Record
+}
+
+// Handler records what it receives at or above its level. Loggers derived with WithAttrs share one store.
+type Handler struct {
+	store    *store
+	attrs    []logging.Attr
+	minLevel logging.Level
+}
+
+// New records from LevelInfo up, like the logger of logrus's hooks/test.
+func New() *Handler {
+	return NewWithLevel(logging.LevelInfo)
+}
+
+// NewLogger returns a Logger writing to a new Handler from New, and that Handler.
+func NewLogger() (*logging.Logger, *Handler) {
+	h := New()
+	return logging.New(h), h
+}
+
+func NewWithLevel(minLevel logging.Level) *Handler {
+	return &Handler{store: &store{}, minLevel: minLevel}
+}
+
+func (h *Handler) Enabled(_ context.Context, level logging.Level) bool { return level >= h.minLevel }
+
+// Handle stores the record with the attributes accumulated by WithAttrs placed first.
+func (h *Handler) Handle(_ context.Context, r logging.Record) error {
+	r.Attrs = append(slices.Clone(h.attrs), r.Attrs...)
+	h.store.mu.Lock()
+	defer h.store.mu.Unlock()
+	h.store.records = append(h.store.records, r)
+	return nil
+}
+
+func (h *Handler) WithAttrs(attrs []logging.Attr) logging.Handler {
+	return &Handler{store: h.store, attrs: append(slices.Clone(h.attrs), attrs...), minLevel: h.minLevel}
+}
+
+func (h *Handler) AllRecords() []logging.Record {
+	h.store.mu.Lock()
+	defer h.store.mu.Unlock()
+	return slices.Clone(h.store.records)
+}
+
+// LastRecord returns nil when nothing was logged.
+func (h *Handler) LastRecord() *logging.Record {
+	h.store.mu.Lock()
+	defer h.store.mu.Unlock()
+	if len(h.store.records) == 0 {
+		return nil
+	}
+	r := h.store.records[len(h.store.records)-1]
+	return &r
+}
+
+// SetDefault makes the process-wide Logger record into a new Handler until the test ends.
+func SetDefault(t testing.TB) *Handler {
+	t.Helper()
+	prev := logging.Default()
+	logger, h := NewLogger()
+	logging.SetDefault(logger)
+	t.Cleanup(func() { logging.SetDefault(prev) })
+	return h
+}

act/common/logging/slog.go

@@ -0,0 +1,81 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging
+
+import (
+	"context"
+	"log/slog"
+	"slices"
+)
+
+func init() {
+	slog.SetDefault(slog.New(slogBridge{}))
+}
+
+// slogBridge hands what libraries log through slog's global logger to the process-wide Logger.
+type slogBridge struct {
+	attrs []Attr
+}
+
+func (b slogBridge) Enabled(ctx context.Context, level slog.Level) bool {
+	return Default().h.Enabled(ctx, Level(level))
+}
+
+func (b slogBridge) Handle(ctx context.Context, r slog.Record) error {
+	h := Default().h
+	if len(b.attrs) > 0 {
+		h = h.WithAttrs(b.attrs)
+	}
+	attrs := make([]Attr, 0, r.NumAttrs())
+	r.Attrs(func(a slog.Attr) bool {
+		attrs = append(attrs, fromSlogAttr(a))
+		return true
+	})
+	return h.Handle(ctx, Record{Time: r.Time, Level: Level(r.Level), Message: r.Message, PC: r.PC, Attrs: attrs})
+}
+
+func (b slogBridge) WithAttrs(attrs []slog.Attr) slog.Handler {
+	out := slices.Clone(b.attrs)
+	for _, a := range attrs {
+		out = append(out, fromSlogAttr(a))
+	}
+	return slogBridge{attrs: out}
+}
+
+func (b slogBridge) WithGroup(string) slog.Handler { return b }
+
+func fromSlogAttr(a slog.Attr) Attr {
+	return Attr{Key: a.Key, Value: a.Value.Resolve().Any()}
+}
+
+type slogHandler struct {
+	h slog.Handler
+}
+
+// NewSlogHandler writes to h. Levels map one to one, as Level uses slog's values.
+func NewSlogHandler(h slog.Handler) Handler {
+	return slogHandler{h: h}
+}
+
+func (s slogHandler) Enabled(ctx context.Context, level Level) bool {
+	return s.h.Enabled(ctx, slog.Level(level))
+}
+
+func (s slogHandler) Handle(ctx context.Context, r Record) error {
+	rec := slog.NewRecord(r.Time, slog.Level(r.Level), r.Message, r.PC)
+	rec.AddAttrs(toSlogAttrs(r.Attrs)...)
+	return s.h.Handle(ctx, rec)
+}
+
+func (s slogHandler) WithAttrs(attrs []Attr) Handler {
+	return slogHandler{h: s.h.WithAttrs(toSlogAttrs(attrs))}
+}
+
+func toSlogAttrs(attrs []Attr) []slog.Attr {
+	out := make([]slog.Attr, len(attrs))
+	for i, a := range attrs {
+		out[i] = slog.Any(a.Key, a.Value)
+	}
+	return out
+}

act/common/logging/terminal_other.go

@@ -0,0 +1,20 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !windows
+
+package logging
+
+import (
+	"io"
+	"os"
+
+	"golang.org/x/term"
+)
+
+func checkIfTerminal(w io.Writer) bool {
+	if f, ok := w.(*os.File); ok {
+		return term.IsTerminal(int(f.Fd()))
+	}
+	return false
+}

act/common/logging/terminal_windows.go

@@ -0,0 +1,27 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build windows
+
+package logging
+
+import (
+	"io"
+	"os"
+
+	"golang.org/x/sys/windows"
+)
+
+// checkIfTerminal also turns on virtual terminal processing, which the console needs to show colors.
+func checkIfTerminal(w io.Writer) bool {
+	f, ok := w.(*os.File)
+	if !ok {
+		return false
+	}
+	handle := windows.Handle(f.Fd())
+	var mode uint32
+	if err := windows.GetConsoleMode(handle, &mode); err != nil {
+		return false
+	}
+	return windows.SetConsoleMode(handle, mode|windows.ENABLE_VIRTUAL_TERMINAL_PROCESSING) == nil
+}

act/common/lookup_fold.go

@@ -0,0 +1,20 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import "strings"
+
+// LookupFold finds name in values, ignoring case where the environment does, as GitHub's inputs always do.
+func LookupFold[V any](values map[string]V, name string, caseInsensitive bool) (V, bool) {
+	if value, ok := values[name]; ok || !caseInsensitive {
+		return value, ok
+	}
+	for key, value := range values {
+		if strings.EqualFold(key, name) {
+			return value, true
+		}
+	}
+	var zero V
+	return zero, false
+}

act/common/outbound_ip.go

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

act/common/outbound_ip_test.go

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

act/container/container_types.go

@@ -6,14 +6,23 @@ package container
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
+	"path"
+	"runtime"
+	"strings"
+	"sync"
+	"sync/atomic"
 
 	"gitea.com/gitea/runner/act/common"
 
 	"github.com/docker/go-connections/nat"
+	"github.com/moby/moby/api/types/container"
 )
 
+var hostOS = runtime.GOOS // replaced in tests
+
 // ExitCodeError reports a non-zero process exit code from a container command.
 type ExitCodeError int
 
@@ -23,26 +32,27 @@ func (e ExitCodeError) Error() string {
 
 // NewContainerInput the input for the New function
 type NewContainerInput struct {
-	Image          string
-	Username       string
-	Password       string
-	Entrypoint     []string
-	Cmd            []string
-	WorkingDir     string
-	Env            []string
-	Binds          []string
-	Mounts         map[string]string
-	Name           string
-	Stdout         io.Writer
-	Stderr         io.Writer
-	NetworkMode    string
-	Privileged     bool
-	UsernsMode     string
-	Platform       string
-	Options        string
-	NetworkAliases []string
-	ExposedPorts   nat.PortSet
-	PortBindings   nat.PortMap
+	Image           string
+	Username        string
+	Password        string
+	Entrypoint      []string
+	Cmd             []string
+	WorkingDir      string
+	Env             []string
+	Binds           []string
+	Mounts          map[string]string
+	Name            string
+	Stdout          io.Writer
+	Stderr          io.Writer
+	NetworkMode     string
+	Privileged      bool
+	UsernsMode      string
+	Platform        string
+	RunnerOptions   string // container options the runner was configured with, trusted
+	WorkflowOptions string // container options the workflow asked for, untrusted
+	NetworkAliases  []string
+	ExposedPorts    nat.PortSet
+	PortBindings    nat.PortMap
 
 	// Gitea specific
 	AutoRemove   bool
@@ -57,14 +67,72 @@ type FileEntry struct {
 	Body string
 }
 
+// Container and healthcheck states, as plain strings so a caller of Info needs no docker
+// SDK of its own.
+const (
+	StateRunning = string(container.StateRunning)
+
+	HealthNone      = string(container.NoHealthcheck)
+	HealthStarting  = string(container.Starting)
+	HealthHealthy   = string(container.Healthy)
+	HealthUnhealthy = string(container.Unhealthy)
+)
+
+// marks what a runner creates for its jobs, telling its leftovers from another runner's
+const runnerUUIDLabel = "com.gitea.runner.uuid"
+
+// ErrContainerNotFound reports a container the daemon no longer knows. Its text is a
+// fragment, missingContainerError composes it into the message every operation shares.
+var ErrContainerNotFound = errors.New("does not exist")
+
+// DockerProxy is a job's docker socket, fronting the daemon's for the job's lifetime.
+type DockerProxy struct {
+	Socket    string
+	close     func(context.Context) error
+	closeOnce sync.Once
+	closeErr  error
+	mounts    atomic.Value
+}
+
+func (p *DockerProxy) SetMounts(mounts map[string]string) {
+	p.mounts.Store(mounts)
+}
+
+func (p *DockerProxy) Close(ctx context.Context) error {
+	p.closeOnce.Do(func() { p.closeErr = p.close(ctx) })
+	return p.closeErr
+}
+
+// Info is a snapshot of a container, as of one inspect.
+type Info struct {
+	ID       string
+	State    string // the docker container state: "created", "running", "exited", ...
+	ExitCode int
+	Health   string // one of the Health* constants
+	// HealthOutput is the last healthcheck probe's output.
+	HealthOutput string
+	Ports        map[string]string // container port ("5432") to the host port it is published on
+	Mounts       map[string]string // container path to its source on the daemon
+}
+
+// DaemonPath maps target to its daemon path through the nearest mount with a source, empty without one.
+func (info *Info) DaemonPath(target string) string {
+	for dir := target; dir != "/" && dir != "."; dir = path.Dir(dir) {
+		if source := info.Mounts[dir]; source != "" {
+			return path.Join(source, strings.TrimPrefix(target, dir))
+		}
+	}
+	return ""
+}
+
 // Container for managing docker run containers
 type Container interface {
 	Create(capAdd, capDrop []string) common.Executor
-	ConnectToNetwork(name string) common.Executor
 	Copy(destPath string, files ...*FileEntry) common.Executor
-	CopyTarStream(ctx context.Context, destPath string, tarStream io.Reader) error
-	CopyDir(destPath, srcPath string, useGitIgnore bool) common.Executor
+	CopyDir(destPath, srcPath string, useGitIgnore, skipGitDir bool) common.Executor
 	GetContainerArchive(ctx context.Context, srcPath string) (io.ReadCloser, error)
+	Inspect(ctx context.Context) (*Info, error)
+	DumpLogs(ctx context.Context) error
 	Pull(forcePull bool) common.Executor
 	Start(attach bool) common.Executor
 	Exec(command []string, env map[string]string, user, workdir string) common.Executor

act/container/docker_auth.go

@@ -2,25 +2,38 @@
 // Copyright 2021 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 
 import (
+	"bytes"
 	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"maps"
+	"net"
+	"net/url"
+	"os"
+	"os/exec"
+	"os/user"
+	"path/filepath"
+	"runtime"
+	"strings"
 
 	"gitea.com/gitea/runner/act/common"
 
 	"github.com/distribution/reference"
-	"github.com/docker/cli/cli/config"
 	"github.com/moby/moby/api/types/registry"
 )
 
 func LoadDockerAuthConfig(ctx context.Context, image string) (registry.AuthConfig, error) {
 	logger := common.Logger(ctx)
-	// config.LoadDefaultConfigFile panics on nil io.Writer when the config
-	// file is malformed; use config.Load to route errors through the logger.
-	cfg, err := config.Load(config.Dir())
+	cfg, err := loadDockerConfig(ctx)
 	if err != nil {
 		logger.Warnf("Could not load docker config: %v", err)
 		return registry.AuthConfig{}, err
@@ -34,32 +47,27 @@ func LoadDockerAuthConfig(ctx context.Context, image string) (registry.AuthConfi
 		}
 	}
 
-	authConfig, err := cfg.GetAuthConfig(registryKey)
+	authConfig, err := cfg.authConfig(ctx, registryKey)
 	if err != nil {
 		logger.Warnf("Could not get auth config from docker config: %v", err)
 		return registry.AuthConfig{}, err
 	}
 
-	return registry.AuthConfig(authConfig), nil
+	return authConfig, nil
 }
 
 func LoadDockerAuthConfigs(ctx context.Context) map[string]registry.AuthConfig {
 	logger := common.Logger(ctx)
-	cfg, err := config.Load(config.Dir())
+	cfg, err := loadDockerConfig(ctx)
 	if err != nil {
 		logger.Warnf("Could not load docker config: %v", err)
 		return nil
 	}
-	creds, err := cfg.GetAllCredentials()
+	authConfigs, err := cfg.allAuthConfigs(ctx)
 	if err != nil {
 		logger.Warnf("Could not get docker auth configs: %v", err)
 		return nil
 	}
-	authConfigs := make(map[string]registry.AuthConfig, len(creds))
-	for k, v := range creds {
-		authConfigs[k] = registry.AuthConfig(v)
-	}
-
 	return authConfigs
 }
 
@@ -69,3 +77,226 @@ func registryAuthConfigKey(domainName string) string {
 	}
 	return domainName
 }
+
+type dockerConfig struct {
+	Auths       map[string]registry.AuthConfig `json:"auths"`
+	CredsStore  string                         `json:"credsStore"`
+	CredHelpers map[string]string              `json:"credHelpers"`
+	env         map[string]registry.AuthConfig // from DOCKER_AUTH_CONFIG, nil when unset or unusable
+}
+
+func loadDockerConfig(ctx context.Context) (*dockerConfig, error) {
+	dir := os.Getenv("DOCKER_CONFIG")
+	if dir == "" {
+		home, _ := os.UserHomeDir()
+		if home == "" && runtime.GOOS != "windows" {
+			if current, err := user.Current(); err == nil {
+				home = current.HomeDir
+			}
+		}
+		dir = filepath.Join(home, ".docker")
+	}
+	cfg := &dockerConfig{}
+	filename := filepath.Join(dir, "config.json")
+	file, err := os.Open(filename)
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return nil, fmt.Errorf("loading config file: %w", err)
+	}
+	if err == nil {
+		defer file.Close()
+		if err := json.NewDecoder(file).Decode(cfg); err != nil && !errors.Is(err, io.EOF) {
+			return nil, fmt.Errorf("parsing config file (%s): %w", filename, err)
+		}
+	}
+	for address, auth := range cfg.Auths {
+		if auth.Auth != "" {
+			if auth.Username, auth.Password, err = decodeAuth(auth.Auth); err != nil {
+				return nil, fmt.Errorf("parsing config file (%s): %w", filename, err)
+			}
+		}
+		auth.Auth, auth.ServerAddress = "", address
+		cfg.Auths[address] = auth
+	}
+	if value := os.Getenv("DOCKER_AUTH_CONFIG"); value != "" {
+		if cfg.env, err = parseDockerAuthConfigEnv(value); err != nil {
+			common.Logger(ctx).Warnf("Failed to create credential store from DOCKER_AUTH_CONFIG: %v", err)
+		}
+	}
+	return cfg, nil
+}
+
+func decodeAuth(auth string) (string, string, error) {
+	decoded, err := base64.StdEncoding.DecodeString(auth)
+	if err != nil {
+		return "", "", err
+	}
+	username, password, ok := strings.Cut(string(decoded), ":")
+	if !ok || username == "" {
+		return "", "", errors.New("invalid auth configuration file")
+	}
+	return username, strings.Trim(password, "\x00"), nil
+}
+
+func parseDockerAuthConfigEnv(value string) (map[string]registry.AuthConfig, error) {
+	var env struct {
+		Auths map[string]struct {
+			Auth string `json:"auth"`
+		} `json:"auths"`
+	}
+	decoder := json.NewDecoder(strings.NewReader(value))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&env); err != nil && !errors.Is(err, io.EOF) {
+		return nil, err
+	}
+	if decoder.More() {
+		return nil, errors.New("DOCKER_AUTH_CONFIG does not support more than one JSON object")
+	}
+	auths := make(map[string]registry.AuthConfig, len(env.Auths))
+	for address, entry := range env.Auths {
+		if entry.Auth == "" {
+			return nil, fmt.Errorf("DOCKER_AUTH_CONFIG environment variable is missing key `auth` for %s", address)
+		}
+		username, password, err := decodeAuth(entry.Auth)
+		if err != nil {
+			return nil, err
+		}
+		auths[address] = registry.AuthConfig{Username: username, Password: password, ServerAddress: address}
+	}
+	return auths, nil
+}
+
+func (c *dockerConfig) authConfig(ctx context.Context, key string) (registry.AuthConfig, error) {
+	if auth, ok := c.env[key]; ok {
+		return auth, nil
+	}
+	helper := c.CredsStore
+	if named, ok := c.CredHelpers[key]; ok {
+		helper = named
+	}
+	if helper == "" {
+		return c.fileAuth(key), nil
+	}
+	auth := c.fileAuth(key)
+	stored, err := helperCredentials(ctx, helper, key)
+	if err != nil {
+		return auth, err
+	}
+	auth.Username, auth.Password, auth.IdentityToken, auth.ServerAddress = stored.Username, stored.Password, stored.IdentityToken, stored.ServerAddress
+	return auth, nil
+}
+
+func (c *dockerConfig) fileAuth(key string) registry.AuthConfig {
+	if auth, ok := c.Auths[key]; ok {
+		return auth
+	}
+	for address, auth := range c.Auths {
+		if registryHostname(address) == key {
+			return auth
+		}
+	}
+	return registry.AuthConfig{}
+}
+
+func (c *dockerConfig) allAuthConfigs(ctx context.Context) (map[string]registry.AuthConfig, error) {
+	var auths map[string]registry.AuthConfig
+	if c.CredsStore == "" {
+		auths = maps.Clone(c.Auths)
+	} else {
+		var err error
+		if auths, err = c.helperAuthConfigs(ctx); err != nil {
+			if c.env == nil {
+				return nil, err
+			}
+			common.Logger(ctx).Warnf("Could not list the credentials of docker-credential-%s: %v", c.CredsStore, err)
+		}
+	}
+	if auths == nil {
+		auths = map[string]registry.AuthConfig{}
+	}
+	maps.Copy(auths, c.env)
+	if c.CredsStore == "" {
+		c.Auths = maps.Clone(auths) // docker's file store holds the DOCKER_AUTH_CONFIG entries after listing, and credHelpers set to "" read it
+	}
+	for address := range c.CredHelpers {
+		auth, err := c.authConfig(ctx, registryAuthConfigKey(address))
+		if err != nil {
+			common.Logger(ctx).Warnf("Failed to get credentials for registry: %s: %v", address, err)
+			continue
+		}
+		auths[address] = auth
+	}
+	return auths, nil
+}
+
+func (c *dockerConfig) helperAuthConfigs(ctx context.Context) (map[string]registry.AuthConfig, error) {
+	out, err := runCredentialHelper(ctx, c.CredsStore, "list", "unused")
+	if err != nil {
+		return nil, fmt.Errorf("error listing credentials - err: %w, out: `%s`", err, strings.TrimSpace(string(out)))
+	}
+	var addresses map[string]string
+	if err := json.NewDecoder(bytes.NewReader(out)).Decode(&addresses); err != nil {
+		return nil, err
+	}
+	auths := make(map[string]registry.AuthConfig, len(addresses))
+	for address := range addresses {
+		stored, err := helperCredentials(ctx, c.CredsStore, address)
+		if err != nil {
+			return nil, err
+		}
+		auth := c.Auths[address]
+		auth.Username, auth.Password, auth.IdentityToken = stored.Username, stored.Password, stored.IdentityToken
+		if auth.ServerAddress == "" {
+			auth.ServerAddress = stored.ServerAddress
+		}
+		auths[address] = auth
+	}
+	return auths, nil
+}
+
+func helperCredentials(ctx context.Context, helper, address string) (registry.AuthConfig, error) {
+	out, err := runCredentialHelper(ctx, helper, "get", address)
+	if err != nil {
+		if strings.TrimSpace(string(out)) == "credentials not found in native keychain" {
+			return registry.AuthConfig{}, nil
+		}
+		return registry.AuthConfig{}, fmt.Errorf("error getting credentials - err: %w, out: `%s`", err, strings.TrimSpace(string(out)))
+	}
+	var stored struct{ Username, Secret string }
+	if err := json.NewDecoder(bytes.NewReader(out)).Decode(&stored); err != nil {
+		return registry.AuthConfig{}, err
+	}
+	if stored.Username == "<token>" {
+		return registry.AuthConfig{IdentityToken: stored.Secret, ServerAddress: address}, nil
+	}
+	return registry.AuthConfig{Username: stored.Username, Password: stored.Secret, ServerAddress: address}, nil
+}
+
+func runCredentialHelper(ctx context.Context, helper, action, input string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, "docker-credential-"+helper, action)
+	cmd.Stdin = strings.NewReader(input)
+	cmd.Stderr = os.Stderr
+	return cmd.Output()
+}
+
+func registryHostname(address string) string {
+	if _, rest, ok := strings.Cut(address, "://"); ok {
+		if u, err := url.Parse(address); err == nil && u.Hostname() != "" {
+			if u.Port() == "" {
+				return u.Hostname()
+			}
+			return net.JoinHostPort(u.Hostname(), u.Port())
+		}
+		if host, _, _ := strings.Cut(rest, "/"); host != "" {
+			if colon := strings.LastIndex(host, ":"); strings.Count(host, ":") > 1 && !strings.HasPrefix(host, "[") && isDigits(host[colon+1:]) {
+				return net.JoinHostPort(host[:colon], host[colon+1:])
+			}
+			return host
+		}
+	}
+	host, _, _ := strings.Cut(address, "/")
+	return host
+}
+
+func isDigits(s string) bool {
+	return s != "" && strings.Trim(s, "0123456789") == ""
+}

act/container/docker_auth_test.go

@@ -0,0 +1,46 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !windows && !(WITHOUT_DOCKER || !(linux || darwin || netbsd || freebsd))
+
+package container
+
+import (
+	"encoding/base64"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/moby/moby/api/types/registry"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLoadDockerAuthConfigFromFileHelpersAndEnv(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "docker-credential-fake"), []byte("#!/bin/sh\nread -r server\n[ \"$1\" = get ] && [ \"$server\" = helper.example.com ] && exec echo '{\"Username\":\"helped\",\"Secret\":\"pw\"}'\necho 'credentials not found in native keychain'\nexit 1\n"), 0o755))
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	auth := func(credentials string) string { return base64.StdEncoding.EncodeToString([]byte(credentials)) }
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "config.json"), []byte(`{"auths": {"https://legacy.example.com/v1/": {"auth": "`+auth("legacy:pw")+`"}}, "credHelpers": {"helper.example.com": "fake", "gone.example.com": "fake", "env-legacy.example.com": ""}}`), 0o600))
+	t.Setenv("DOCKER_CONFIG", dir)
+	t.Setenv("DOCKER_AUTH_CONFIG", `{"auths": {"env.example.com": {"auth": "`+auth("env:pw")+`"}, "https://env-legacy.example.com/v1/": {"auth": "`+auth("env:pw")+`"}}}`)
+
+	for image, want := range map[string]registry.AuthConfig{
+		"legacy.example.com/app": {Username: "legacy", Password: "pw", ServerAddress: "https://legacy.example.com/v1/"},
+		"helper.example.com/app": {Username: "helped", Password: "pw", ServerAddress: "helper.example.com"},
+		"env.example.com/app":    {Username: "env", Password: "pw", ServerAddress: "env.example.com"},
+		"gone.example.com/app":   {},
+	} {
+		got, err := LoadDockerAuthConfig(t.Context(), image)
+		require.NoError(t, err)
+		assert.Equal(t, want, got, image)
+	}
+	assert.Equal(t, map[string]registry.AuthConfig{
+		"https://legacy.example.com/v1/":     {Username: "legacy", Password: "pw", ServerAddress: "https://legacy.example.com/v1/"},
+		"helper.example.com":                 {Username: "helped", Password: "pw", ServerAddress: "helper.example.com"},
+		"gone.example.com":                   {},
+		"env.example.com":                    {Username: "env", Password: "pw", ServerAddress: "env.example.com"},
+		"https://env-legacy.example.com/v1/": {Username: "env", Password: "pw", ServerAddress: "https://env-legacy.example.com/v1/"},
+		"env-legacy.example.com":             {Username: "env", Password: "pw", ServerAddress: "https://env-legacy.example.com/v1/"},
+	}, LoadDockerAuthConfigs(t.Context()))
+}

act/container/docker_build.go

@@ -2,20 +2,23 @@
 // Copyright 2020 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 
 import (
+	"archive/tar"
 	"context"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
-	"github.com/moby/go-archive"
-	"github.com/moby/go-archive/compression"
 	"github.com/moby/moby/client"
 	"github.com/moby/patternmatcher"
 	"github.com/moby/patternmatcher/ignorefile"
@@ -43,9 +46,8 @@ func NewDockerBuildExecutor(input NewDockerBuildExecutorInput) common.Executor {
 
 		logger.Debugf("Building image from '%v'", input.ContextDir)
 
-		tags := []string{input.ImageTag}
 		options := client.ImageBuildOptions{
-			Tags:        tags,
+			Tags:        []string{input.ImageTag},
 			Remove:      true,
 			AuthConfigs: LoadDockerAuthConfigs(ctx),
 			Dockerfile:  input.Dockerfile,
@@ -72,12 +74,10 @@ func NewDockerBuildExecutor(input NewDockerBuildExecutorInput) common.Executor {
 
 		logger.Debugf("Creating image from context dir '%s' with tag '%s' and platform '%s'", input.ContextDir, input.ImageTag, input.Platform)
 		resp, err := cli.ImageBuild(ctx, buildContext, options)
-
-		err = logDockerResponse(logger, resp.Body, err != nil)
 		if err != nil {
 			return err
 		}
-		return nil
+		return logDockerResponse(logger, resp.Body, false)
 	}
 }
 
@@ -115,14 +115,143 @@ func createBuildContext(ctx context.Context, contextDir, relDockerfile string) (
 		includes = append(includes, ".dockerignore", relDockerfile)
 	}
 
-	buildCtx, err := archive.TarWithOptions(contextDir, &archive.TarOptions{
-		Compression:     compression.None,
-		ExcludePatterns: excludes,
-		IncludeFiles:    includes,
-	})
+	pm, err := patternmatcher.New(excludes)
 	if err != nil {
 		return nil, err
 	}
-
-	return buildCtx, nil
+	reader, writer := io.Pipe()
+	go func() { writer.CloseWithError(writeBuildContext(ctx, writer, contextDir, includes, pm)) }()
+	return reader, nil
 }
+
+func writeBuildContext(ctx context.Context, w io.Writer, contextDir string, includes []string, pm *patternmatcher.PatternMatcher) error {
+	contextDir, err := filepath.EvalSymlinks(contextDir)
+	if err != nil {
+		return err
+	}
+	tw := tar.NewWriter(w)
+	seen := map[string]bool{}
+	hardlinks := map[uint64]string{}
+	buffer := make([]byte, 32*1024)
+	for _, include := range includes {
+		include = filepath.FromSlash(include)
+		var parents []parentMatch
+		err := filepath.WalkDir(filepath.Join(contextDir, include), func(file string, entry fs.DirEntry, err error) error {
+			if err != nil {
+				return leaveOut(ctx, file, err)
+			}
+			rel, err := filepath.Rel(contextDir, file)
+			if err != nil || rel == "." {
+				return nil
+			}
+			if rel != include {
+				for len(parents) > 0 && !strings.HasPrefix(rel, parents[len(parents)-1].dir+string(filepath.Separator)) {
+					parents = parents[:len(parents)-1]
+				}
+				var parentInfo patternmatcher.MatchInfo
+				if len(parents) > 0 {
+					parentInfo = parents[len(parents)-1].info
+				}
+				skip, info, err := pm.MatchesUsingParentResults(rel, parentInfo)
+				if err != nil {
+					return err
+				}
+				if entry.IsDir() {
+					parents = append(parents, parentMatch{rel, info})
+				}
+				if skip {
+					if entry.IsDir() && !hasExceptionWithin(pm, rel) {
+						return filepath.SkipDir
+					}
+					return nil
+				}
+			}
+			if seen[rel] {
+				return nil
+			}
+			seen[rel] = true
+			return addBuildContextEntry(ctx, tw, file, rel, entry, hardlinks, buffer)
+		})
+		if err != nil {
+			return err
+		}
+	}
+	return tw.Close()
+}
+
+type parentMatch struct {
+	dir  string
+	info patternmatcher.MatchInfo
+}
+
+func hasExceptionWithin(pm *patternmatcher.PatternMatcher, dir string) bool {
+	dirPrefix := dir + string(filepath.Separator)
+	for _, pattern := range pm.Patterns() {
+		if pattern.Exclusion() && strings.HasPrefix(pattern.String()+string(filepath.Separator), dirPrefix) {
+			return true
+		}
+	}
+	return false
+}
+
+func leaveOut(ctx context.Context, file string, err error) error {
+	common.Logger(ctx).Warnf("Leaving %s out of the build context: %v", file, err)
+	return nil
+}
+
+func addBuildContextEntry(ctx context.Context, tw *tar.Writer, file, rel string, entry fs.DirEntry, hardlinks map[uint64]string, buffer []byte) error {
+	info, err := entry.Info()
+	if err != nil {
+		return leaveOut(ctx, file, err)
+	}
+	if info.Mode()&fs.ModeSocket != 0 {
+		return nil // tar has no socket type
+	}
+	var link string
+	if info.Mode()&fs.ModeSymlink != 0 {
+		if link, err = os.Readlink(file); err != nil {
+			return leaveOut(ctx, file, err)
+		}
+	}
+	header, err := tar.FileInfoHeader(noNameLookups{info}, filepath.ToSlash(link))
+	if err != nil {
+		return err
+	}
+	header.Name = filepath.ToSlash(rel)
+	inode, linked := hardlinkInode(info)
+	if target, ok := hardlinks[inode]; linked && ok {
+		header.Typeflag, header.Linkname, header.Size = tar.TypeLink, target, 0
+	}
+	var content *os.File
+	if header.Typeflag == tar.TypeReg && header.Size > 0 {
+		if content, err = os.Open(file); err != nil {
+			return leaveOut(ctx, file, err)
+		}
+		defer content.Close()
+	}
+	if linked && header.Typeflag != tar.TypeLink {
+		hardlinks[inode] = header.Name
+	}
+	if info.IsDir() {
+		header.Name += "/"
+	}
+	header.Format = tar.FormatPAX
+	header.ModTime = header.ModTime.Truncate(time.Second)
+	header.AccessTime, header.ChangeTime = time.Time{}, time.Time{}
+	if runtime.GOOS == "windows" {
+		header.Mode = header.Mode&0o755 | 0o111 // Windows has no exec bit, so mark everything executable like docker build
+	}
+	if err := tw.WriteHeader(header); err != nil {
+		return err
+	}
+	if content != nil {
+		_, err = io.CopyBuffer(tw, struct{ io.Reader }{content}, buffer) // hides os.File's WriteTo, which would allocate a buffer per file
+	}
+	return err
+}
+
+type noNameLookups struct{ fs.FileInfo } // leaves Uname and Gname empty like docker build, so packing never waits on NSS
+
+func (noNameLookups) Uname() (string, error) { return "", nil }
+
+func (noNameLookups) Gname() (string, error) { return "", nil }

act/container/docker_build_test.go

@@ -0,0 +1,71 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
+
+package container
+
+import (
+	"archive/tar"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestDockerBuildReportsDaemonError(t *testing.T) {
+	daemon := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		writer.Header().Set("API-Version", "1.47")
+		if strings.HasSuffix(request.URL.Path, "/build") {
+			writer.Header().Set("Content-Type", "application/json")
+			writer.WriteHeader(http.StatusInternalServerError)
+			_, _ = io.WriteString(writer, `{"message":"build rejected"}`)
+		}
+	}))
+	t.Cleanup(daemon.Close)
+	t.Setenv("DOCKER_HOST", daemon.URL)
+	t.Setenv("DOCKER_CONFIG", t.TempDir())
+	t.Setenv("DOCKER_AUTH_CONFIG", "")
+
+	require.ErrorContains(t, NewDockerBuildExecutor(NewDockerBuildExecutorInput{
+		ImageTag: "action:test", Dockerfile: "Dockerfile", BuildContext: strings.NewReader(""),
+	})(t.Context()), "build rejected")
+}
+
+func TestCreateBuildContextFollowsDockerignoreAndSymlinkedRootButKeepsDockerfile(t *testing.T) {
+	dir := t.TempDir()
+	for name, content := range map[string]string{
+		".dockerignore": "*.log\nbuild\n!build/keep.txt\nDockerfile", "Dockerfile": "FROM scratch", "a.txt": "a",
+		"a.log": "log", "build/drop.txt": "drop", "build/keep.txt": "keep",
+	} {
+		require.NoError(t, os.MkdirAll(filepath.Join(dir, filepath.Dir(name)), 0o755))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644))
+	}
+	require.NoError(t, os.Mkdir(filepath.Join(dir, "empty"), 0o755))
+
+	contexts := []string{dir}
+	if link := filepath.Join(t.TempDir(), "link"); os.Symlink(dir, link) == nil {
+		contexts = append(contexts, link, link+string(filepath.Separator))
+	}
+
+	for _, contextDir := range contexts {
+		buildContext, err := createBuildContext(t.Context(), contextDir, "Dockerfile")
+		require.NoError(t, err)
+		var names []string
+		for reader := tar.NewReader(buildContext); ; {
+			header, err := reader.Next()
+			if err == io.EOF {
+				break
+			}
+			require.NoError(t, err)
+			names = append(names, header.Name)
+		}
+		require.NoError(t, buildContext.Close())
+		require.Equal(t, []string{".dockerignore", "a.txt", "build/keep.txt", "empty/", "Dockerfile"}, names, contextDir)
+	}
+}

act/container/docker_build_unix.go

@@ -0,0 +1,18 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !WITHOUT_DOCKER && (linux || darwin || netbsd || freebsd)
+
+package container
+
+import (
+	"io/fs"
+	"syscall"
+)
+
+func hardlinkInode(info fs.FileInfo) (uint64, bool) {
+	if stat, ok := info.Sys().(*syscall.Stat_t); ok && !info.IsDir() && stat.Nlink > 1 {
+		return stat.Ino, true
+	}
+	return 0, false
+}

act/container/docker_build_unix_test.go

@@ -0,0 +1,35 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !WITHOUT_DOCKER && (linux || darwin || netbsd || freebsd)
+
+package container
+
+import (
+	"archive/tar"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCreateBuildContextKeepsHardlinkedSpecialFilesLinked(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "first"), 0o644))
+	require.NoError(t, os.Link(filepath.Join(dir, "first"), filepath.Join(dir, "second")))
+
+	buildContext, err := createBuildContext(t.Context(), dir, "Dockerfile")
+	require.NoError(t, err)
+	defer buildContext.Close()
+	reader := tar.NewReader(buildContext)
+	first, err := reader.Next()
+	require.NoError(t, err)
+	assert.Equal(t, byte(tar.TypeFifo), first.Typeflag)
+	second, err := reader.Next()
+	require.NoError(t, err)
+	assert.Equal(t, byte(tar.TypeLink), second.Typeflag)
+	assert.Equal(t, first.Name, second.Linkname)
+}

act/container/docker_build_windows.go

@@ -0,0 +1,10 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !WITHOUT_DOCKER
+
+package container
+
+import "io/fs"
+
+func hardlinkInode(_info fs.FileInfo) (uint64, bool) { return 0, false }

act/container/docker_cli.go

@@ -2,12 +2,14 @@
 // Copyright 2022 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
-// This file is exact copy of https://github.com/docker/cli/blob/dfc4efb1e2ab8c06d70d2a1366ad448d2f917e90/cli/command/container/opts.go with:
+// This file is based on https://github.com/docker/cli/blob/4a63305d74332de5ceba7fcbccbc3cbb7412f5ba/cli/command/container/opts.go with:
 // * appended with license information
-// * regexp and loader.ParseVolume in place of the import-restricted internal/lazyregexp and internal/volumespec
-// * invalidParameter from the package's errors.go, and convertPortSet/convertPortMap for the callers in docker_run.go
+// * regexp and ParseVolume in place of the import-restricted internal/lazyregexp and internal/volumespec
+// * cdiDeviceName in place of the container-device-interface parser's IsQualifiedName
+// * jsontext in place of json.Compact for the seccomp profile
+// * invalidParameter from the package's errors.go, and convertPortSet/convertPortMap for nat port types
 //
 // docker/cli is licensed under the Apache License, Version 2.0.
 // See DOCKER_LICENSE for the full license text.
@@ -17,8 +19,7 @@
 package container
 
 import (
-	"bytes"
-	"encoding/json"
+	"encoding/json/jsontext"
 	"errors"
 	"fmt"
 	"net"
@@ -33,14 +34,12 @@ import (
 	"time"
 
 	cerrdefs "github.com/containerd/errdefs"
-	"github.com/docker/cli/cli/compose/loader"
 	"github.com/docker/cli/opts"
 	"github.com/docker/go-connections/nat"
 	"github.com/moby/moby/api/types/container"
 	"github.com/moby/moby/api/types/mount"
 	"github.com/moby/moby/api/types/network"
 	"github.com/spf13/pflag"
-	cdi "tags.cncf.io/container-device-interface/pkg/parser"
 )
 
 const (
@@ -153,10 +152,8 @@ type containerOptions struct {
 	runtime             string
 	autoRemove          bool
 	init                bool
+	umask               opts.UmaskOpt
 	annotations         *opts.MapOpts
-
-	Image string
-	Args  []string
 }
 
 // addFlags adds all command line flags that will be used by parse to the FlagSet
@@ -327,6 +324,9 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
 	flags.Var(&copts.shmSize, "shm-size", "Size of /dev/shm")
 	flags.StringVar(&copts.utsMode, "uts", "", "UTS namespace to use")
 	flags.StringVar(&copts.runtime, "runtime", "", "Runtime to use for this container")
+	flags.Var(&copts.umask, "umask", "Set umask for the container")
+	flags.SetAnnotation("umask", "version", []string{"1.56"})
+	flags.SetAnnotation("umask", "ostype", []string{"linux"})
 
 	flags.BoolVar(&copts.init, "init", false, "Run an init inside the container that forwards signals and reaps processes")
 	flags.SetAnnotation("init", "version", []string{"1.25"})
@@ -384,7 +384,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 	volumes := copts.volumes.GetMap()
 	// add any bind targets to the list of container volumes
 	for bind := range volumes {
-		parsed, err := loader.ParseVolume(bind)
+		parsed, err := ParseVolume(bind)
 		if err != nil {
 			return nil, err
 		}
@@ -392,7 +392,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 		if parsed.Source != "" {
 			toBind := bind
 
-			if parsed.Type == string(mount.TypeBind) {
+			if parsed.Type == mount.TypeBind {
 				if hostPart, targetPath, ok := strings.Cut(bind, ":"); ok {
 					if !filepath.IsAbs(hostPart) && strings.HasPrefix(hostPart, ".") {
 						if absHostPart, err := filepath.Abs(hostPart); err == nil {
@@ -419,12 +419,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 		tmpfs[k] = v
 	}
 
-	var runCmd, entrypoint []string
-
-	if len(copts.Args) > 0 {
-		runCmd = copts.Args
-	}
-
+	var entrypoint []string
 	if copts.entrypoint != "" {
 		entrypoint = []string{copts.entrypoint}
 	} else if flags.Changed("entrypoint") {
@@ -445,36 +440,15 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 	if err != nil {
 		return nil, err
 	}
-	portBindings := network.PortMap{}
-	for port, bindings := range natPortBindings {
-		p, err := network.ParsePort(string(port))
-		if err != nil {
-			return nil, err
-		}
-		portBindings[p] = []network.PortBinding{}
-		for _, b := range bindings {
-			var hostIP netip.Addr
-			if b.HostIP != "" {
-				hostIP, err = netip.ParseAddr(b.HostIP)
-				if err != nil {
-					return nil, err
-				}
-			}
-			portBindings[p] = append(portBindings[p], network.PortBinding{
-				HostIP:   hostIP,
-				HostPort: b.HostPort,
-			})
-		}
+	portBindings, err := convertPortMap(natPortBindings)
+	if err != nil {
+		return nil, err
 	}
 
 	// Add published ports as exposed ports.
-	exposedPorts := network.PortSet{}
-	for port := range ports {
-		p, err := network.ParsePort(string(port))
-		if err != nil {
-			return nil, err
-		}
-		exposedPorts[p] = struct{}{}
+	exposedPorts, err := convertPortSet(ports)
+	if err != nil {
+		return nil, err
 	}
 
 	// Merge in exposed ports to the map of published ports
@@ -500,7 +474,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 	deviceMappings := make([]container.DeviceMapping, 0, len(devices))
 	cdiDeviceNames := make([]string, 0, len(devices))
 	for _, device := range devices {
-		if cdi.IsQualifiedName(device) {
+		if cdiDeviceName.MatchString(device) {
 			cdiDeviceNames = append(cdiDeviceNames, device)
 			continue
 		}
@@ -615,11 +589,10 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 
 	deviceRequests := copts.gpus.Value()
 	if len(cdiDeviceNames) > 0 {
-		cdiDeviceRequest := container.DeviceRequest{
+		deviceRequests = append(deviceRequests, container.DeviceRequest{
 			Driver:    "cdi",
 			DeviceIDs: cdiDeviceNames,
-		}
-		deviceRequests = append(deviceRequests, cdiDeviceRequest)
+		})
 	}
 
 	resources := container.Resources{
@@ -665,8 +638,6 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 		AttachStdout: attachStdout,
 		AttachStderr: attachStderr,
 		Env:          envVariables,
-		Cmd:          runCmd,
-		Image:        copts.Image,
 		Volumes:      volumes,
 		Entrypoint:   entrypoint,
 		WorkingDir:   copts.workingDir,
@@ -722,6 +693,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 		MaskedPaths:    maskedPaths,
 		ReadonlyPaths:  readonlyPaths,
 		Annotations:    copts.annotations.GetAll(),
+		Umask:          copts.umask.Value(),
 	}
 
 	if copts.autoRemove && !hostConfig.RestartPolicy.IsNone() {
@@ -752,6 +724,10 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 	}, nil
 }
 
+func isUserDefinedNetwork(mode container.NetworkMode) bool { // Docker's helper uses the host OS instead of the daemon's.
+	return !mode.IsDefault() && mode != network.NetworkBridge && mode != network.NetworkHost && !mode.IsNone() && !mode.IsContainer()
+}
+
 // parseNetworkOpts converts --network advanced options to endpoint-specs, and combines
 // them with the old --network-alias and --links. If returns an error if conflicting options
 // are found.
@@ -780,7 +756,7 @@ func parseNetworkOpts(copts *containerOptions) (map[string]*network.EndpointSett
 	}
 
 	for i, n := range copts.netMode.Value() {
-		if container.NetworkMode(n.Target).IsUserDefined() {
+		if isUserDefinedNetwork(container.NetworkMode(n.Target)) {
 			hasUserDefined = true
 		} else {
 			hasNonUserDefined = true
@@ -806,10 +782,8 @@ func parseNetworkOpts(copts *containerOptions) (map[string]*network.EndpointSett
 		// For backward compatibility: if no custom options are provided for the network,
 		// and only a single network is specified, omit the endpoint-configuration
 		// on the client (the daemon will still create it when creating the container)
-		if i == 0 && len(copts.netMode.Value()) == 1 {
-			if ep == nil || reflect.ValueOf(*ep).IsZero() {
-				continue
-			}
+		if i == 0 && len(copts.netMode.Value()) == 1 && reflect.ValueOf(*ep).IsZero() {
+			continue
 		}
 		endpoints[n.Target] = ep
 	}
@@ -840,14 +814,12 @@ func applyContainerOptions(n *opts.NetworkAttachmentOpts, copts *containerOption
 		return invalidParameter(errors.New("conflicting options: cannot specify both --link-local-ip and per-network link-local IP addresses"))
 	}
 	if copts.aliases.Len() > 0 {
-		n.Aliases = make([]string, copts.aliases.Len())
-		copy(n.Aliases, copts.aliases.GetSlice())
+		n.Aliases = slices.Clone(copts.aliases.GetSlice())
 	}
 	// For a user-defined network, "--link" is an endpoint option, it creates an alias. But,
 	// for the default bridge it defines a legacy-link.
-	if container.NetworkMode(n.Target).IsUserDefined() && copts.links.Len() > 0 {
-		n.Links = make([]string, copts.links.Len())
-		copy(n.Links, copts.links.GetSlice())
+	if isUserDefinedNetwork(container.NetworkMode(n.Target)) && copts.links.Len() > 0 {
+		n.Links = slices.Clone(copts.links.GetSlice())
 	}
 	if copts.ipv4Address != nil {
 		if ipv4, ok := netip.AddrFromSlice(copts.ipv4Address.To4()); ok {
@@ -872,7 +844,7 @@ func parseNetworkAttachmentOpt(ep opts.NetworkAttachmentOpts) (*network.Endpoint
 	if strings.TrimSpace(ep.Target) == "" {
 		return nil, errors.New("no name set for network")
 	}
-	if !container.NetworkMode(ep.Target).IsUserDefined() {
+	if !isUserDefinedNetwork(container.NetworkMode(ep.Target)) {
 		if len(ep.Aliases) > 0 {
 			return nil, errors.New("network-scoped aliases are only supported for user-defined networks")
 		}
@@ -886,7 +858,6 @@ func parseNetworkAttachmentOpt(ep opts.NetworkAttachmentOpts) (*network.Endpoint
 	}
 	epConfig.Aliases = append(epConfig.Aliases, ep.Aliases...)
 	if len(ep.DriverOpts) > 0 {
-		epConfig.DriverOpts = make(map[string]string)
 		epConfig.DriverOpts = ep.DriverOpts
 	}
 	if len(ep.Links) > 0 {
@@ -930,11 +901,10 @@ func convertToStandardNotation(ports []string) ([]string, error) {
 }
 
 func parseLoggingOpts(loggingDriver string, loggingOpts []string) (map[string]string, error) {
-	loggingOptsMap := opts.ConvertKVStringsToMap(loggingOpts)
 	if loggingDriver == "none" && len(loggingOpts) > 0 {
 		return map[string]string{}, fmt.Errorf("invalid logging opts for driver %s", loggingDriver)
 	}
-	return loggingOptsMap, nil
+	return opts.ConvertKVStringsToMap(loggingOpts), nil
 }
 
 // takes a local seccomp daemon, reads the file contents for sending to the daemon
@@ -959,11 +929,11 @@ func parseSecurityOpts(securityOpts []string) ([]string, error) {
 				if err != nil {
 					return securityOpts, fmt.Errorf("opening seccomp profile (%s) failed: %w", v, err)
 				}
-				var b bytes.Buffer
-				if err := json.Compact(&b, f); err != nil {
+				profile := jsontext.Value(f)
+				if err := profile.Compact(); err != nil {
 					return securityOpts, fmt.Errorf("compacting json for seccomp profile (%s) failed: %w", v, err)
 				}
-				securityOpts[key] = "seccomp=" + b.String()
+				securityOpts[key] = "seccomp=" + string(profile)
 			}
 		}
 	}
@@ -1192,6 +1162,8 @@ func convertPortSet(ports nat.PortSet) (network.PortSet, error) {
 	return converted, nil
 }
 
+var cdiDeviceName = regexp.MustCompile(`^[a-zA-Z]([a-zA-Z0-9_.-]*[a-zA-Z0-9])?/[a-zA-Z]([a-zA-Z0-9_.-]*[a-zA-Z0-9])?=[a-zA-Z0-9]([a-zA-Z0-9_.:-]*[a-zA-Z0-9])?$`)
+
 func convertPortMap(bindings nat.PortMap) (network.PortMap, error) {
 	converted := make(network.PortMap, len(bindings))
 	for port, portBindings := range bindings {

act/container/docker_cli_test.go

@@ -2,7 +2,7 @@
 // Copyright 2022 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-// This file is exact copy of https://github.com/docker/cli/blob/dfc4efb1e2ab8c06d70d2a1366ad448d2f917e90/cli/command/container/opts_test.go with:
+// This file is based on https://github.com/docker/cli/blob/4a63305d74332de5ceba7fcbccbc3cbb7412f5ba/cli/command/container/opts_test.go with:
 // * appended with license information
 // * added tests for the locally changed parseDevice, validateDevice and invalidParameter
 //
@@ -25,13 +25,11 @@ import (
 	"testing"
 	"time"
 
-	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/moby/moby/api/types/container"
 	networktypes "github.com/moby/moby/api/types/network"
 	"github.com/spf13/pflag"
-	"gotest.tools/v3/assert"
-	is "gotest.tools/v3/assert/cmp"
-	"gotest.tools/v3/skip"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func mustParseMAC(s string) networktypes.HardwareAddr {
@@ -71,7 +69,6 @@ func parseRun(args []string) (*container.Config, *container.HostConfig, *network
 	if err := flags.Parse(args); err != nil {
 		return nil, nil, nil, err
 	}
-	// TODO(dnephin): fix tests to accept ContainerConfig; see https://github.com/moby/moby/pull/31621
 	containerCfg, err := parse(flags, copts, runtime.GOOS)
 	if err != nil {
 		return nil, nil, nil, err
@@ -83,14 +80,13 @@ func setupRunFlags() (*pflag.FlagSet, *containerOptions) {
 	flags := pflag.NewFlagSet("run", pflag.ContinueOnError)
 	flags.SetOutput(io.Discard)
 	flags.Usage = nil
-	copts := addFlags(flags)
-	return flags, copts
+	return flags, addFlags(flags)
 }
 
 func mustParse(t *testing.T, args string) (*container.Config, *container.HostConfig, *networktypes.NetworkingConfig) {
 	t.Helper()
-	config, hostConfig, nwConfig, err := parseRun(append(strings.Split(args, " "), "ubuntu", "bash"))
-	assert.NilError(t, err)
+	config, hostConfig, nwConfig, err := parseRun(strings.Split(args, " "))
+	require.NoError(t, err)
 	return config, hostConfig, nwConfig
 }
 
@@ -156,65 +152,46 @@ func TestParseRunLinks(t *testing.T) {
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			_, hostConfig, netConfig := mustParse(t, tc.input)
-			assert.Check(t, is.DeepEqual(hostConfig.Links, tc.expHostConfigLinks))
-			assert.Check(t, is.Len(netConfig.EndpointsConfig, len(tc.expNetConfigLinks)))
+			assert.Equal(t, tc.expHostConfigLinks, hostConfig.Links)
+			assert.Len(t, netConfig.EndpointsConfig, len(tc.expNetConfigLinks))
 			for netName, expLinks := range tc.expNetConfigLinks {
 				nc, ok := netConfig.EndpointsConfig[netName]
-				assert.Assert(t, ok)
-				assert.Check(t, is.DeepEqual(nc.Links, expLinks))
+				require.True(t, ok)
+				assert.Equal(t, expLinks, nc.Links)
 			}
 		})
 	}
 }
 
+func TestParseRunWithoutUmask(t *testing.T) {
+	_, hostConfig, _, err := parseRun([]string{"ubuntu", "bash"})
+	require.NoError(t, err)
+	require.Nil(t, hostConfig.Umask)
+}
+
+func TestParseRunUmask(t *testing.T) {
+	_, hostConfig, _, err := parseRun([]string{"--umask", "0022", "ubuntu", "bash"})
+	require.NoError(t, err)
+	require.NotNil(t, hostConfig.Umask)
+	require.Equal(t, uint32(0o22), *hostConfig.Umask)
+}
+
 func TestParseRunAttach(t *testing.T) {
-	tests := []struct {
-		input    string
-		expected container.Config
+	for _, tc := range []struct {
+		input                 string
+		stdin, stdout, stderr bool
 	}{
-		{
-			input: "",
-			expected: container.Config{
-				AttachStdout: true,
-				AttachStderr: true,
-			},
-		},
-		{
-			input: "-i",
-			expected: container.Config{
-				AttachStdin:  true,
-				AttachStdout: true,
-				AttachStderr: true,
-			},
-		},
-		{
-			input: "-a stdin",
-			expected: container.Config{
-				AttachStdin: true,
-			},
-		},
-		{
-			input: "-a stdin -a stdout",
-			expected: container.Config{
-				AttachStdin:  true,
-				AttachStdout: true,
-			},
-		},
-		{
-			input: "-a stdin -a stdout -a stderr",
-			expected: container.Config{
-				AttachStdin:  true,
-				AttachStdout: true,
-				AttachStderr: true,
-			},
-		},
-	}
-	for _, tc := range tests {
+		{"", false, true, true},
+		{"-i", true, true, true},
+		{"-a stdin", true, false, false},
+		{"-a stdin -a stdout", true, true, false},
+		{"-a stdin -a stdout -a stderr", true, true, true},
+	} {
 		t.Run(tc.input, func(t *testing.T) {
 			config, _, _ := mustParse(t, tc.input)
-			assert.Equal(t, config.AttachStdin, tc.expected.AttachStdin)
-			assert.Equal(t, config.AttachStdout, tc.expected.AttachStdout)
-			assert.Equal(t, config.AttachStderr, tc.expected.AttachStderr)
+			require.Equal(t, tc.stdin, config.AttachStdin)
+			require.Equal(t, tc.stdout, config.AttachStdout)
+			require.Equal(t, tc.stderr, config.AttachStderr)
 		})
 	}
 }
@@ -260,109 +237,52 @@ func TestParseRunWithInvalidArgs(t *testing.T) {
 	flags, _ := setupRunFlags()
 	for _, tc := range tests {
 		t.Run(strings.Join(tc.args, " "), func(t *testing.T) {
-			assert.Error(t, flags.Parse(tc.args), tc.error)
+			require.EqualError(t, flags.Parse(tc.args), tc.error)
 		})
 	}
 }
 
-func TestParseWithVolumes(t *testing.T) { //nolint:gocyclo // verbatim copy from docker/cli tests
-	// A single volume
-	arr, tryit := setupPlatformVolume([]string{`/tmp`}, []string{`c:\tmp`})
-	if config, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds != nil {
-		t.Fatalf("Error parsing volume flags, %q should not mount-bind anything. Received %v", tryit, hostConfig.Binds)
-	} else if _, exists := config.Volumes[arr[0]]; !exists {
-		t.Fatalf("Error parsing volume flags, %q is missing from volumes. Received %v", tryit, config.Volumes)
-	}
-
-	// Two volumes
-	arr, tryit = setupPlatformVolume([]string{`/tmp`, `/var`}, []string{`c:\tmp`, `c:\var`})
-	if config, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds != nil {
-		t.Fatalf("Error parsing volume flags, %q should not mount-bind anything. Received %v", tryit, hostConfig.Binds)
-	} else if _, exists := config.Volumes[arr[0]]; !exists {
-		t.Fatalf("Error parsing volume flags, %s is missing from volumes. Received %v", arr[0], config.Volumes)
-	} else if _, exists := config.Volumes[arr[1]]; !exists {
-		t.Fatalf("Error parsing volume flags, %s is missing from volumes. Received %v", arr[1], config.Volumes)
-	}
-
-	// A single bind mount
-	arr, tryit = setupPlatformVolume([]string{`/hostTmp:/containerTmp`}, []string{os.Getenv("TEMP") + `:c:\containerTmp`})
-	if config, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds == nil || hostConfig.Binds[0] != arr[0] {
-		t.Fatalf("Error parsing volume flags, %q should mount-bind the path before the colon into the path after the colon. Received %v %v", arr[0], hostConfig.Binds, config.Volumes)
-	}
-
-	// Two bind mounts.
-	arr, tryit = setupPlatformVolume([]string{`/hostTmp:/containerTmp`, `/hostVar:/containerVar`}, []string{os.Getenv("ProgramData") + `:c:\ContainerPD`, os.Getenv("TEMP") + `:c:\containerTmp`})
-	if _, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds == nil || compareRandomizedStrings(hostConfig.Binds[0], hostConfig.Binds[1], arr[0], arr[1]) != nil {
-		t.Fatalf("Error parsing volume flags, `%s and %s` did not mount-bind correctly. Received %v", arr[0], arr[1], hostConfig.Binds)
-	}
-
-	// Two bind mounts, first read-only, second read-write.
-	// TODO Windows: The Windows version uses read-write as that's the only mode it supports. Can change this post TP4
-	arr, tryit = setupPlatformVolume(
-		[]string{`/hostTmp:/containerTmp:ro`, `/hostVar:/containerVar:rw`},
-		[]string{os.Getenv("TEMP") + `:c:\containerTmp:rw`, os.Getenv("ProgramData") + `:c:\ContainerPD:rw`})
-	if _, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds == nil || compareRandomizedStrings(hostConfig.Binds[0], hostConfig.Binds[1], arr[0], arr[1]) != nil {
-		t.Fatalf("Error parsing volume flags, `%s and %s` did not mount-bind correctly. Received %v", arr[0], arr[1], hostConfig.Binds)
-	}
-
-	// Similar to previous test but with alternate modes which are only supported by Linux
-	if runtime.GOOS != "windows" {
-		arr, tryit = setupPlatformVolume([]string{`/hostTmp:/containerTmp:ro,Z`, `/hostVar:/containerVar:rw,Z`}, []string{})
-		if _, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds == nil || compareRandomizedStrings(hostConfig.Binds[0], hostConfig.Binds[1], arr[0], arr[1]) != nil {
-			t.Fatalf("Error parsing volume flags, `%s and %s` did not mount-bind correctly. Received %v", arr[0], arr[1], hostConfig.Binds)
+func TestParseWithVolumes(t *testing.T) {
+	for _, tc := range []struct {
+		unix, windows []string
+		binds         int
+	}{
+		{[]string{`/tmp`}, []string{`c:\tmp`}, 0},
+		{[]string{`/tmp`, `/var`}, []string{`c:\tmp`, `c:\var`}, 0},
+		{[]string{`/hostTmp:/containerTmp`}, []string{os.Getenv("TEMP") + `:c:\containerTmp`}, 1},
+		{[]string{`/hostTmp:/containerTmp`, `/hostVar:/containerVar`}, []string{os.Getenv("ProgramData") + `:c:\ContainerPD`, os.Getenv("TEMP") + `:c:\containerTmp`}, 2},
+		{[]string{`/hostTmp:/containerTmp:ro`, `/hostVar:/containerVar:rw`}, []string{os.Getenv("TEMP") + `:c:\containerTmp:rw`, os.Getenv("ProgramData") + `:c:\ContainerPD:rw`}, 2},
+		{[]string{`/hostTmp:/containerTmp:ro,Z`, `/hostVar:/containerVar:rw,Z`}, nil, 2},
+		{[]string{`/hostTmp:/containerTmp:Z`, `/hostVar:/containerVar:z`}, nil, 2},
+		{[]string{`/hostTmp:/containerTmp`, `/containerVar`}, []string{os.Getenv("TEMP") + `:c:\containerTmp`, `c:\containerTmp`}, 1},
+		{nil, []string{os.Getenv("SystemDrive") + `\:d:`}, 1},
+	} {
+		volumes := tc.unix
+		if runtime.GOOS == "windows" {
+			volumes = tc.windows
 		}
-
-		arr, tryit = setupPlatformVolume([]string{`/hostTmp:/containerTmp:Z`, `/hostVar:/containerVar:z`}, []string{})
-		if _, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds == nil || compareRandomizedStrings(hostConfig.Binds[0], hostConfig.Binds[1], arr[0], arr[1]) != nil {
-			t.Fatalf("Error parsing volume flags, `%s and %s` did not mount-bind correctly. Received %v", arr[0], arr[1], hostConfig.Binds)
+		if len(volumes) == 0 {
+			continue
 		}
+		t.Run(strings.Join(volumes, ","), func(t *testing.T) {
+			var args []string
+			for _, volume := range volumes {
+				args = append(args, "-v", volume)
+			}
+			config, hostConfig, _, err := parseRun(args)
+			require.NoError(t, err)
+			if tc.binds == 0 {
+				assert.Nil(t, hostConfig.Binds)
+			} else {
+				assert.ElementsMatch(t, volumes[:tc.binds], hostConfig.Binds)
+			}
+			expectedVolumes := map[string]struct{}{}
+			for _, volume := range volumes[tc.binds:] {
+				expectedVolumes[volume] = struct{}{}
+			}
+			assert.Equal(t, expectedVolumes, config.Volumes)
+		})
 	}
-
-	// One bind mount and one volume
-	arr, tryit = setupPlatformVolume([]string{`/hostTmp:/containerTmp`, `/containerVar`}, []string{os.Getenv("TEMP") + `:c:\containerTmp`, `c:\containerTmp`})
-	if config, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds == nil || len(hostConfig.Binds) > 1 || hostConfig.Binds[0] != arr[0] {
-		t.Fatalf("Error parsing volume flags, %s and %s should only one and only one bind mount %s. Received %s", arr[0], arr[1], arr[0], hostConfig.Binds)
-	} else if _, exists := config.Volumes[arr[1]]; !exists {
-		t.Fatalf("Error parsing volume flags %s and %s. %s is missing from volumes. Received %v", arr[0], arr[1], arr[1], config.Volumes)
-	}
-
-	// Root to non-c: drive letter (Windows specific)
-	if runtime.GOOS == "windows" {
-		arr, tryit = setupPlatformVolume([]string{}, []string{os.Getenv("SystemDrive") + `\:d:`})
-		if config, hostConfig, _ := mustParse(t, tryit); hostConfig.Binds == nil || len(hostConfig.Binds) > 1 || hostConfig.Binds[0] != arr[0] || len(config.Volumes) != 0 {
-			t.Fatalf("Error parsing %s. Should have a single bind mount and no volumes", arr[0])
-		}
-	}
-}
-
-// setupPlatformVolume takes two arrays of volume specs - a Unix style
-// spec and a Windows style spec. Depending on the platform being unit tested,
-// it returns one of them, along with a volume string that would be passed
-// on the docker CLI (e.g. -v /bar -v /foo).
-func setupPlatformVolume(u, w []string) ([]string, string) {
-	var a []string
-	if runtime.GOOS == "windows" {
-		a = w
-	} else {
-		a = u
-	}
-	s := ""
-	for _, v := range a {
-		s = s + "-v " + v + " "
-	}
-	return a, s
-}
-
-// check if (a == c && b == d) || (a == d && b == c)
-// because maps are randomized
-func compareRandomizedStrings(a, b, c, d string) error {
-	if a == c && b == d {
-		return nil
-	}
-	if a == d && b == c {
-		return nil
-	}
-	return errors.New("strings don't match")
 }
 
 // Simple parse with MacAddress validation
@@ -383,66 +303,49 @@ func TestRunFlagsParseWithMemory(t *testing.T) {
 	flags, _ := setupRunFlags()
 	args := []string{"--memory=invalid", "img", "cmd"}
 	err := flags.Parse(args)
-	assert.ErrorContains(t, err, `invalid argument "invalid" for "-m, --memory" flag`)
+	require.ErrorContains(t, err, `invalid argument "invalid" for "-m, --memory" flag`)
 
 	_, hostconfig, _ := mustParse(t, "--memory=1G")
-	assert.Check(t, is.Equal(int64(1073741824), hostconfig.Memory))
+	assert.Equal(t, int64(1073741824), hostconfig.Memory)
 }
 
 func TestParseWithMemorySwap(t *testing.T) {
 	flags, _ := setupRunFlags()
 	args := []string{"--memory-swap=invalid", "img", "cmd"}
 	err := flags.Parse(args)
-	assert.ErrorContains(t, err, `invalid argument "invalid" for "--memory-swap" flag`)
+	require.ErrorContains(t, err, `invalid argument "invalid" for "--memory-swap" flag`)
 
 	_, hostconfig, _ := mustParse(t, "--memory-swap=1G")
-	assert.Check(t, is.Equal(int64(1073741824), hostconfig.MemorySwap))
+	assert.Equal(t, int64(1073741824), hostconfig.MemorySwap)
 
 	_, hostconfig, _ = mustParse(t, "--memory-swap=-1")
-	assert.Check(t, is.Equal(int64(-1), hostconfig.MemorySwap))
+	assert.Equal(t, int64(-1), hostconfig.MemorySwap)
 }
 
 func TestParseHostname(t *testing.T) {
-	validHostnames := map[string]string{
-		"hostname":    "hostname",
-		"host-name":   "host-name",
-		"hostname123": "hostname123",
-		"123hostname": "123hostname",
-		"hostname-of-63-bytes-long-should-be-valid-and-without-any-error": "hostname-of-63-bytes-long-should-be-valid-and-without-any-error",
-	}
-	hostnameWithDomain := "--hostname=hostname.domainname"
-	hostnameWithDomainTld := "--hostname=hostname.domainname.tld"
-	for hostname, expectedHostname := range validHostnames {
-		if config, _, _ := mustParse(t, "--hostname="+hostname); config.Hostname != expectedHostname {
-			t.Fatalf("Expected the config to have 'hostname' as %q, got %q", expectedHostname, config.Hostname)
-		}
-	}
-	if config, _, _ := mustParse(t, hostnameWithDomain); config.Hostname != "hostname.domainname" || config.Domainname != "" {
-		t.Fatalf("Expected the config to have 'hostname' as hostname.domainname, got %q", config.Hostname)
-	}
-	if config, _, _ := mustParse(t, hostnameWithDomainTld); config.Hostname != "hostname.domainname.tld" || config.Domainname != "" {
-		t.Fatalf("Expected the config to have 'hostname' as hostname.domainname.tld, got %q", config.Hostname)
-	}
-}
-
-func TestParseHostnameDomainname(t *testing.T) {
-	validDomainnames := map[string]string{
-		"domainname":    "domainname",
-		"domain-name":   "domain-name",
-		"domainname123": "domainname123",
-		"123domainname": "123domainname",
-		"domainname-63-bytes-long-should-be-valid-and-without-any-errors": "domainname-63-bytes-long-should-be-valid-and-without-any-errors",
-	}
-	for domainname, expectedDomainname := range validDomainnames {
-		if config, _, _ := mustParse(t, "--domainname="+domainname); config.Domainname != expectedDomainname {
-			t.Fatalf("Expected the config to have 'domainname' as %q, got %q", expectedDomainname, config.Domainname)
-		}
-	}
-	if config, _, _ := mustParse(t, "--hostname=some.prefix --domainname=domainname"); config.Hostname != "some.prefix" || config.Domainname != "domainname" {
-		t.Fatalf("Expected the config to have 'hostname' as 'some.prefix' and 'domainname' as 'domainname', got %q and %q", config.Hostname, config.Domainname)
-	}
-	if config, _, _ := mustParse(t, "--hostname=another-prefix --domainname=domainname.tld"); config.Hostname != "another-prefix" || config.Domainname != "domainname.tld" {
-		t.Fatalf("Expected the config to have 'hostname' as 'another-prefix' and 'domainname' as 'domainname.tld', got %q and %q", config.Hostname, config.Domainname)
+	for _, tc := range []struct {
+		input, hostname, domainname string
+	}{
+		{"--hostname=hostname", "hostname", ""},
+		{"--hostname=host-name", "host-name", ""},
+		{"--hostname=hostname123", "hostname123", ""},
+		{"--hostname=123hostname", "123hostname", ""},
+		{"--hostname=hostname-of-63-bytes-long-should-be-valid-and-without-any-error", "hostname-of-63-bytes-long-should-be-valid-and-without-any-error", ""},
+		{"--hostname=hostname.domainname", "hostname.domainname", ""},
+		{"--hostname=hostname.domainname.tld", "hostname.domainname.tld", ""},
+		{"--domainname=domainname", "", "domainname"},
+		{"--domainname=domain-name", "", "domain-name"},
+		{"--domainname=domainname123", "", "domainname123"},
+		{"--domainname=123domainname", "", "123domainname"},
+		{"--domainname=domainname-63-bytes-long-should-be-valid-and-without-any-errors", "", "domainname-63-bytes-long-should-be-valid-and-without-any-errors"},
+		{"--hostname=some.prefix --domainname=domainname", "some.prefix", "domainname"},
+		{"--hostname=another-prefix --domainname=domainname.tld", "another-prefix", "domainname.tld"},
+	} {
+		t.Run(tc.input, func(t *testing.T) {
+			config, _, _ := mustParse(t, tc.input)
+			require.Equal(t, tc.hostname, config.Hostname)
+			require.Equal(t, tc.domainname, config.Domainname)
+		})
 	}
 }
 
@@ -461,7 +364,7 @@ func TestParseWithExpose(t *testing.T) {
 		for expose, expectedError := range tests {
 			t.Run(expose, func(t *testing.T) {
 				_, _, _, err := parseRun([]string{fmt.Sprintf("--expose=%v", expose), "img", "cmd"})
-				assert.Error(t, err, expectedError)
+				require.EqualError(t, err, expectedError)
 			})
 		}
 	})
@@ -476,30 +379,38 @@ func TestParseWithExpose(t *testing.T) {
 		for expose, exposedPorts := range tests {
 			t.Run(expose, func(t *testing.T) {
 				config, _, _, err := parseRun([]string{fmt.Sprintf("--expose=%v", expose), "img", "cmd"})
-				assert.NilError(t, err)
+				require.NoError(t, err)
 				for _, port := range exposedPorts {
 					_, ok := config.ExposedPorts[port]
-					assert.Check(t, ok, "missing port %q in exposed ports: %#+v", port, config.ExposedPorts[port])
+					assert.True(t, ok, "missing port %q in exposed ports: %#+v", port, config.ExposedPorts[port])
 				}
 			})
 		}
 	})
 
 	t.Run("merge with published", func(t *testing.T) {
-		// Merge with actual published port
-		config, _, _, err := parseRun([]string{"--publish=80", "--expose=80-81/tcp", "img", "cmd"})
-		assert.NilError(t, err)
-		assert.Check(t, is.Len(config.ExposedPorts, 2))
+		config, hostConfig, _, err := parseRun([]string{"--publish=80", "--publish=127.0.0.1:8080:80", "--publish=[::1]:8081:80", "--expose=80-81/tcp"})
+		require.NoError(t, err)
+		assert.Equal(t, networktypes.PortMap{
+			networktypes.MustParsePort("80/tcp"): {
+				{},
+				{HostIP: netip.MustParseAddr("127.0.0.1"), HostPort: "8080"},
+				{HostIP: netip.MustParseAddr("::1"), HostPort: "8081"},
+			},
+		}, hostConfig.PortBindings)
+		assert.Len(t, config.ExposedPorts, 2)
 		ports := []networktypes.Port{networktypes.MustParsePort("80/tcp"), networktypes.MustParsePort("81/tcp")}
 		for _, port := range ports {
 			_, ok := config.ExposedPorts[port]
-			assert.Check(t, ok, "missing port %q in exposed ports: %#+v", port, config.ExposedPorts[port])
+			assert.True(t, ok, "missing port %q in exposed ports: %#+v", port, config.ExposedPorts[port])
 		}
 	})
 }
 
 func TestParseDevice(t *testing.T) {
-	skip.If(t, runtime.GOOS != "linux") // Windows and macOS validate server-side
+	if runtime.GOOS != "linux" {
+		t.Skip("Windows and macOS validate server-side")
+	}
 	testCases := []struct {
 		devices        []string
 		deviceMapping  *container.DeviceMapping
@@ -573,17 +484,17 @@ func TestParseDevice(t *testing.T) {
 
 			_, hostconfig, _, err := parseRun(args)
 
-			assert.NilError(t, err)
+			require.NoError(t, err)
 
 			if tc.deviceMapping != nil {
-				if assert.Check(t, is.Len(hostconfig.Devices, 1)) {
-					assert.Check(t, is.DeepEqual(*tc.deviceMapping, hostconfig.Devices[0]))
+				if assert.Len(t, hostconfig.Devices, 1) {
+					assert.Equal(t, *tc.deviceMapping, hostconfig.Devices[0])
 				}
 			} else {
-				assert.Check(t, is.Len(hostconfig.Devices, 0))
+				assert.Empty(t, hostconfig.Devices)
 			}
 
-			assert.Check(t, is.DeepEqual(tc.deviceRequests, hostconfig.DeviceRequests))
+			assert.Equal(t, tc.deviceRequests, hostconfig.DeviceRequests)
 		})
 	}
 }
@@ -652,11 +563,11 @@ func TestParseDeviceByServerOS(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			got, err := parseDevice(tc.device, tc.serverOS)
 			if tc.wantErr != "" {
-				assert.Error(t, err, tc.wantErr)
+				require.EqualError(t, err, tc.wantErr)
 				return
 			}
-			assert.NilError(t, err)
-			assert.Equal(t, got, tc.want)
+			require.NoError(t, err)
+			require.Equal(t, tc.want, got)
 		})
 	}
 }
@@ -835,13 +746,13 @@ func TestParseNetworkConfig(t *testing.T) {
 			_, hConfig, nwConfig, err := parseRun(tc.flags)
 
 			if tc.expectedErr != "" {
-				assert.Error(t, err, tc.expectedErr)
+				require.EqualError(t, err, tc.expectedErr)
 				return
 			}
 
-			assert.NilError(t, err)
-			assert.DeepEqual(t, hConfig.NetworkMode, tc.expectedHostCfg.NetworkMode)
-			assert.DeepEqual(t, nwConfig.EndpointsConfig, tc.expected, cmpopts.EquateComparable(netip.Addr{}))
+			require.NoError(t, err)
+			require.Equal(t, tc.expectedHostCfg.NetworkMode, hConfig.NetworkMode)
+			require.Equal(t, tc.expected, nwConfig.EndpointsConfig)
 		})
 	}
 }
@@ -850,24 +761,24 @@ func TestParseModes(t *testing.T) {
 	// pid ko
 	flags, copts := setupRunFlags()
 	args := []string{"--pid=container:", "img", "cmd"}
-	assert.NilError(t, flags.Parse(args))
+	require.NoError(t, flags.Parse(args))
 	_, err := parse(flags, copts, runtime.GOOS)
-	assert.ErrorContains(t, err, "--pid: invalid PID mode")
+	require.ErrorContains(t, err, "--pid: invalid PID mode")
 
 	// pid ok
 	_, hostconfig, _, err := parseRun([]string{"--pid=host", "img", "cmd"})
-	assert.NilError(t, err)
+	require.NoError(t, err)
 	if !hostconfig.PidMode.Valid() {
 		t.Fatalf("Expected a valid PidMode, got %v", hostconfig.PidMode)
 	}
 
 	// uts ko
 	_, _, _, err = parseRun([]string{"--uts=container:", "img", "cmd"}) //nolint:dogsled // verbatim copy from docker/cli tests
-	assert.ErrorContains(t, err, "--uts: invalid UTS mode")
+	require.ErrorContains(t, err, "--uts: invalid UTS mode")
 
 	// uts ok
 	_, hostconfig, _, err = parseRun([]string{"--uts=host", "img", "cmd"})
-	assert.NilError(t, err)
+	require.NoError(t, err)
 	if !hostconfig.UTSMode.Valid() {
 		t.Fatalf("Expected a valid UTSMode, got %v", hostconfig.UTSMode)
 	}
@@ -879,11 +790,11 @@ func TestRunFlagsParseShmSize(t *testing.T) {
 	args := []string{"--shm-size=a128m", "img", "cmd"}
 	expectedErr := `invalid argument "a128m" for "--shm-size" flag:`
 	err := flags.Parse(args)
-	assert.ErrorContains(t, err, expectedErr)
+	require.ErrorContains(t, err, expectedErr)
 
 	// shm-size ok
 	_, hostconfig, _, err := parseRun([]string{"--shm-size=128m", "img", "cmd"})
-	assert.NilError(t, err)
+	require.NoError(t, err)
 	if hostconfig.ShmSize != 134217728 {
 		t.Fatalf("Expected a valid ShmSize, got %d", hostconfig.ShmSize)
 	}
@@ -954,11 +865,11 @@ func TestParseRestartPolicy(t *testing.T) {
 		t.Run(tc.input, func(t *testing.T) {
 			_, hostConfig, _, err := parseRun([]string{"--restart=" + tc.input, "img", "cmd"})
 			if tc.expectedErr != "" {
-				assert.Check(t, is.Error(err, tc.expectedErr))
-				assert.Check(t, is.Nil(hostConfig))
+				assert.Nil(t, hostConfig)
+				assert.EqualError(t, err, tc.expectedErr)
 			} else {
-				assert.NilError(t, err)
-				assert.Check(t, is.DeepEqual(hostConfig.RestartPolicy, tc.expected))
+				require.NoError(t, err)
+				assert.Equal(t, tc.expected, hostConfig.RestartPolicy)
 			}
 		})
 	}
@@ -967,45 +878,33 @@ func TestParseRestartPolicy(t *testing.T) {
 func TestParseRestartPolicyAutoRemove(t *testing.T) {
 	_, _, _, err := parseRun([]string{"--rm", "--restart=always", "img", "cmd"}) //nolint:dogsled // verbatim copy from docker/cli tests
 	const expected = "conflicting options: cannot specify both --restart and --rm"
-	assert.Check(t, is.Error(err, expected))
+	assert.EqualError(t, err, expected)
 }
 
 func TestParseHealth(t *testing.T) {
-	checkOk := func(args ...string) *container.HealthConfig {
-		config, _, _, err := parseRun(args)
-		if err != nil {
-			t.Fatalf("%#v: %v", args, err)
-		}
-		return config.Healthcheck
-	}
-	checkError := func(expected string, args ...string) {
-		config, _, _, err := parseRun(args)
-		if err == nil {
-			t.Fatalf("Expected error, but got %#v", config)
-		}
-		if err.Error() != expected {
-			t.Fatalf("Expected %#v, got %#v", expected, err)
-		}
-	}
-	health := checkOk("--no-healthcheck", "img", "cmd")
-	if health == nil || len(health.Test) != 1 || health.Test[0] != "NONE" {
-		t.Fatalf("--no-healthcheck failed: %#v", health)
-	}
-
-	health = checkOk("--health-cmd=/check.sh -q", "img", "cmd")
-	if len(health.Test) != 2 || health.Test[0] != "CMD-SHELL" || health.Test[1] != "/check.sh -q" {
-		t.Fatalf("--health-cmd: got %#v", health.Test)
-	}
-	if health.Timeout != 0 {
-		t.Fatalf("--health-cmd: timeout = %s", health.Timeout)
-	}
-
-	checkError("--no-healthcheck conflicts with --health-* options",
-		"--no-healthcheck", "--health-cmd=/check.sh -q", "img", "cmd")
-
-	health = checkOk("--health-timeout=2s", "--health-retries=3", "--health-interval=4.5s", "--health-start-period=5s", "--health-start-interval=1s", "img", "cmd")
-	if health.Timeout != 2*time.Second || health.Retries != 3 || health.Interval != 4500*time.Millisecond || health.StartPeriod != 5*time.Second || health.StartInterval != 1*time.Second {
-		t.Fatalf("--health-*: got %#v", health)
+	for _, tc := range []struct {
+		args     []string
+		expected *container.HealthConfig
+		wantErr  string
+	}{
+		{[]string{"--no-healthcheck", "img", "cmd"}, &container.HealthConfig{Test: []string{"NONE"}}, ""},
+		{[]string{"--health-cmd=/check.sh -q", "img", "cmd"}, &container.HealthConfig{Test: []string{"CMD-SHELL", "/check.sh -q"}}, ""},
+		{[]string{"--no-healthcheck", "--health-cmd=/check.sh -q", "img", "cmd"}, nil, "--no-healthcheck conflicts with --health-* options"},
+		{
+			[]string{"--health-timeout=2s", "--health-retries=3", "--health-interval=4.5s", "--health-start-period=5s", "--health-start-interval=1s", "img", "cmd"},
+			&container.HealthConfig{Timeout: 2 * time.Second, Retries: 3, Interval: 4500 * time.Millisecond, StartPeriod: 5 * time.Second, StartInterval: time.Second},
+			"",
+		},
+	} {
+		t.Run(strings.Join(tc.args, " "), func(t *testing.T) {
+			config, _, _, err := parseRun(tc.args)
+			if tc.wantErr != "" {
+				require.EqualError(t, err, tc.wantErr)
+			} else {
+				require.NoError(t, err)
+				require.Equal(t, tc.expected, config.Healthcheck)
+			}
+		})
 	}
 }
 
@@ -1024,93 +923,66 @@ func TestParseLoggingOpts(t *testing.T) {
 	}
 }
 
-func TestParseEnvfileVariables(t *testing.T) { //nolint:dupl // verbatim copy from docker/cli tests
-	expErr := "--env-file: open nonexistent: no such file or directory"
-	if runtime.GOOS == "windows" {
-		expErr = "--env-file: open nonexistent: The system cannot find the file specified."
-	}
-	// env ko
-	if _, _, _, err := parseRun([]string{"--env-file=nonexistent", "img", "cmd"}); err == nil || err.Error() != expErr {
-		t.Fatalf("Expected an error with message '%s', got %v", expErr, err)
-	}
-	// env ok
-	config, _, _, err := parseRun([]string{"--env-file=testdata/valid.env", "img", "cmd"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(config.Env) != 1 || config.Env[0] != "ENV1=value1" {
-		t.Fatalf("Expected a config with [ENV1=value1], got %v", config.Env)
-	}
-	config, _, _, err = parseRun([]string{"--env-file=testdata/valid.env", "--env=ENV2=value2", "img", "cmd"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(config.Env) != 2 || config.Env[0] != "ENV1=value1" || config.Env[1] != "ENV2=value2" {
-		t.Fatalf("Expected a config with [ENV1=value1 ENV2=value2], got %v", config.Env)
+func TestParseFileVariables(t *testing.T) {
+	for _, tc := range []struct {
+		flag, file, key string
+	}{
+		{"env", "valid.env", "ENV"},
+		{"label", "valid.label", "LABEL"},
+	} {
+		t.Run(tc.flag, func(t *testing.T) {
+			expectedError := "no such file or directory"
+			if runtime.GOOS == "windows" {
+				expectedError = "The system cannot find the file specified."
+			}
+			_, _, _, err := parseRun([]string{"--" + tc.flag + "-file=nonexistent"})
+			require.EqualError(t, err, "--"+tc.flag+"-file: open nonexistent: "+expectedError)
+			for _, extra := range []bool{false, true} {
+				args := []string{"--" + tc.flag + "-file=testdata/" + tc.file}
+				expected := []string{tc.key + "1=value1"}
+				if extra {
+					args = append(args, "--"+tc.flag+"="+tc.key+"2=value2")
+					expected = append(expected, tc.key+"2=value2")
+				}
+				config, _, _, err := parseRun(args)
+				require.NoError(t, err)
+				if tc.flag == "env" {
+					assert.Equal(t, expected, config.Env)
+				} else {
+					assert.Len(t, config.Labels, len(expected))
+					for _, label := range expected {
+						key, value, _ := strings.Cut(label, "=")
+						assert.Equal(t, value, config.Labels[key])
+					}
+				}
+			}
+		})
 	}
 }
 
 func TestParseEnvfileVariablesWithBOMUnicode(t *testing.T) {
-	// UTF8 with BOM
-	config, _, _, err := parseRun([]string{"--env-file=testdata/utf8.env", "img", "cmd"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	env := []string{"FOO=BAR", "HELLO=" + string([]byte{0xe6, 0x82, 0xa8, 0xe5, 0xa5, 0xbd}), "BAR=FOO"}
-	if len(config.Env) != len(env) {
-		t.Fatalf("Expected a config with %d env variables, got %v: %v", len(env), len(config.Env), config.Env)
-	}
-	for i, v := range env {
-		if config.Env[i] != v {
-			t.Fatalf("Expected a config with [%s], got %v", v, []byte(config.Env[i]))
-		}
-	}
+	config, _, _, err := parseRun([]string{"--env-file=testdata/utf8.env"})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"FOO=BAR", "HELLO=您好", "BAR=FOO"}, config.Env)
 
-	// UTF16 with BOM
-	e := "invalid utf8 bytes at line"
-	if _, _, _, err := parseRun([]string{"--env-file=testdata/utf16.env", "img", "cmd"}); err == nil || !strings.Contains(err.Error(), e) {
-		t.Fatalf("Expected an error with message '%s', got %v", e, err)
-	}
-	// UTF16BE with BOM
-	if _, _, _, err := parseRun([]string{"--env-file=testdata/utf16be.env", "img", "cmd"}); err == nil || !strings.Contains(err.Error(), e) {
-		t.Fatalf("Expected an error with message '%s', got %v", e, err)
-	}
-}
-
-func TestParseLabelfileVariables(t *testing.T) { //nolint:dupl // verbatim copy from docker/cli tests
-	expErr := "--label-file: open nonexistent: no such file or directory"
-	if runtime.GOOS == "windows" {
-		expErr = "--label-file: open nonexistent: The system cannot find the file specified."
-	}
-	// label ko
-	if _, _, _, err := parseRun([]string{"--label-file=nonexistent", "img", "cmd"}); err == nil || err.Error() != expErr {
-		t.Fatalf("Expected an error with message '%s', got %v", expErr, err)
-	}
-	// label ok
-	config, _, _, err := parseRun([]string{"--label-file=testdata/valid.label", "img", "cmd"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(config.Labels) != 1 || config.Labels["LABEL1"] != "value1" {
-		t.Fatalf("Expected a config with [LABEL1:value1], got %v", config.Labels)
-	}
-	config, _, _, err = parseRun([]string{"--label-file=testdata/valid.label", "--label=LABEL2=value2", "img", "cmd"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(config.Labels) != 2 || config.Labels["LABEL1"] != "value1" || config.Labels["LABEL2"] != "value2" {
-		t.Fatalf("Expected a config with [LABEL1:value1 LABEL2:value2], got %v", config.Labels)
+	for _, file := range []string{"utf16.env", "utf16be.env"} {
+		t.Run(file, func(t *testing.T) {
+			_, _, _, err := parseRun([]string{"--env-file=testdata/" + file})
+			require.ErrorContains(t, err, "invalid utf8 bytes at line")
+		})
 	}
 }
 
 func TestParseEntryPoint(t *testing.T) {
 	config, _, _, err := parseRun([]string{"--entrypoint=anything", "cmd", "img"})
-	assert.NilError(t, err)
-	assert.Check(t, is.DeepEqual(config.Entrypoint, []string{"anything"}))
+	require.NoError(t, err)
+	assert.Equal(t, []string{"anything"}, config.Entrypoint)
 }
 
 func TestValidateDevice(t *testing.T) {
-	skip.If(t, runtime.GOOS != "linux") // Windows and macOS validate server-side
+	if runtime.GOOS != "linux" {
+		t.Skip("Windows and macOS validate server-side")
+	}
 	valid := []string{
 		"/home",
 		"/home:/home",
@@ -1209,22 +1081,22 @@ func TestValidateDeviceByServerOS(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			got, err := validateDevice(tc.value, tc.serverOS)
 			if tc.wantError != "" {
-				assert.Error(t, err, tc.wantError)
+				require.EqualError(t, err, tc.wantError)
 				return
 			}
-			assert.NilError(t, err)
-			assert.Equal(t, got, tc.want)
+			require.NoError(t, err)
+			require.Equal(t, tc.want, got)
 		})
 	}
 }
 
 func TestDeviceCgroupRulesAndInvalidParameter(t *testing.T) {
 	got, err := validateDeviceCgroupRule("c 1:3 rwm")
-	assert.NilError(t, err)
-	assert.Equal(t, got, "c 1:3 rwm")
+	require.NoError(t, err)
+	require.Equal(t, "c 1:3 rwm", got)
 
 	_, err = validateDeviceCgroupRule("invalid")
-	assert.Error(t, err, "invalid device cgroup format 'invalid'")
+	require.EqualError(t, err, "invalid device cgroup format 'invalid'")
 
 	if invalidParameter(nil) != nil {
 		t.Fatal("invalidParameter(nil) should be nil")
@@ -1232,9 +1104,9 @@ func TestDeviceCgroupRulesAndInvalidParameter(t *testing.T) {
 	cause := errors.New("bad input")
 	err = invalidParameter(cause)
 	var invalid interface{ InvalidParameter() }
-	assert.Assert(t, errors.As(err, &invalid))
-	assert.Assert(t, errors.Is(err, cause))
-	assert.Equal(t, invalidParameter(err), err) // already invalid, so not wrapped twice
+	require.ErrorAs(t, err, &invalid)
+	require.ErrorIs(t, err, cause)
+	require.Condition(t, func() bool { return invalidParameter(err) == err })
 }
 
 func TestParseSystemPaths(t *testing.T) {
@@ -1285,9 +1157,9 @@ func TestParseSystemPaths(t *testing.T) {
 
 	for _, tc := range tests {
 		securityOpts, maskedPaths, readonlyPaths := parseSystemPaths(tc.in)
-		assert.DeepEqual(t, securityOpts, tc.out)
-		assert.DeepEqual(t, maskedPaths, tc.masked)
-		assert.DeepEqual(t, readonlyPaths, tc.readonly)
+		require.Equal(t, tc.out, securityOpts)
+		require.Equal(t, tc.masked, maskedPaths)
+		require.Equal(t, tc.readonly, readonlyPaths)
 	}
 }
 
@@ -1309,9 +1181,9 @@ func TestConvertToStandardNotation(t *testing.T) {
 	for key, ports := range valid {
 		convertedPorts, err := convertToStandardNotation(ports)
 		if err != nil {
-			assert.NilError(t, err)
+			require.NoError(t, err)
 		}
-		assert.DeepEqual(t, strings.Split(key, " "), convertedPorts)
+		require.Equal(t, strings.Split(key, " "), convertedPorts)
 	}
 
 	for _, ports := range invalid {

act/container/docker_create_flags.go

@@ -1,7 +1,7 @@
 // Copyright 2026 The Gitea Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 
@@ -10,7 +10,9 @@ import (
 	"fmt"
 	"io"
 	"slices"
+	"strings"
 
+	"github.com/docker/cli/opts"
 	"github.com/kballard/go-shellquote"
 	"github.com/spf13/pflag"
 )
@@ -51,15 +53,16 @@ func parseContainerOptions(options string) (*pflag.FlagSet, *containerOptions, *
 	flags := pflag.NewFlagSet("container_flags", pflag.ContinueOnError)
 	flags.SetOutput(io.Discard)
 	copts := addFlags(flags)
+	copts.env = opts.NewListOpts(validateEnv) // addFlags registered this field's address, so the swap takes effect
 	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)
+		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, fmt.Errorf("cannot parse container options: '%s': '%w'", options, err)
 	}
 
 	return flags, copts, cf, nil
@@ -73,6 +76,30 @@ func createFlagsFromOptions(options string) *createFlags {
 	return cf
 }
 
+// validateEnv is opts.ValidateEnv without its lookup of a bare name in the runner's environment.
+func validateEnv(val string) (string, error) {
+	if name, _, _ := strings.Cut(val, "="); name == "" {
+		return "", errors.New("invalid environment variable: " + val)
+	}
+	return val, nil
+}
+
+// rejectHostReadingOptions refuses the flags naming files that are read here, on the
+// runner, rather than in the container.
+func rejectHostReadingOptions(options string) error {
+	flags, _, _, err := parseContainerOptions(options)
+	if err != nil {
+		return err
+	}
+
+	for _, name := range []string{"env-file", "label-file"} {
+		if flags.Changed(name) {
+			return fmt.Errorf("container option --%s reads files from the runner and is not allowed in a workflow", name)
+		}
+	}
+	return nil
+}
+
 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)

act/container/docker_create_flags_test.go

@@ -50,13 +50,13 @@ func TestCreateFlagsValidate(t *testing.T) {
 }
 
 func TestNewContainerAppliesCreateFlags(t *testing.T) {
-	input := &NewContainerInput{Platform: "linux/amd64", Options: "--platform linux/arm64 --pull never"}
+	input := &NewContainerInput{Platform: "linux/amd64", RunnerOptions: "--pull never", WorkflowOptions: "--platform linux/arm64"}
 	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"}
+	kept := &NewContainerInput{Platform: "linux/amd64", RunnerOptions: "--privileged"}
 	NewContainer(kept)
 	assert.Equal(t, "linux/amd64", kept.Platform)
 }

act/container/docker_images.go

@@ -2,16 +2,16 @@
 // Copyright 2020 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 
 import (
 	"context"
-	"fmt"
 
 	cerrdefs "github.com/containerd/errdefs"
 	"github.com/moby/moby/client"
+	specs "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
 // ImageExistsLocally returns a boolean indicating if an image with the
@@ -30,11 +30,23 @@ func ImageExistsLocally(ctx context.Context, imageName, platform string) (bool,
 		return false, err
 	}
 
-	if platform == "" || platform == "any" || fmt.Sprintf("%s/%s", inspectImage.Os, inspectImage.Architecture) == platform {
+	if platform == "" || platform == "any" {
 		return true, nil
 	}
 
-	return false, nil
+	requested, err := parsePlatform(platform)
+	if err != nil {
+		return false, err
+	}
+	return platformMatches(requested, &specs.Platform{OS: inspectImage.Os, Architecture: inspectImage.Architecture, Variant: inspectImage.Variant}), nil
+}
+
+func platformMatches(requested, image *specs.Platform) bool {
+	variant := image.Variant
+	if variant == "" {
+		variant = map[string]string{"amd64": "v1", "arm": "v7", "arm64": "v8"}[image.Architecture]
+	}
+	return image.OS == requested.OS && image.Architecture == requested.Architecture && (requested.Variant == "" || requested.Variant == variant)
 }
 
 // RemoveImage removes image from local store, the function is used to run different
@@ -46,19 +58,14 @@ func RemoveImage(ctx context.Context, imageName string, force, pruneChildren boo
 	}
 	defer cli.Close()
 
-	inspectImage, err := cli.ImageInspect(ctx, imageName)
-	if cerrdefs.IsNotFound(err) {
+	if _, err = cli.ImageRemove(ctx, imageName, client.ImageRemoveOptions{
+		Force:         force,
+		PruneChildren: pruneChildren,
+	}); cerrdefs.IsNotFound(err) {
 		return false, nil
 	} else if err != nil {
 		return false, err
 	}
 
-	if _, err = cli.ImageRemove(ctx, inspectImage.ID, client.ImageRemoveOptions{
-		Force:         force,
-		PruneChildren: pruneChildren,
-	}); err != nil {
-		return false, err
-	}
-
 	return true, nil
 }

act/container/docker_images_test.go

@@ -5,65 +5,74 @@
 package container
 
 import (
+	"bytes"
 	"context"
 	"fmt"
-	"os"
-	"os/exec"
 	"strings"
 	"testing"
+	"time"
 
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/common/logging"
+
+	mobyclient "github.com/moby/moby/client"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 func init() {
-	log.SetLevel(log.DebugLevel)
+	logging.SetLevel(logging.LevelDebug)
 }
 
-// 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 {
+func loadScratchImage(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() })
+	tag := fmt.Sprintf("act-test-exists-%s-%d:latest", strings.TrimPrefix(platform, "linux/"), time.Now().UnixNano())
+	var archive bytes.Buffer
+	require.NoError(t, writeFilesTar(t.Context(), &archive, 0, 0,
+		&FileEntry{Name: "config.json", Mode: 0o600, Body: fmt.Sprintf(`{"architecture":%q,"os":"linux","rootfs":{"type":"layers","diff_ids":[]}}`, strings.TrimPrefix(platform, "linux/"))},
+		&FileEntry{Name: "manifest.json", Mode: 0o600, Body: fmt.Sprintf(`[{"Config":"config.json","RepoTags":[%q],"Layers":[]}]`, tag)},
+	))
+	cli, err := GetDockerClient(t.Context())
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = cli.Close() })
+	response, err := cli.ImageLoad(t.Context(), &archive)
+	require.NoError(t, err)
+	defer response.Close()
+	require.NoError(t, logDockerResponse(common.Logger(t.Context()), response, false))
+	t.Cleanup(func() {
+		_, _ = cli.ImageRemove(context.WithoutCancel(t.Context()), tag, mobyclient.ImageRemoveOptions{Force: true})
+	})
 	return tag
 }
 
 func TestImageExistsLocally(t *testing.T) {
+	t.Parallel()
 	requireDocker(t)
-	ctx := context.Background()
+	ctx := t.Context()
 
-	// a non-existent image is reported absent
 	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
 	assert.False(t, missing)
 
-	// Build tiny images for two architectures locally so per-platform existence can be checked
-	// offline (formerly pulled node:24-bookworm-slim for amd64 and arm64 over the network).
-	amd64Ref := buildScratchImage(t, "linux/amd64")
-	arm64Ref := buildScratchImage(t, "linux/arm64")
+	amd64Ref := loadScratchImage(t, "linux/amd64")
+	arm64Ref := loadScratchImage(t, "linux/arm64")
 
 	amd64Exists, err := ImageExistsLocally(ctx, amd64Ref, "linux/amd64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 	assert.True(t, amd64Exists)
 
-	// a non-host architecture image is detected for its own architecture
 	arm64Exists, err := ImageExistsLocally(ctx, arm64Ref, "linux/arm64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 	assert.True(t, arm64Exists)
 
-	// 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.False(t, wrongPlatform)
+
+	removed, err := RemoveImage(ctx, amd64Ref, false, false)
+	require.NoError(t, err)
+	assert.True(t, removed)
+	removed, err = RemoveImage(ctx, amd64Ref, false, false)
+	require.NoError(t, err)
+	assert.False(t, removed)
 }

act/container/docker_logger.go

@@ -2,17 +2,17 @@
 // Copyright 2020 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 
 import (
 	"bufio"
-	"encoding/json"
+	"encoding/json/v2"
 	"errors"
 	"io"
 
-	"github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
 )
 
 type dockerMessage struct {
@@ -20,31 +20,23 @@ type dockerMessage struct {
 	Stream      string `json:"stream"`
 	Error       string `json:"error"`
 	ErrorDetail struct {
-		Message string
-	}
+		Message string `json:"message"`
+	} `json:"errorDetail"`
 	Status   string `json:"status"`
 	Progress string `json:"progress"`
 }
 
-func logDockerResponse(logger logrus.FieldLogger, dockerResponse io.ReadCloser, isError bool) error {
+func logDockerResponse(logger *logging.Logger, dockerResponse io.ReadCloser, isError bool) error {
 	if dockerResponse == nil {
 		return nil
 	}
 	defer dockerResponse.Close()
 
 	scanner := bufio.NewScanner(dockerResponse)
-	msg := dockerMessage{}
-
+	scanner.Buffer(nil, 64*1024*1024) // a build echoes long instructions in one record
 	for scanner.Scan() {
 		line := scanner.Bytes()
-
-		msg.ID = ""
-		msg.Stream = ""
-		msg.Error = ""
-		msg.ErrorDetail.Message = ""
-		msg.Status = ""
-		msg.Progress = ""
-
+		var msg dockerMessage
 		if err := json.Unmarshal(line, &msg); err != nil {
 			writeLog(logger, false, "Unable to unmarshal line [%s] ==> %v", string(line), err)
 			continue
@@ -60,23 +52,24 @@ func logDockerResponse(logger logrus.FieldLogger, dockerResponse io.ReadCloser,
 			return errors.New(msg.ErrorDetail.Message)
 		}
 
-		if msg.Status != "" {
+		switch {
+		case msg.Status != "":
 			if msg.Progress != "" {
 				writeLog(logger, isError, "%s :: %s :: %s\n", msg.Status, msg.ID, msg.Progress)
 			} else {
 				writeLog(logger, isError, "%s :: %s\n", msg.Status, msg.ID)
 			}
-		} else if msg.Stream != "" {
+		case msg.Stream != "":
 			writeLog(logger, isError, "%s", msg.Stream)
-		} else {
+		default:
 			writeLog(logger, false, "Unable to handle line: %s", string(line))
 		}
 	}
 
-	return nil
+	return scanner.Err()
 }
 
-func writeLog(logger logrus.FieldLogger, isError bool, format string, args ...any) {
+func writeLog(logger *logging.Logger, isError bool, format string, args ...any) {
 	if isError {
 		logger.Errorf(format, args...)
 	} else {

act/container/docker_network.go

@@ -2,7 +2,7 @@
 // Copyright 2023 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 
@@ -10,21 +10,20 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"net/netip"
 	"strings"
 	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
+	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/types/network"
 	"github.com/moby/moby/client"
 )
 
 const (
 	networkCreateAttempts   = 3
 	networkCreateRetryDelay = time.Second
-
-	// marks the networks a runner creates for its jobs, so it can tell its own leftovers from
-	// those of another runner sharing the daemon
-	runnerUUIDLabel = "com.gitea.runner.uuid"
 )
 
 // RemoveOrphanNetworks removes the networks this runner created for jobs whose teardown did
@@ -32,17 +31,17 @@ const (
 // had an endpoint on it at the time. Each one holds a subnet of the daemon's address pool
 // until it is removed. Networks created after createdBefore are left alone, so a job starting
 // while this runs cannot lose the network it has created but not yet attached a container to.
-func RemoveOrphanNetworks(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
+func RemoveOrphanNetworks(ctx context.Context, runnerUUID, detach string, createdBefore time.Time) error {
 	cli, err := GetDockerClient(ctx)
 	if err != nil {
 		return fmt.Errorf("failed to connect to the docker daemon: %w", err)
 	}
 	defer cli.Close()
 
-	return removeOrphanNetworks(ctx, cli, runnerUUID, createdBefore)
+	return removeOrphanNetworks(ctx, cli, runnerUUID, detach, createdBefore)
 }
 
-func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID string, createdBefore time.Time) error {
+func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID, detach string, createdBefore time.Time) error {
 	networks, err := cli.NetworkList(ctx, client.NetworkListOptions{
 		Filters: make(client.Filters).Add("label", runnerUUIDLabel+"="+runnerUUID),
 	})
@@ -51,18 +50,32 @@ func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID
 	}
 
 	var errs []error
+networks:
 	for _, n := range networks.Items {
 		result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
-		if err != nil {
+		if cerrdefs.IsNotFound(err) {
+			continue
+		} else 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) {
+		if len(result.Network.Containers) > 1 || result.Network.Created.After(createdBefore) {
 			continue
 		}
-		if _, err := cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); err != nil {
+		for containerID := range result.Network.Containers {
+			if detach == "" || !strings.HasPrefix(containerID, detach) {
+				continue networks
+			}
+			if err := disconnectNetwork(ctx, cli, n.ID, containerID); err != nil {
+				errs = append(errs, fmt.Errorf("failed to disconnect container from network %s: %w", n.Name, err))
+				continue networks
+			}
+		}
+		if _, err := cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); cerrdefs.IsNotFound(err) {
+			continue
+		} else if err != nil {
 			errs = append(errs, fmt.Errorf("failed to remove network %s: %w", n.Name, err))
 			continue
 		}
@@ -72,51 +85,60 @@ func removeOrphanNetworks(ctx context.Context, cli client.APIClient, runnerUUID
 }
 
 func NewDockerNetworkCreateExecutor(name string, opts NewDockerNetworkCreateExecutorInput) common.Executor {
-	return func(ctx context.Context) error {
+	return common.Executor(func(ctx context.Context) error {
 		cli, err := GetDockerClient(ctx)
 		if err != nil {
 			return err
 		}
 		defer cli.Close()
+		return createDockerNetwork(ctx, cli, name, opts)
+	}).IfNot(common.Dryrun)
+}
 
-		// Only create the network if it doesn't exist
-		networks, err := cli.NetworkList(ctx, client.NetworkListOptions{})
-		if err != nil {
+func createDockerNetwork(ctx context.Context, cli client.APIClient, name string, opts NewDockerNetworkCreateExecutorInput) error {
+	// Only create the network if it doesn't exist
+	networks, err := cli.NetworkList(ctx, client.NetworkListOptions{})
+	if err != nil {
+		return err
+	}
+	var options map[string]string
+	// For Gitea, reduce log noise
+	// common.Logger(ctx).Debugf("%v", networks)
+	for _, n := range networks.Items {
+		if n.Name == name {
+			common.Logger(ctx).Debugf("Network %v exists", name)
+			return nil
+		}
+		// the daemon's mtu only reaches its default bridge, Docker's default is left out to keep default-network-opts
+		if mtu := n.Options["com.docker.network.driver.mtu"]; n.Name == network.NetworkBridge && mtu != "" && mtu != "1500" {
+			options = map[string]string{"com.docker.network.driver.mtu": mtu}
+		}
+	}
+
+	for i := range networkCreateAttempts {
+		if i > 0 {
+			common.Logger(ctx).Infof("Waiting for a free docker address pool to create network %s", name)
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-time.After(time.Duration(i) * networkCreateRetryDelay):
+			}
+		}
+		if _, err = cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{
+			Driver:     "bridge",
+			Scope:      "local",
+			EnableIPv4: opts.EnableIPv4,
+			EnableIPv6: opts.EnableIPv6,
+			Options:    options,
+			Labels:     runnerLabels(opts.RunnerUUID),
+		}); err == nil {
+			return nil
+		}
+		if !isAddressPoolExhausted(err) {
 			return err
 		}
-		// For Gitea, reduce log noise
-		// common.Logger(ctx).Debugf("%v", networks)
-		for _, n := range networks.Items {
-			if n.Name == name {
-				common.Logger(ctx).Debugf("Network %v exists", name)
-				return nil
-			}
-		}
-
-		for i := range networkCreateAttempts {
-			if i > 0 {
-				common.Logger(ctx).Infof("Waiting for a free docker address pool to create network %s", name)
-				select {
-				case <-ctx.Done():
-					return ctx.Err()
-				case <-time.After(time.Duration(i) * networkCreateRetryDelay):
-				}
-			}
-			if _, err = cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{
-				Driver:     "bridge",
-				Scope:      "local",
-				EnableIPv4: opts.EnableIPv4,
-				EnableIPv6: opts.EnableIPv6,
-				Labels:     runnerLabels(opts.RunnerUUID),
-			}); err == nil {
-				return nil
-			}
-			if !isAddressPoolExhausted(err) {
-				return err
-			}
-		}
-		return fmt.Errorf("docker has no address pool left for this job's network, lower runner.capacity or widen default-address-pools in the docker daemon config: %w", err)
 	}
+	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 {
@@ -134,41 +156,130 @@ func isAddressPoolExhausted(err error) bool {
 		strings.Contains(msg, "could not find an available, non-overlapping IPv4 address pool among the defaults") // docker 24 and older
 }
 
-func NewDockerNetworkRemoveExecutor(name string) common.Executor {
-	return func(ctx context.Context) error {
+func NewDockerNetworkConnectExecutor(networkName, container string) common.Executor {
+	return common.Executor(func(ctx context.Context) error {
 		cli, err := GetDockerClient(ctx)
 		if err != nil {
 			return err
 		}
 		defer cli.Close()
+		if err := connectNetwork(ctx, cli, networkName, container); err != nil {
+			common.Logger(ctx).Warnf("cannot connect %s to network %s, so jobs on it cannot reach the cache: %v", container, networkName, err)
+		}
+		return nil
+	}).IfNot(common.Dryrun)
+}
 
-		// Make sure that all network of the specified name are removed
-		// cli.NetworkRemove refuses to remove a network if there are duplicates
-		networks, err := cli.NetworkList(ctx, client.NetworkListOptions{})
+func connectNetwork(ctx context.Context, cli client.APIClient, networkName, container string) error {
+	_, err := cli.NetworkConnect(ctx, networkName, client.NetworkConnectOptions{
+		Container:      container,
+		EndpointConfig: &network.EndpointSettings{Aliases: []string{container}},
+	})
+	if err != nil && (strings.Contains(err.Error(), "already exists in network") || strings.Contains(err.Error(), "already connected")) {
+		return nil
+	}
+	return err
+}
+
+func NewDockerNetworkDisconnectExecutor(networkName, container string) common.Executor {
+	return common.Executor(func(ctx context.Context) error {
+		cli, err := GetDockerClient(ctx)
 		if err != nil {
 			return err
 		}
-		// 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{})
-				if err != nil {
-					return err
-				}
+		defer cli.Close()
+		return disconnectNetwork(ctx, cli, networkName, container)
+	}).IfNot(common.Dryrun)
+}
 
-				// it holds a subnet out of the daemon's pool until something reclaims it
-				if len(result.Network.Containers) != 0 {
-					common.Logger(ctx).Warnf("Refusing to remove network %s because it still has active endpoints, the idle cleanup reclaims it once they are gone", name)
-					continue
-				}
-				if _, err = cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); err != nil {
-					errs = append(errs, fmt.Errorf("failed to remove network %s: %w", name, err))
-				}
+func disconnectNetwork(ctx context.Context, cli client.APIClient, networkName, container string) error {
+	_, err := cli.NetworkDisconnect(ctx, networkName, client.NetworkDisconnectOptions{Container: container, Force: true})
+	if cerrdefs.IsNotFound(err) || (err != nil && strings.Contains(err.Error(), "is not connected")) {
+		return nil
+	}
+	return err
+}
+
+func NewDockerNetworkRemoveExecutor(name string) common.Executor {
+	return common.Executor(func(ctx context.Context) error {
+		cli, err := GetDockerClient(ctx)
+		if err != nil {
+			return err
+		}
+		defer cli.Close()
+		return removeNetwork(ctx, cli, name)
+	}).IfNot(common.Dryrun)
+}
+
+func removeNetwork(ctx context.Context, cli client.APIClient, name string) error {
+	networks, err := cli.NetworkList(ctx, client.NetworkListOptions{}) // NetworkRemove by name refuses duplicates, so remove each by ID
+	if err != nil {
+		return err
+	}
+	var errs []error
+	for _, n := range networks.Items {
+		if n.Name != name {
+			continue
+		}
+		result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
+		if cerrdefs.IsNotFound(err) {
+			continue
+		} else if err != nil {
+			return err
+		}
+		if len(result.Network.Containers) != 0 {
+			common.Logger(ctx).Warnf("Refusing to remove network %s because it still has active endpoints, the orphan cleanup reclaims it once they are gone", name)
+			continue
+		}
+		if _, err = cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); err != nil && !cerrdefs.IsNotFound(err) {
+			errs = append(errs, fmt.Errorf("failed to remove network %s: %w", name, err))
+		}
+	}
+	return errors.Join(errs...)
+}
+
+// IsolatedCacheContainer returns the container holding addr, when jobs on jobNetwork cannot reach it there.
+func IsolatedCacheContainer(ctx context.Context, addr netip.Addr, jobNetwork string) (string, error) {
+	cli, err := GetDockerClient(ctx)
+	if err != nil {
+		return "", err
+	}
+	defer cli.Close()
+	return isolatedCacheContainer(ctx, cli, addr, jobNetwork)
+}
+
+func isolatedCacheContainer(ctx context.Context, cli client.APIClient, addr netip.Addr, jobNetwork string) (string, error) {
+	if jobNetwork == "host" || strings.HasPrefix(jobNetwork, "container:") {
+		return "", nil
+	}
+	containers, err := cli.ContainerList(ctx, client.ContainerListOptions{})
+	if err != nil {
+		return "", err
+	}
+	var holderID, holderContainer string
+	for _, summary := range containers.Items {
+		if summary.NetworkSettings == nil {
+			continue
+		}
+		for _, endpoint := range summary.NetworkSettings.Networks {
+			if endpoint != nil && (endpoint.IPAddress == addr || endpoint.GlobalIPv6Address == addr) {
+				holderID = endpoint.NetworkID
+				holderContainer = summary.ID[:12]
 			}
 		}
-
-		return errors.Join(errs...)
 	}
+	if holderID == "" {
+		return "", nil
+	}
+	holder, err := cli.NetworkInspect(ctx, holderID, client.NetworkInspectOptions{})
+	if err != nil || holder.Network.Driver != "bridge" {
+		return "", err
+	}
+	if jobNetwork != "" {
+		job, err := cli.NetworkInspect(ctx, jobNetwork, client.NetworkInspectOptions{})
+		if err != nil || job.Network.ID == holderID {
+			return "", err
+		}
+	}
+	return holderContainer, nil
 }

act/container/docker_network_test.go

@@ -6,45 +6,166 @@ package container
 import (
 	"context"
 	"errors"
+	"net/netip"
 	"testing"
 	"time"
 
 	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/types/container"
 	"github.com/moby/moby/api/types/network"
 	mobyclient "github.com/moby/moby/client"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
+func TestIsolatedCacheContainer(t *testing.T) {
+	ctx := t.Context()
+	cache, lan := netip.MustParseAddr("172.18.0.3"), netip.MustParseAddr("192.168.1.20")
+	client := &mockDockerClient{}
+	client.On("ContainerList", ctx, mobyclient.ContainerListOptions{}).Return(mobyclient.ContainerListResult{Items: []container.Summary{{}, {
+		ID: "0123456789abcdef",
+		NetworkSettings: &container.NetworkSettingsSummary{Networks: map[string]*network.EndpointSettings{
+			"compose": {NetworkID: "c0ffee", IPAddress: cache},
+			"lan":     {NetworkID: "beef", IPAddress: lan},
+		}},
+	}}}, nil)
+	for ref, inspected := range map[string]network.Network{
+		"c0ffee": {ID: "c0ffee", Name: "compose", Driver: "bridge"},
+		"beef":   {ID: "beef", Name: "lan", Driver: "macvlan"},
+		"c0f":    {ID: "c0ffee"},
+		"jobs":   {ID: "f00d"},
+	} {
+		client.On("NetworkInspect", ctx, ref, mobyclient.NetworkInspectOptions{}).
+			Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Network: inspected}}, nil)
+	}
+	check := func(addr netip.Addr, jobNetwork, want string) {
+		got, err := isolatedCacheContainer(ctx, client, addr, jobNetwork)
+		require.NoError(t, err)
+		assert.Equal(t, want, got, jobNetwork)
+	}
+	check(cache, "", "0123456789ab")
+	check(cache, "jobs", "0123456789ab")
+	check(cache, "c0f", "")
+	check(cache, "host", "")
+	check(lan, "", "")
+	check(netip.MustParseAddr("10.0.0.5"), "", "")
+}
+
 func TestIsAddressPoolExhausted(t *testing.T) {
 	assert.True(t, isAddressPoolExhausted(cerrdefs.ErrInvalidArgument.WithMessage("Error response from daemon: all predefined address pools have been fully subnetted")))
 	assert.True(t, isAddressPoolExhausted(errors.New("could not find an available, non-overlapping IPv4 address pool among the defaults to assign to the network")))
 	assert.False(t, isAddressPoolExhausted(cerrdefs.ErrInvalidArgument.WithMessage("invalid subnet 10.0.0.0/8: it overlaps with an existing network")))
 }
 
-// Of this runner's networks, only the ones nothing is attached to and old enough to predate
-// any job now starting are the runner's to reclaim. An unexpected NetworkRemove fails the
-// test on its own, since testify has no expectation to match it against.
-func TestRemoveOrphanNetworks(t *testing.T) {
-	ctx := context.Background()
+func TestCreateDockerNetworkInheritsDaemonMTU(t *testing.T) {
+	ctx := t.Context()
+	for _, tc := range []struct {
+		bridgeOptions, want map[string]string
+	}{
+		{
+			map[string]string{"com.docker.network.bridge.host_binding_ipv4": "127.0.0.1", "com.docker.network.driver.mtu": "1450"},
+			map[string]string{"com.docker.network.driver.mtu": "1450"},
+		},
+		{map[string]string{"com.docker.network.driver.mtu": "1500"}, nil},
+	} {
+		client := &mockDockerClient{}
+		client.On("NetworkList", ctx, mobyclient.NetworkListOptions{}).
+			Return(mobyclient.NetworkListResult{Items: []network.Summary{{Name: network.NetworkBridge, Options: tc.bridgeOptions}}}, nil)
+		client.On("NetworkCreate", ctx, "job-network", mobyclient.NetworkCreateOptions{Driver: "bridge", Scope: "local", Options: tc.want}).
+			Return(mobyclient.NetworkCreateResult{}, nil)
+		require.NoError(t, createDockerNetwork(ctx, client, "job-network", NewDockerNetworkCreateExecutorInput{}))
+		client.AssertExpectations(t)
+	}
+}
+
+func (m *mockDockerClient) NetworkConnect(ctx context.Context, id string, opts mobyclient.NetworkConnectOptions) (mobyclient.NetworkConnectResult, error) {
+	return mobyclient.NetworkConnectResult{}, m.Called(ctx, id, opts).Error(0)
+}
+
+func (m *mockDockerClient) NetworkDisconnect(ctx context.Context, id string, opts mobyclient.NetworkDisconnectOptions) (mobyclient.NetworkDisconnectResult, error) {
+	return mobyclient.NetworkDisconnectResult{}, m.Called(ctx, id, opts).Error(0)
+}
+
+func TestConnectAndDisconnectNetwork(t *testing.T) {
+	ctx := t.Context()
+	connect := func(answer error) error {
+		client := &mockDockerClient{}
+		client.On("NetworkConnect", ctx, "jobs", mobyclient.NetworkConnectOptions{
+			Container:      "0123456789ab",
+			EndpointConfig: &network.EndpointSettings{Aliases: []string{"0123456789ab"}},
+		}).Return(answer).Once()
+		return connectNetwork(ctx, client, "jobs", "0123456789ab")
+	}
+	require.NoError(t, connect(nil))
+	require.NoError(t, connect(errors.New("endpoint with name runner already exists in network jobs")))
+	require.NoError(t, connect(errors.New("container runner already connected to network jobs")))
+	require.ErrorIs(t, connect(context.Canceled), context.Canceled)
+
+	disconnect := func(answer error) error {
+		client := &mockDockerClient{}
+		client.On("NetworkDisconnect", ctx, "jobs", mobyclient.NetworkDisconnectOptions{
+			Container: "0123456789ab", Force: true,
+		}).Return(answer).Once()
+		return disconnectNetwork(ctx, client, "jobs", "0123456789ab")
+	}
+	require.NoError(t, disconnect(cerrdefs.ErrNotFound))
+	require.NoError(t, disconnect(errors.New("container runner is not connected to the network jobs")))
+	require.ErrorIs(t, disconnect(context.Canceled), context.Canceled)
+}
+
+// Of this runner's networks, only the ones nothing but its own cache container is attached to
+// and old enough to predate any job now starting are the runner's to reclaim. An unexpected
+// NetworkRemove fails the test on its own, since testify has no expectation to match it against.
+func TestRemoveNetworks(t *testing.T) {
+	ctx := t.Context()
 	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"}},
+		{ID: "orphan"},
+		{ID: "busy"},
+		{ID: "starting"},
+		{ID: "cached"},
+		{ID: "shared"},
+		{ID: "gone"},
+		{ID: "raced"},
 	}}, nil)
 	client.On("NetworkInspect", ctx, "orphan", mobyclient.NetworkInspectOptions{}).
-		Return(mobyclient.NetworkInspectResult{}, nil)
+		Return(mobyclient.NetworkInspectResult{}, nil).Twice()
 	client.On("NetworkInspect", ctx, "busy", mobyclient.NetworkInspectOptions{}).
-		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Containers: map[string]network.EndpointResource{"c": {}}}}, nil)
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Containers: map[string]network.EndpointResource{"c": {}}}}, nil).Twice()
 	client.On("NetworkInspect", ctx, "starting", mobyclient.NetworkInspectOptions{}).
-		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Network: network.Network{Created: cutoff.Add(time.Second)}}}, nil)
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{
+			Network:    network.Network{Created: cutoff.Add(time.Second)},
+			Containers: map[string]network.EndpointResource{"0123456789abcdef": {}},
+		}}, nil)
+	client.On("NetworkInspect", ctx, "cached", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Containers: map[string]network.EndpointResource{"0123456789abcdef": {}}}}, nil)
+	client.On("NetworkInspect", ctx, "shared", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{Network: network.Inspect{Containers: map[string]network.EndpointResource{"0123456789abcdef": {}, "job": {}}}}, nil)
+	client.On("NetworkInspect", ctx, "gone", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{}, cerrdefs.ErrNotFound).Twice()
+	client.On("NetworkInspect", ctx, "raced", mobyclient.NetworkInspectOptions{}).
+		Return(mobyclient.NetworkInspectResult{}, nil).Twice()
+	client.On("NetworkRemove", ctx, "raced", mobyclient.NetworkRemoveOptions{}).
+		Return(mobyclient.NetworkRemoveResult{}, cerrdefs.ErrNotFound).Twice()
 	client.On("NetworkRemove", ctx, "orphan", mobyclient.NetworkRemoveOptions{}).
-		Return(mobyclient.NetworkRemoveResult{}, nil)
+		Return(mobyclient.NetworkRemoveResult{}, nil).Twice()
+	client.On("NetworkDisconnect", ctx, "cached", mobyclient.NetworkDisconnectOptions{Container: "0123456789abcdef", Force: true}).
+		Return(nil).Once()
+	client.On("NetworkRemove", ctx, "cached", mobyclient.NetworkRemoveOptions{}).
+		Return(mobyclient.NetworkRemoveResult{}, nil).Once()
 
-	require.NoError(t, removeOrphanNetworks(ctx, client, "runner-1", cutoff))
+	require.NoError(t, removeOrphanNetworks(ctx, client, "runner-1", "0123456789ab", cutoff))
+
+	client.On("NetworkList", ctx, mobyclient.NetworkListOptions{}).Return(mobyclient.NetworkListResult{Items: []network.Summary{
+		{ID: "orphan", Name: "job"},
+		{ID: "busy", Name: "job"},
+		{ID: "gone", Name: "job"},
+		{ID: "raced", Name: "job"},
+		{ID: "shared", Name: "other"},
+	}}, nil)
+	require.NoError(t, removeNetwork(ctx, client, "job"))
 	client.AssertExpectations(t)
 }

act/container/docker_platform.go

@@ -2,7 +2,7 @@
 // Copyright 2025 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 

act/container/docker_platform_test.go

@@ -6,6 +6,7 @@ package container
 import (
 	"testing"
 
+	specs "github.com/opencontainers/image-spec/specs-go/v1"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -17,32 +18,17 @@ func TestParsePlatform(t *testing.T) {
 		assert.Nil(t, got)
 	})
 
-	t.Run("os/arch", func(t *testing.T) {
-		got, err := parsePlatform("linux/amd64")
-		require.NoError(t, err)
-		require.NotNil(t, got)
-		assert.Equal(t, "linux", got.OS)
-		assert.Equal(t, "amd64", got.Architecture)
-		assert.Empty(t, got.Variant)
-	})
-
-	t.Run("os/arch/variant", func(t *testing.T) {
-		got, err := parsePlatform("linux/arm/v7")
-		require.NoError(t, err)
-		require.NotNil(t, got)
-		assert.Equal(t, "linux", got.OS)
-		assert.Equal(t, "arm", got.Architecture)
-		assert.Equal(t, "v7", got.Variant)
-	})
-
-	t.Run("input is lowercased", func(t *testing.T) {
-		got, err := parsePlatform("Linux/AMD64/V8")
-		require.NoError(t, err)
-		require.NotNil(t, got)
-		assert.Equal(t, "linux", got.OS)
-		assert.Equal(t, "amd64", got.Architecture)
-		assert.Equal(t, "v8", got.Variant)
-	})
+	for input, want := range map[string]specs.Platform{
+		"linux/amd64":    {OS: "linux", Architecture: "amd64"},
+		"linux/arm/v7":   {OS: "linux", Architecture: "arm", Variant: "v7"},
+		"Linux/AMD64/V8": {OS: "linux", Architecture: "amd64", Variant: "v8"},
+	} {
+		t.Run(input, func(t *testing.T) {
+			got, err := parsePlatform(input)
+			require.NoError(t, err)
+			assert.Equal(t, &want, got)
+		})
+	}
 
 	for _, bad := range []string{
 		"amd64",
@@ -61,3 +47,26 @@ func TestParsePlatform(t *testing.T) {
 		})
 	}
 }
+
+func TestPlatformMatches(t *testing.T) {
+	for _, testcase := range []struct {
+		requested, image string
+		want             bool
+	}{
+		{"linux/amd64", "linux/amd64", true},
+		{"linux/amd64/v1", "linux/amd64", true},
+		{"linux/arm64", "linux/amd64", false},
+		{"linux/arm64/v8", "linux/arm64", true},
+		{"linux/arm/v7", "linux/arm/v7", true},
+		{"linux/arm", "linux/arm/v7", true},
+		{"linux/arm/v6", "linux/arm/v7", false},
+		{"linux/arm", "linux/arm/v6", true},
+		{"windows/arm/v7", "linux/arm/v7", false},
+	} {
+		requested, err := parsePlatform(testcase.requested)
+		require.NoError(t, err)
+		image, err := parsePlatform(testcase.image)
+		require.NoError(t, err)
+		assert.Equal(t, testcase.want, platformMatches(requested, image), "%s on %s", testcase.requested, testcase.image)
+	}
+}

act/container/docker_proxy.go

@@ -0,0 +1,680 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
+
+package container
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"maps"
+	"mime"
+	"net"
+	"net/http"
+	"net/http/httputil"
+	"os"
+	"path"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+
+	"gitea.com/gitea/runner/act/common"
+
+	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/types/container"
+	"github.com/moby/moby/api/types/mount"
+	"github.com/moby/moby/client"
+)
+
+const (
+	jobLabel      = "com.gitea.runner.job."
+	maxCreateBody = 8 << 20
+
+	dockerProxyProbeTimeout       = 5 * time.Second
+	dockerProxyProbeWorkerTimeout = time.Minute
+	dockerProxyProbeTarget        = "/gitea-runner-probe"
+)
+
+var (
+	createPath    = regexp.MustCompile(`^(/v[0-9.]+)?/(containers|networks|volumes)/create$`)
+	rawStreamPath = regexp.MustCompile(`^(/v[0-9.]+)?/(containers/[^/]+/attach|exec/[^/]+/start)$`)
+)
+
+var dockerProxyProbes sync.Map
+
+type dockerProxyDirectory struct {
+	dir, daemonDir string
+	socket         os.FileInfo
+}
+
+type dockerProxyProbe struct {
+	directory dockerProxyDirectory
+	done      chan struct{}
+	seen      bool
+	err       error
+}
+
+func NewDockerProxy(ctx context.Context, job string) *DockerProxy {
+	if host := os.Getenv("DOCKER_HOST"); runtime.GOOS != "linux" || host != "" && !strings.HasPrefix(host, "unix://") {
+		return nil
+	}
+	probeCtx, cancel := context.WithTimeout(ctx, dockerProxyProbeTimeout)
+	defer cancel()
+	cli, err := client.New(client.FromEnv) // negotiates on first request, so a cached probe costs no round trip
+	if err != nil {
+		return nil
+	}
+	defer cli.Close()
+	daemonSocket, ok := strings.CutPrefix(cli.DaemonHost(), "unix://")
+	if !ok {
+		return nil
+	}
+	socket, err := os.Stat(daemonSocket)
+	if err != nil || socket.Mode()&os.ModeSocket == 0 {
+		return nil
+	}
+	workdir, _ := os.Getwd()
+	key := [3]string{cli.DaemonHost(), workdir, os.TempDir()}
+	probe, err := probeDockerProxyDirectory(probeCtx, cli, key, socket)
+	if err != nil {
+		common.Logger(ctx).Infof("docker proxy probe failed, jobs get the daemon socket directly: %v", err)
+		return nil
+	}
+	if !probe.seen {
+		common.Logger(ctx).Infof("the docker daemon cannot reach the runner's temporary or working directory, jobs get the daemon socket directly")
+		return nil
+	}
+	if ctx.Err() != nil {
+		return nil
+	}
+	proxy, err := StartDockerProxy(daemonSocket, probe.directory.dir, job)
+	if err != nil {
+		dockerProxyProbes.CompareAndDelete(key, probe)
+		common.Logger(ctx).Warnf("docker proxy not started, the job gets the daemon socket directly: %v", err)
+		return nil
+	}
+	proxy.Socket = probe.directory.daemonDir + strings.TrimPrefix(proxy.Socket, probe.directory.dir)
+	return proxy
+}
+
+func probeDockerProxyDirectory(ctx context.Context, cli client.APIClient, key [3]string, socket os.FileInfo) (*dockerProxyProbe, error) {
+	for {
+		probe := &dockerProxyProbe{directory: dockerProxyDirectory{socket: socket}, done: make(chan struct{})}
+		actual, loaded := dockerProxyProbes.LoadOrStore(key, probe)
+		if loaded {
+			probe, _ = actual.(*dockerProxyProbe)
+			if !os.SameFile(probe.directory.socket, socket) { // daemon replacement invalidates cached paths
+				dockerProxyProbes.CompareAndDelete(key, probe)
+				continue
+			}
+		} else {
+			go func() { // outlives callers' deadlines so a slow daemon still gets its result cached
+				defer cli.Close()
+				ctx, cancel := context.WithTimeout(context.Background(), dockerProxyProbeWorkerTimeout)
+				defer cancel()
+				probe.directory.dir, probe.directory.daemonDir = runnerContainerWorkdir(ctx, cli)
+				probe.seen = probe.directory.daemonDir != ""
+				if !probe.seen {
+					if probe.directory.dir, probe.err = filepath.Abs(key[2]); probe.err == nil {
+						probe.directory.daemonDir = probe.directory.dir
+						probe.seen, probe.err = daemonSeesDir(ctx, cli, probe.directory.dir, probe.directory.daemonDir)
+					}
+				}
+				if probe.seen {
+					dockerProxyProbes.LoadOrStore(key, probe)
+				} else {
+					dockerProxyProbes.CompareAndDelete(key, probe)
+				}
+				close(probe.done)
+				removeStaleProbeContainers(cli)
+			}()
+		}
+		select {
+		case <-ctx.Done():
+			return &dockerProxyProbe{}, ctx.Err()
+		case <-probe.done:
+		}
+		if ctx.Err() == nil && errors.Is(probe.err, context.DeadlineExceeded) {
+			continue
+		}
+		return probe, probe.err
+	}
+}
+
+// runnerContainerWorkdir looks the runner's container up by hostname to find the daemon's path to its working directory.
+func runnerContainerWorkdir(ctx context.Context, cli client.APIClient) (workdir, daemonDir string) {
+	workdir, err := os.Getwd()
+	hostname, hostnameErr := os.Hostname()
+	if err != nil || hostnameErr != nil {
+		return "", ""
+	}
+	self, err := cli.ContainerInspect(ctx, hostname, client.ContainerInspectOptions{})
+	if err != nil {
+		return "", ""
+	}
+	if daemonDir = containerInfoFromInspect(self.Container).DaemonPath(workdir); daemonDir == "" {
+		return "", ""
+	}
+	if seen, _ := containerSeesMarker(ctx, cli, workdir, self.Container.ID, workdir); !seen { // the hostname may name another container
+		return "", ""
+	}
+	return workdir, daemonDir
+}
+
+func containerSeesMarker(ctx context.Context, cli client.APIClient, dir, id, containerDir string) (bool, error) {
+	marker, err := os.CreateTemp(dir, "gitea-runner-probe-")
+	if err != nil {
+		return false, err
+	}
+	defer func() {
+		if err := os.Remove(marker.Name()); err != nil {
+			common.Logger(ctx).Warnf("removing the docker proxy probe marker failed: %v", err)
+		}
+	}()
+	if err := marker.Close(); err != nil {
+		return false, err
+	}
+	_, err = cli.ContainerStatPath(ctx, id, client.ContainerStatPathOptions{Path: path.Join(containerDir, filepath.Base(marker.Name()))})
+	if cerrdefs.IsNotFound(err) {
+		return false, nil
+	}
+	return err == nil, err
+}
+
+// daemonSeesDir reports whether the daemon opens the files the runner writes in dir by their path in daemonDir,
+// which is what a job's proxy socket mounted from there needs.
+func daemonSeesDir(ctx context.Context, cli client.APIClient, dir, daemonDir string) (bool, error) {
+	images, err := cli.ImageList(ctx, client.ImageListOptions{})
+	if err != nil {
+		return false, err
+	}
+	if len(images.Items) == 0 {
+		return false, errors.New("no image available for the docker proxy probe")
+	}
+	var created client.ContainerCreateResult
+	for _, image := range images.Items {
+		created, err = cli.ContainerCreate(ctx, client.ContainerCreateOptions{
+			Config: &container.Config{Image: image.ID, Cmd: []string{"true"}},
+			HostConfig: &container.HostConfig{Mounts: []mount.Mount{
+				{Type: mount.TypeBind, Source: daemonDir, Target: dockerProxyProbeTarget, ReadOnly: true}, // not the marker itself, podman creates a missing bind source where docker rejects it
+			}},
+		})
+		if !cerrdefs.IsNotFound(err) {
+			break
+		}
+	}
+	if cerrdefs.IsInvalidArgument(err) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	seen, err := containerSeesMarker(ctx, cli, dir, created.ID, dockerProxyProbeTarget)
+	cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), dockerProxyProbeTimeout)
+	defer cancel()
+	if _, removeErr := cli.ContainerRemove(cleanupCtx, created.ID, client.ContainerRemoveOptions{Force: true, RemoveVolumes: true}); removeErr != nil {
+		return false, fmt.Errorf("removing the docker proxy probe container failed: %w", removeErr)
+	}
+	return seen, err
+}
+
+// removeStaleProbeContainers removes probe containers left by abandoned creates once any probe in flight when listed has ended.
+func removeStaleProbeContainers(cli client.APIClient) {
+	ctx, cancel := context.WithTimeout(context.Background(), dockerProxyProbeTimeout)
+	defer cancel()
+	listed, err := cli.ContainerList(ctx, client.ContainerListOptions{
+		All:     true,
+		Filters: make(client.Filters).Add("status", string(container.StateCreated)).Add("volume", dockerProxyProbeTarget),
+	})
+	if err != nil {
+		common.Logger(ctx).Warnf("listing stale docker proxy probe containers failed: %v", err)
+		return
+	}
+	listed.Items = slices.DeleteFunc(listed.Items, func(stale container.Summary) bool {
+		return stale.State != container.StateCreated || !slices.ContainsFunc(stale.Mounts, func(mountPoint container.MountPoint) bool {
+			return mountPoint.Type == mount.TypeBind && !mountPoint.RW && mountPoint.Destination == dockerProxyProbeTarget
+		})
+	})
+	if len(listed.Items) == 0 {
+		return
+	}
+	time.Sleep(dockerProxyProbeWorkerTimeout + dockerProxyProbeTimeout)
+	for _, stale := range listed.Items {
+		ctx, cancel := context.WithTimeout(context.Background(), dockerProxyProbeTimeout)
+		if err := (&containerReference{cli: cli, id: stale.ID}).remove()(ctx); err != nil {
+			common.Logger(ctx).Warnf("removing stale docker proxy probe container failed: %v", err)
+		}
+		cancel()
+	}
+}
+
+// StartDockerProxy serves a job's docker socket in dir, labelling what the job creates through it.
+func StartDockerProxy(daemonSocket, dir, job string) (*DockerProxy, error) {
+	info, err := os.Stat(daemonSocket)
+	if err != nil {
+		return nil, err
+	}
+	if info.Mode()&os.ModeSocket == 0 {
+		return nil, errors.New("docker daemon path is not a Unix socket")
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return nil, err
+	}
+	instance, err := os.MkdirTemp(dir, "p-")
+	if err != nil {
+		return nil, err
+	}
+	socket := filepath.Join(instance, "docker.sock")
+	listener, err := net.Listen("unix", socket)
+	if err != nil {
+		return nil, errors.Join(err, os.RemoveAll(instance))
+	}
+	if err := copyDockerSocketPermissions(daemonSocket, socket, info); err != nil {
+		return nil, errors.Join(err, listener.Close(), os.RemoveAll(instance))
+	}
+	dial := func(ctx context.Context, _, _ string) (net.Conn, error) {
+		return (&net.Dialer{}).DialContext(ctx, "unix", daemonSocket)
+	}
+	transport := &http.Transport{DialContext: dial}
+	forward := &httputil.ReverseProxy{
+		Rewrite: func(r *httputil.ProxyRequest) {
+			r.Out.URL.Scheme = "http"
+			r.Out.URL.Host = "docker"
+		},
+		Transport: transport,
+	}
+	proxy := &DockerProxy{Socket: socket}
+	streams, cancelStreams := context.WithCancel(context.Background())
+	creates, cancelCreates := context.WithCancel(context.Background())
+	var admission sync.Mutex
+	var handlers sync.WaitGroup
+	server := &http.Server{ReadHeaderTimeout: 30 * time.Second, ConnContext: func(ctx context.Context, conn net.Conn) context.Context {
+		return context.WithValue(ctx, dockerProxyConnKey{}, conn)
+	}, Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		admission.Lock()
+		if streams.Err() != nil {
+			admission.Unlock()
+			http.Error(w, "docker proxy is closing", http.StatusServiceUnavailable)
+			return
+		}
+		handlers.Add(1)
+		admission.Unlock()
+		defer handlers.Done()
+		creating := r.Method == http.MethodPost && createPath.MatchString(r.URL.Path)
+		parent, lifetime := r.Context(), streams
+		if creating {
+			parent, lifetime = context.WithoutCancel(parent), creates
+		}
+		ctx, cancel := context.WithCancel(parent)
+		defer cancel()
+		stop := context.AfterFunc(lifetime, func() {
+			cancel()
+			if !creating {
+				if conn, ok := parent.Value(dockerProxyConnKey{}).(net.Conn); ok {
+					_ = conn.Close()
+				}
+			}
+		})
+		defer stop()
+		r = r.WithContext(ctx)
+		if creating {
+			r.Body = http.MaxBytesReader(w, r.Body, maxCreateBody)
+			mounts, _ := proxy.mounts.Load().(map[string]string)
+			if err := rewriteCreate(r, job, mounts); err != nil {
+				status := http.StatusBadRequest
+				if _, ok := errors.AsType[*http.MaxBytesError](err); ok {
+					status = http.StatusRequestEntityTooLarge
+				}
+				http.Error(w, err.Error(), status)
+				return
+			}
+		} else if r.Method == http.MethodPost && rawStreamPath.MatchString(r.URL.Path) {
+			tunnel(w, r, dial, forward)
+			return
+		}
+		forward.ServeHTTP(w, r)
+	})}
+	served := make(chan struct{})
+	go func() {
+		defer close(served)
+		_ = server.Serve(listener)
+	}()
+	proxy.close = func(ctx context.Context) error {
+		ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+		defer cancel()
+		admission.Lock()
+		listenerErr := listener.Close()
+		cancelStreams()
+		admission.Unlock()
+		<-served
+		shutdownErr := server.Shutdown(ctx)
+		cancelCreates()
+		serverErr := server.Close()
+		handlers.Wait()
+		transport.CloseIdleConnections()
+		return errors.Join(ctx.Err(), listenerErr, shutdownErr, serverErr, os.RemoveAll(instance))
+	}
+	return proxy, nil
+}
+
+func rewriteCreate(r *http.Request, job string, mounts map[string]string) error {
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		return err
+	}
+	if len(bytes.TrimSpace(body)) == 0 {
+		body = []byte("{}")
+	}
+	var fields map[string]json.RawMessage
+	var config struct{ Labels map[string]string }
+	if err := json.Unmarshal(body, &fields); err != nil {
+		return fmt.Errorf("invalid create request: %w", err)
+	}
+	if err := json.Unmarshal(body, &config); err != nil {
+		return fmt.Errorf("invalid create labels: %w", err)
+	}
+	if fields == nil {
+		fields = make(map[string]json.RawMessage)
+	}
+	if len(mounts) > 0 && !hasAmbiguousFields(body) {
+		translateBinds(fields, createPath.FindStringSubmatch(r.URL.Path)[2], mounts)
+	}
+	maps.DeleteFunc(fields, func(name string, _ json.RawMessage) bool {
+		return strings.EqualFold(name, "Labels")
+	})
+	if config.Labels == nil {
+		config.Labels = make(map[string]string)
+	}
+	config.Labels[jobLabel+job] = "" // per-job key, so nested proxies keep each other's
+	if fields["Labels"], err = json.Marshal(config.Labels); err != nil {
+		return err
+	}
+	if body, err = json.Marshal(fields); err != nil {
+		return err
+	}
+	r.Body = io.NopCloser(bytes.NewReader(body))
+	r.ContentLength = int64(len(body))
+	r.TransferEncoding = nil
+	return nil
+}
+
+func translateBinds(fields map[string]json.RawMessage, kind string, mounts map[string]string) {
+	cleanedSource := func(source string) string {
+		cleaned := path.Clean(source)
+		if target := jobMount(cleaned, mounts); mounts[target] != "" {
+			return mounts[target] + cleaned[len(target):]
+		}
+		return source
+	}
+	spelledSource := func(source string) string { // dockerd checks these as spelled
+		target := jobMount(path.Clean(source), mounts)
+		if rest, spelled := strings.CutPrefix(source, target); mounts[target] != "" && spelled && (rest == "" || rest[0] == '/') && filepath.IsLocal("."+rest) {
+			return mounts[target] + rest
+		}
+		return cleanedSource(source)
+	}
+	switch kind {
+	case "volumes":
+		var driver string
+		var options map[string]any
+		decodeField(fields, "Driver", &driver)
+		if key := decodeField(fields, "DriverOpts", &options); options != nil {
+			translateDevice(driver, options, spelledSource)
+			if encoded, err := json.Marshal(options); err == nil {
+				fields[key] = encoded
+			}
+		}
+	case "containers":
+		var hostConfig map[string]any
+		key := decodeField(fields, "HostConfig", &hostConfig)
+		binds, _ := field(hostConfig, "Binds").([]any)
+		for i, bind := range binds {
+			bind, _ := bind.(string)
+			source, target, _ := strings.Cut(bind, ":")
+			if translated := cleanedSource(source); strings.HasPrefix(target, "/") && !strings.Contains(translated, ":") {
+				binds[i] = translated + ":" + target
+			}
+		}
+		specs, _ := field(hostConfig, "Mounts").([]any)
+		for _, spec := range specs {
+			spec, _ := spec.(map[string]any)
+			switch field(spec, "Type") {
+			case "bind":
+				if source, ok := field(spec, "Source").(string); ok {
+					spec["Source"] = spelledSource(source)
+				}
+			case "volume":
+				volumeOptions, _ := field(spec, "VolumeOptions").(map[string]any)
+				driverConfig, _ := field(volumeOptions, "DriverConfig").(map[string]any)
+				translateDevice(field(driverConfig, "Name"), field(driverConfig, "Options"), spelledSource)
+			}
+		}
+		if encoded, err := json.Marshal(hostConfig); err == nil && hostConfig != nil {
+			fields[key] = encoded
+		}
+	}
+}
+
+func decodeField(fields map[string]json.RawMessage, name string, value any) string {
+	for key, raw := range fields {
+		if strings.EqualFold(key, name) {
+			decoder := json.NewDecoder(bytes.NewReader(raw))
+			decoder.UseNumber()
+			_ = decoder.Decode(value) // wrong types stay unset for dockerd to reject
+			return key
+		}
+	}
+	return ""
+}
+
+func translateDevice(driver, options any, translate func(string) string) {
+	optionMap, _ := options.(map[string]any)
+	device, ok := optionMap["device"].(string)
+	flags, _ := optionMap["o"].(string)
+	tokens := strings.Split(flags, ",")
+	local := driver == nil || driver == "" || driver == "local"
+	if ok && local && (slices.Contains(tokens, "bind") || slices.Contains(tokens, "rbind")) && !slices.Contains(tokens, "remount") {
+		optionMap["device"] = translate(device)
+	}
+}
+
+// field also renames the matched key to name.
+func field(object map[string]any, name string) any {
+	for key, value := range object {
+		if strings.EqualFold(key, name) {
+			delete(object, key)
+			object[name] = value
+			return value
+		}
+	}
+	return nil
+}
+
+var (
+	requestFields = []string{"hostconfig", "driver", "driveropts"}
+	asciiFolds    = strings.NewReplacer("ſ", "s", "K", "k") // the non-ASCII runes strings.EqualFold matches to ASCII letters
+)
+
+// dockerd settles repeated names by order, which re-encoding loses.
+func hasAmbiguousFields(body []byte) bool {
+	type frame struct {
+		names     map[string]bool
+		key       string
+		expectKey bool
+		nested    bool
+	}
+	decoder := json.NewDecoder(bytes.NewReader(body))
+	decoder.UseNumber()
+	stack := []*frame{{}}
+	for {
+		token, err := decoder.Token()
+		if err != nil {
+			return !errors.Is(err, io.EOF)
+		}
+		top := stack[len(stack)-1]
+		if name, ok := token.(string); ok && top.expectKey {
+			top.key, top.expectKey = strings.ToLower(asciiFolds.Replace(name)), false
+			if top.names[top.key] && (top.nested || slices.Contains(requestFields, top.key)) {
+				return true
+			}
+			top.names[top.key] = true
+			continue
+		}
+		top.expectKey = top.names != nil
+		nested := top.nested || len(stack) == 2 && slices.Contains(requestFields, top.key)
+		switch token {
+		case json.Delim('{'):
+			stack = append(stack, &frame{names: map[string]bool{}, expectKey: true, nested: nested})
+		case json.Delim('['):
+			stack = append(stack, &frame{nested: nested})
+		case json.Delim('}'), json.Delim(']'):
+			stack = stack[:len(stack)-1]
+		}
+	}
+}
+
+// jobMount returns "" also for a path already naming a daemon source.
+func jobMount(source string, mounts map[string]string) string {
+	target := ""
+	for destination, daemonSource := range mounts {
+		if daemonSource != "" && (source == daemonSource || strings.HasPrefix(source, daemonSource+"/")) {
+			return ""
+		}
+		if len(destination) > len(target) && (source == destination || strings.HasPrefix(source, destination+"/")) {
+			target = destination
+		}
+	}
+	return target
+}
+
+type dockerProxyConnKey struct{}
+
+type dockerProxyResponse struct {
+	response *http.Response
+}
+
+func (r dockerProxyResponse) RoundTrip(_ *http.Request) (*http.Response, error) {
+	return r.response, nil
+}
+
+// tunnel splices attach and exec streams, which the daemon hijacks with or without an HTTP upgrade
+func tunnel(w http.ResponseWriter, r *http.Request, dial func(context.Context, string, string) (net.Conn, error), forward *httputil.ReverseProxy) {
+	upstream, err := dial(r.Context(), "", "")
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadGateway)
+		return
+	}
+	defer upstream.Close()
+	stop := context.AfterFunc(r.Context(), func() { _ = upstream.Close() })
+	defer stop()
+	if err := r.Write(upstream); err != nil {
+		http.Error(w, err.Error(), http.StatusBadGateway)
+		return
+	}
+	reader := bufio.NewReader(upstream)
+	var response *http.Response
+	for {
+		response, err = http.ReadResponse(reader, r)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusBadGateway)
+			return
+		}
+		if response.StatusCode >= 200 || response.StatusCode == http.StatusSwitchingProtocols {
+			break
+		}
+		maps.Copy(w.Header(), response.Header)
+		w.WriteHeader(response.StatusCode)
+		clear(w.Header())
+		_ = response.Body.Close()
+	}
+	defer func() {
+		_ = upstream.Close()
+		_ = response.Body.Close()
+	}()
+	mediaType, _, _ := mime.ParseMediaType(response.Header.Get("Content-Type"))
+	if response.StatusCode != http.StatusSwitchingProtocols && (response.StatusCode != http.StatusOK || mediaType != "application/vnd.docker.raw-stream") {
+		ordinary := *forward
+		ordinary.Transport = dockerProxyResponse{response: response}
+		ordinary.ServeHTTP(w, r)
+		return
+	}
+	downstream, buffered, err := http.NewResponseController(w).Hijack()
+	if err != nil {
+		return
+	}
+	defer downstream.Close()
+	if _, err := fmt.Fprintf(buffered, "%s %s\r\n", response.Proto, response.Status); err != nil {
+		return
+	}
+	if err := response.Header.Write(buffered); err != nil {
+		return
+	}
+	if _, err := buffered.WriteString("\r\n"); err != nil {
+		return
+	}
+	if err := buffered.Flush(); err != nil {
+		return
+	}
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		if _, err := io.Copy(upstream, io.MultiReader(io.LimitReader(buffered, int64(buffered.Reader.Buffered())), downstream)); err != nil { // Bypass net/http after the prefix so stdin EOF preserves output.
+			_ = upstream.Close()
+		} else if writer, ok := upstream.(interface{ CloseWrite() error }); ok {
+			_ = writer.CloseWrite()
+		} else {
+			_ = upstream.Close()
+		}
+	}()
+	_, _ = io.Copy(downstream, reader)
+	_ = downstream.Close()
+	_ = upstream.Close()
+	<-done
+}
+
+func RemoveDockerJobResources(ctx context.Context, job string) error {
+	cli, err := GetDockerClient(ctx)
+	if err != nil {
+		return err
+	}
+	defer cli.Close()
+	return removeLabelled(ctx, cli, job)
+}
+
+func removeLabelled(ctx context.Context, cli client.APIClient, job string) error {
+	logger := common.Logger(ctx)
+	filters := make(client.Filters).Add("label", jobLabel+job)
+	containers, err := cli.ContainerList(ctx, client.ContainerListOptions{All: true, Filters: filters})
+	errs := []error{err}
+	for _, c := range containers.Items {
+		logger.Infof("removing container %s the job left behind", strings.TrimPrefix(strings.Join(c.Names, ","), "/"))
+		errs = append(errs, (&containerReference{cli: cli, id: c.ID}).remove()(ctx))
+	}
+	networks, err := cli.NetworkList(ctx, client.NetworkListOptions{Filters: filters})
+	errs = append(errs, err)
+	for _, n := range networks.Items {
+		if _, err := cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); n.Scope == "swarm" && cerrdefs.IsInvalidArgument(err) { // swarm refuses while a service or its tasks use it
+			logger.Infof("keeping network %s, a swarm service still uses it", n.Name)
+		} else if err != nil && !cerrdefs.IsNotFound(err) {
+			errs = append(errs, fmt.Errorf("failed to remove network %s: %w", n.Name, err))
+		}
+	}
+	volumes, err := cli.VolumeList(ctx, client.VolumeListOptions{Filters: filters})
+	errs = append(errs, err)
+	for _, v := range volumes.Items {
+		if _, err := cli.VolumeRemove(ctx, v.Name, client.VolumeRemoveOptions{}); err != nil && !cerrdefs.IsNotFound(err) {
+			errs = append(errs, fmt.Errorf("failed to remove volume %s: %w", v.Name, err))
+		}
+	}
+	return errors.Join(errs...)
+}

act/container/docker_proxy_test.go

@@ -0,0 +1,805 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
+
+package container
+
+import (
+	"archive/tar"
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/types/container"
+	"github.com/moby/moby/api/types/image"
+	"github.com/moby/moby/api/types/mount"
+	"github.com/moby/moby/api/types/network"
+	"github.com/moby/moby/api/types/volume"
+	mobyclient "github.com/moby/moby/client"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+)
+
+func (m *mockDockerClient) VolumeList(ctx context.Context, opts mobyclient.VolumeListOptions) (mobyclient.VolumeListResult, error) {
+	args := m.Called(ctx, opts)
+	return args.Get(0).(mobyclient.VolumeListResult), args.Error(1)
+}
+
+func (m *mockDockerClient) VolumeRemove(ctx context.Context, id string, opts mobyclient.VolumeRemoveOptions) (mobyclient.VolumeRemoveResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.VolumeRemoveResult), args.Error(1)
+}
+
+// unix socket paths are limited to about a hundred bytes, which the default macOS TMPDIR exceeds
+func shortTempDir(t testing.TB) string {
+	t.Helper()
+	t.Setenv("TMPDIR", "/tmp")
+	return t.TempDir()
+}
+
+func daemonSocketPath(t testing.TB, cli mobyclient.APIClient) string {
+	t.Helper()
+	host := cli.DaemonHost()
+	if !strings.HasPrefix(host, "unix://") {
+		t.Skipf("skipping: daemon at %s is not a unix socket", host)
+	}
+	return strings.TrimPrefix(host, "unix://")
+}
+
+func TestDockerProxy(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Unix socket ownership is unavailable on Windows")
+	}
+	bodies := make(chan []byte, 8)
+	createStarted, releaseCreate := make(chan struct{}), make(chan struct{})
+	streamsDone := make(chan struct{}, 2)
+	var probes atomic.Int32
+	daemonSocket := filepath.Join(shortTempDir(t), "d.sock")
+	listener, err := net.Listen("unix", daemonSocket)
+	require.NoError(t, err)
+	daemon := &http.Server{ReadHeaderTimeout: time.Second, Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/create"):
+			body, _ := io.ReadAll(r.Body)
+			if bytes.Contains(body, []byte(`"Image":"probe-image"`)) {
+				_, _ = w.Write([]byte(`{"Id":"probe"}`))
+				return
+			}
+			if r.URL.RawQuery == "wait" {
+				close(createStarted)
+				<-releaseCreate
+			}
+			bodies <- body
+			w.WriteHeader(http.StatusCreated)
+		case strings.HasSuffix(r.URL.Path, "/images/json"):
+			if probes.Add(1) == 1 {
+				http.Error(w, "probe unavailable", http.StatusServiceUnavailable)
+				return
+			}
+			_, _ = w.Write([]byte(`[{"Id":"probe-image"}]`))
+		case strings.HasSuffix(r.URL.Path, "/containers/json"):
+			_, _ = w.Write([]byte(`[]`))
+		case strings.HasSuffix(r.URL.Path, "/json"):
+			http.NotFound(w, r)
+		case strings.HasSuffix(r.URL.Path, "/archive"):
+			w.Header().Set("X-Docker-Container-Path-Stat", "e30=")
+		case r.Method == http.MethodDelete:
+			w.WriteHeader(http.StatusNoContent)
+		case r.URL.Path == "/exec/detached/start" || r.URL.Path == "/exec/error/start":
+			if r.URL.Path == "/exec/error/start" {
+				w.Header().Set("Content-Type", "application/vnd.docker.raw-stream")
+				w.WriteHeader(http.StatusBadRequest)
+			}
+			_, _ = w.Write([]byte("ordinary"))
+		case rawStreamPath.MatchString(r.URL.Path) || r.URL.Path == "/session":
+			_, _ = io.Copy(io.Discard, r.Body)
+			conn, buffered, err := w.(http.Hijacker).Hijack()
+			if err != nil {
+				return
+			}
+			defer conn.Close()
+			if r.Header.Get("Upgrade") != "" {
+				_, _ = conn.Write([]byte("HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: tcp\r\n\r\nready\n"))
+			} else {
+				_, _ = conn.Write([]byte("HTTP/1.1 200 OK\r\nContent-Type: application/vnd.docker.raw-stream\r\n\r\nready\n"))
+			}
+			input, _ := io.ReadAll(buffered)
+			_, _ = conn.Write(append([]byte("final:"), input...))
+			streamsDone <- struct{}{}
+		default:
+			w.Header().Set("Api-Version", "1.47")
+			_, _ = w.Write([]byte("OK " + r.Method + " " + r.URL.Path))
+		}
+	})}
+	go func() { _ = daemon.Serve(listener) }()
+	t.Cleanup(func() { _ = daemon.Close() })
+	proxy, err := StartDockerProxy(daemonSocket, shortTempDir(t), "job-1")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = proxy.Close(context.Background()) })
+	proxy.SetMounts(map[string]string{"/workspace/o/r": "/volumes/job/_data", "/workspace/o/r/tmp": "", "/var/run/docker.sock": "/tmp/p/docker.sock", "/volumes": "/daemon/volumes"})
+	client := &http.Client{Timeout: 5 * time.Second, Transport: &http.Transport{DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+		return (&net.Dialer{}).DialContext(ctx, "unix", proxy.Socket)
+	}}}
+	t.Cleanup(client.CloseIdleConnections)
+	dialProxy := func(t *testing.T) *net.UnixConn {
+		t.Helper()
+		conn, err := net.DialUnix("unix", nil, &net.UnixAddr{Name: proxy.Socket, Net: "unix"})
+		require.NoError(t, err)
+		t.Cleanup(func() { _ = conn.Close() })
+		require.NoError(t, conn.SetDeadline(time.Now().Add(5*time.Second)))
+		return conn
+	}
+	startStream := func(t *testing.T, path, upgrade string) (*net.UnixConn, *bufio.Reader) {
+		t.Helper()
+		conn := dialProxy(t)
+		_, err := fmt.Fprintf(conn, "POST %s HTTP/1.1\r\nHost: docker\r\n%sContent-Length: 2\r\n\r\n{}input", path, upgrade)
+		require.NoError(t, err)
+		reader := bufio.NewReader(conn)
+		resp, err := http.ReadResponse(reader, nil)
+		require.NoError(t, err)
+		t.Cleanup(func() {
+			_ = conn.Close()
+			_ = resp.Body.Close()
+		})
+		prefix, err := reader.ReadString('\n')
+		require.NoError(t, err)
+		require.Equal(t, "ready\n", prefix)
+		return conn, reader
+	}
+
+	t.Run("labels creates", func(t *testing.T) {
+		for _, testCase := range []struct{ path, body, want string }{
+			{
+				"/v1.47/containers/create", `{"Image":"alpine","Unknown":{"enabled":true},"Labels":{"own":"1","com.gitea.runner.job.job-0":""}}`,
+				`{"Image":"alpine","Unknown":{"enabled":true},"Labels":{"own":"1","com.gitea.runner.job.job-0":"","com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/containers/create", `{"HostConfig":{"Binds":["/workspace/o/r:/src:ro","/workspace/o/r/../r/sub/:/sub","workspace/o/r:/relative","/workspace/o/rest:/rest","/workspace/o/r/tmp/x:/tmp","named:/named","/anonymous","/workspace/o/r:ro","/volumes/job/_data/x:/daemon-path"]},"DriverOpts":{"o":"bind","device":"/workspace/o/r"},"Labels":{"Foo":"1","foo":"2"}}`,
+				`{"HostConfig":{"Binds":["/volumes/job/_data:/src:ro","/volumes/job/_data/sub:/sub","workspace/o/r:/relative","/workspace/o/rest:/rest","/workspace/o/r/tmp/x:/tmp","named:/named","/anonymous","/workspace/o/r:ro","/volumes/job/_data/x:/daemon-path"]},"DriverOpts":{"o":"bind","device":"/workspace/o/r"},"Labels":{"Foo":"1","foo":"2","com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/containers/create", `{"HostConfig":{"Mounts":[{"Type":"bind","Source":"/var/run/docker.sock","Target":"/var/run/docker.sock"},{"type":"bind","source":"/workspace/o/r/sub/","target":"/m"},{"Type":"bind","Source":"/workspace/o/r/sub/../data","Target":"/dotted"},{"Type":"bind","Source":"/workspace/o/r/../r","Target":"/escaping"},{"Type":"BIND","Source":"/workspace/o/r"},{"Type":"volume","Source":"/workspace/o/r"}]}}`,
+				`{"HostConfig":{"Mounts":[{"Type":"bind","Source":"/tmp/p/docker.sock","Target":"/var/run/docker.sock"},{"Type":"bind","Source":"/volumes/job/_data/sub/","target":"/m"},{"Type":"bind","Source":"/volumes/job/_data/sub/../data","Target":"/dotted"},{"Type":"bind","Source":"/volumes/job/_data","Target":"/escaping"},{"Type":"BIND","Source":"/workspace/o/r"},{"Type":"volume","Source":"/workspace/o/r"}]},"Labels":{"com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/containers/create", `{"HostConfig":{"Mounts":[{"Type":"volume","VolumeOptions":{"DriverConfig":{"Options":{"o":"bind","device":"/workspace/o/r/data"}}}},{"Type":"volume","VolumeOptions":{"DriverConfig":{"Options":{"o":"unbindable","device":"/workspace/o/r"}}}},{"Type":"volume","VolumeOptions":{"DriverConfig":{"Options":{"o":"bind,remount","device":"/workspace/o/r"}}}},{"Type":"volume","VolumeOptions":{"DriverConfig":{"Name":"plugin","Options":{"o":"bind","device":"/workspace/o/r"}}}}]}}`,
+				`{"HostConfig":{"Mounts":[{"Type":"volume","VolumeOptions":{"DriverConfig":{"Options":{"o":"bind","device":"/volumes/job/_data/data"}}}},{"Type":"volume","VolumeOptions":{"DriverConfig":{"Options":{"o":"unbindable","device":"/workspace/o/r"}}}},{"Type":"volume","VolumeOptions":{"DriverConfig":{"Options":{"o":"bind,remount","device":"/workspace/o/r"}}}},{"Type":"volume","VolumeOptions":{"DriverConfig":{"Name":"plugin","Options":{"o":"bind","device":"/workspace/o/r"}}}}]},"Labels":{"com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/containers/create", `{"HostConfig":{"privileged":true,"Privileged":false,"Binds":["/workspace/o/r:/src"]},"hoſtconfig":null}`,
+				`{"HostConfig":{"privileged":true,"Privileged":false,"Binds":["/workspace/o/r:/src"]},"hoſtconfig":null,"Labels":{"com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/networks/create", `{"Name":"n"}`,
+				`{"Name":"n","Labels":{"com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/volumes/create", `{"Name":"v","labels":null,"DriverOpts":{"type":"none","o":"rbind,ro","device":"/workspace/o/r/"},"HostConfig":{"Binds":["/workspace/o/r:/src"]}}`,
+				`{"Name":"v","Labels":{"com.gitea.runner.job.job-1":""},"DriverOpts":{"type":"none","o":"rbind,ro","device":"/volumes/job/_data/"},"HostConfig":{"Binds":["/workspace/o/r:/src"]}}`,
+			},
+			{
+				"/volumes/create", `{"Name":"d","DriverOpts":{"o":"bind","device":1,"device":"/workspace/o/r"}}`,
+				`{"Name":"d","DriverOpts":{"o":"bind","device":1,"device":"/workspace/o/r"},"Labels":{"com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/volumes/create", `{"Name":"p","Driver":"plugin","DriverOpts":{"o":"bind","device":"/workspace/o/r"}}`,
+				`{"Name":"p","Driver":"plugin","DriverOpts":{"o":"bind","device":"/workspace/o/r"},"Labels":{"com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/volumes/create", "",
+				`{"Labels":{"com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/volumes/create", "null",
+				`{"Labels":{"com.gitea.runner.job.job-1":""}}`,
+			},
+			{
+				"/volumes/create", `{"Labels":{"discard":"1"},"labels":null,"LABELS":{"own":"1"},"LABELS":{"extra":"2"}}`,
+				`{"Labels":{"own":"1","extra":"2","com.gitea.runner.job.job-1":""}}`,
+			},
+		} {
+			resp, err := client.Post("http://docker"+testCase.path, "application/json", strings.NewReader(testCase.body))
+			require.NoError(t, err)
+			resp.Body.Close()
+			require.Equal(t, http.StatusCreated, resp.StatusCode)
+			assert.JSONEq(t, testCase.want, string(<-bodies), testCase.body)
+		}
+	})
+
+	t.Run("passes other requests through", func(t *testing.T) {
+		resp, err := client.Get("http://docker/v1.47/_ping")
+		require.NoError(t, err)
+		defer resp.Body.Close()
+		body, _ := io.ReadAll(resp.Body)
+		assert.Equal(t, "1.47", resp.Header.Get("Api-Version"))
+		assert.Equal(t, "OK GET /v1.47/_ping", string(body))
+	})
+
+	t.Run("discovery caches only successes", func(t *testing.T) {
+		if runtime.GOOS != "linux" {
+			t.Skip("automatic proxy discovery requires Linux")
+		}
+		t.Setenv("DOCKER_HOST", "unix://"+daemonSocket)
+		tempDir := shortTempDir(t)
+		t.Setenv("TMPDIR", tempDir)
+		require.Nil(t, NewDockerProxy(t.Context(), "failed"))
+		for _, job := range []string{"first", "second"} {
+			proxy := NewDockerProxy(t.Context(), job)
+			require.NotNil(t, proxy)
+			require.NoError(t, proxy.Close(context.Background()))
+		}
+		assert.EqualValues(t, 2, probes.Load())
+		workdir, err := os.Getwd()
+		require.NoError(t, err)
+		cached, _ := dockerProxyProbes.Load([3]string{"unix://" + daemonSocket, workdir, tempDir})
+		cached.(*dockerProxyProbe).directory.socket, _ = os.Stat(t.TempDir())
+		proxy := NewDockerProxy(t.Context(), "replaced daemon")
+		require.NotNil(t, proxy)
+		require.NoError(t, proxy.Close(context.Background()))
+		assert.EqualValues(t, 3, probes.Load())
+	})
+
+	t.Run("tunnels raw streams through stdin EOF", func(t *testing.T) {
+		for _, stream := range []struct{ path, upgrade string }{
+			{path: "/v1.47/exec/abc/start"},
+			{path: "/containers/abc/attach", upgrade: "Connection: Upgrade\r\nUpgrade: tcp\r\n"},
+		} {
+			conn, reader := startStream(t, stream.path, stream.upgrade)
+			require.NoError(t, conn.CloseWrite())
+			output, err := io.ReadAll(reader)
+			require.NoError(t, err)
+			assert.Equal(t, "final:input", string(output))
+			<-streamsDone
+		}
+	})
+
+	t.Run("detached and error responses retain keepalive label injection", func(t *testing.T) {
+		conn := dialProxy(t)
+		reader := bufio.NewReader(conn)
+		for endpoint, status := range map[string]int{"detached": http.StatusOK, "error": http.StatusBadRequest} {
+			_, err := fmt.Fprintf(conn, "POST /exec/%s/start HTTP/1.1\r\nHost: docker\r\nContent-Length: 2\r\n\r\n{}", endpoint)
+			require.NoError(t, err)
+			resp, err := http.ReadResponse(reader, nil)
+			require.NoError(t, err)
+			body, err := io.ReadAll(resp.Body)
+			require.NoError(t, err)
+			require.NoError(t, resp.Body.Close())
+			assert.Equal(t, status, resp.StatusCode)
+			assert.Equal(t, "ordinary", string(body))
+			_, err = io.WriteString(conn, "POST /volumes/create HTTP/1.1\r\nHost: docker\r\nContent-Length: 0\r\n\r\n")
+			require.NoError(t, err)
+			resp, err = http.ReadResponse(reader, nil)
+			require.NoError(t, err)
+			require.NoError(t, resp.Body.Close())
+			require.Equal(t, http.StatusCreated, resp.StatusCode)
+			assert.JSONEq(t, `{"Labels":{"com.gitea.runner.job.job-1":""}}`, string(<-bodies))
+		}
+	})
+
+	t.Run("close joins streams and admitted create", func(t *testing.T) {
+		t.Cleanup(func() { close(releaseCreate) })
+		_, raw := startStream(t, "/exec/live/start", "")
+		_, upgraded := startStream(t, "/session", "Connection: Upgrade\r\nUpgrade: tcp\r\n")
+		creator := dialProxy(t)
+		_, err := io.WriteString(creator, "POST /volumes/create?wait HTTP/1.1\r\nHost: docker\r\nContent-Length: 2\r\n\r\n{}")
+		require.NoError(t, err)
+		<-createStarted
+		require.NoError(t, creator.CloseWrite())
+		closed := make(chan error, 1)
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+		defer cancel()
+		go func() { closed <- proxy.Close(ctx) }()
+		for _, reader := range []*bufio.Reader{raw, upgraded} {
+			_, err := reader.ReadByte()
+			require.ErrorIs(t, err, io.EOF)
+			<-streamsDone
+		}
+		select {
+		case err := <-closed:
+			t.Fatalf("Close returned before admitted create settled: %v", err)
+		default:
+		}
+		releaseCreate <- struct{}{}
+		resp, err := http.ReadResponse(bufio.NewReader(creator), nil)
+		require.NoError(t, err)
+		require.NoError(t, resp.Body.Close())
+		require.Equal(t, http.StatusCreated, resp.StatusCode)
+		assert.JSONEq(t, `{"Labels":{"com.gitea.runner.job.job-1":""}}`, string(<-bodies))
+		require.NoError(t, <-closed)
+	})
+}
+
+func TestRemoveLabelledRemovesContainersNetworksAndVolumes(t *testing.T) {
+	containerFailure := errors.New("container removal failed")
+	listFailure := errors.New("listing failed")
+	volumeFailure := errors.New("volume removal failed")
+	ctx := t.Context()
+	filters := make(mobyclient.Filters).Add("label", jobLabel+"job-1")
+	cli := &mockDockerClient{}
+	cli.On("ContainerList", ctx, mobyclient.ContainerListOptions{All: true, Filters: filters}).
+		Return(mobyclient.ContainerListResult{Items: []container.Summary{{ID: "c1", Names: []string{"/app"}}}}, nil).Once()
+	cli.On("ContainerKill", ctx, "c1", mock.Anything).Return(mobyclient.ContainerKillResult{}, nil).Once()
+	cli.On("ContainerRemove", ctx, "c1", mobyclient.ContainerRemoveOptions{RemoveVolumes: true, Force: true}).
+		Return(mobyclient.ContainerRemoveResult{}, containerFailure).Once()
+	cli.On("NetworkList", ctx, mobyclient.NetworkListOptions{Filters: filters}).
+		Return(mobyclient.NetworkListResult{Items: []network.Summary{{ID: "n1", Name: "stack_default", Scope: "swarm"}}}, listFailure).Once()
+	cli.On("NetworkRemove", ctx, "n1", mobyclient.NetworkRemoveOptions{}).Return(mobyclient.NetworkRemoveResult{}, cerrdefs.ErrInvalidArgument).Once()
+	cli.On("VolumeList", ctx, mobyclient.VolumeListOptions{Filters: filters}).
+		Return(mobyclient.VolumeListResult{Items: []volume.Volume{{Name: "app_data"}}}, nil).Once()
+	cli.On("VolumeRemove", ctx, "app_data", mobyclient.VolumeRemoveOptions{}).Return(mobyclient.VolumeRemoveResult{}, volumeFailure).Once()
+
+	err := removeLabelled(ctx, cli, "job-1")
+	require.ErrorIs(t, err, containerFailure)
+	require.ErrorIs(t, err, listFailure)
+	require.ErrorIs(t, err, volumeFailure)
+	require.NotErrorIs(t, err, cerrdefs.ErrInvalidArgument)
+	require.ErrorContains(t, err, "failed to remove container c1")
+	require.ErrorContains(t, err, "failed to remove volume app_data")
+	cli.AssertExpectations(t)
+}
+
+func TestDockerProxyWithDaemon(t *testing.T) {
+	requireDocker(t)
+	ctx := t.Context()
+	cleanupCtx := context.WithoutCancel(ctx)
+	require.NoError(t, NewDockerPullExecutor(NewDockerPullExecutorInput{Image: "alpine"})(ctx))
+	direct, err := GetDockerClient(ctx)
+	require.NoError(t, err)
+	defer direct.Close()
+	dir := shortTempDir(t)
+	seen, err := daemonSeesDir(ctx, direct, dir, dir)
+	require.NoError(t, err)
+	t.Logf("daemon sees the runner's filesystem: %v", seen)
+	seen, err = daemonSeesDir(ctx, direct, dir, shortTempDir(t))
+	require.NoError(t, err)
+	assert.False(t, seen)
+
+	job := "proxy-test-" + strconv.FormatInt(time.Now().UnixNano(), 36)
+	proxy, err := StartDockerProxy(daemonSocketPath(t, direct), dir, job)
+	if os.Geteuid() != 0 && errors.Is(err, os.ErrPermission) {
+		t.Skipf("non-root runners that cannot take the daemon socket's ownership get it directly: %v", err)
+	}
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = proxy.Close(context.Background()) })
+	viaProxy, err := mobyclient.New(mobyclient.WithHost("unix://" + proxy.Socket))
+	require.NoError(t, err)
+	defer viaProxy.Close()
+
+	created, err := viaProxy.ContainerCreate(ctx, mobyclient.ContainerCreateOptions{
+		Config: &container.Config{Image: "alpine", Cmd: []string{"sleep", "300"}, Labels: map[string]string{"own": "1"}},
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		_, _ = direct.ContainerRemove(cleanupCtx, created.ID, mobyclient.ContainerRemoveOptions{Force: true})
+	})
+	_, err = viaProxy.ContainerStart(ctx, created.ID, mobyclient.ContainerStartOptions{})
+	require.NoError(t, err)
+	net, err := viaProxy.NetworkCreate(ctx, job, mobyclient.NetworkCreateOptions{})
+	require.NoError(t, err)
+	t.Cleanup(func() { _, _ = direct.NetworkRemove(cleanupCtx, net.ID, mobyclient.NetworkRemoveOptions{}) })
+	_, err = viaProxy.VolumeCreate(ctx, mobyclient.VolumeCreateOptions{Name: job})
+	require.NoError(t, err)
+	t.Cleanup(func() { _, _ = direct.VolumeRemove(cleanupCtx, job, mobyclient.VolumeRemoveOptions{Force: true}) })
+
+	inspected, err := direct.ContainerInspect(ctx, created.ID, mobyclient.ContainerInspectOptions{})
+	require.NoError(t, err)
+	assert.Subset(t, inspected.Container.Config.Labels, map[string]string{"own": "1", jobLabel + job: ""})
+	vol, err := direct.VolumeInspect(ctx, job, mobyclient.VolumeInspectOptions{})
+	require.NoError(t, err)
+	assert.Contains(t, vol.Volume.Labels, jobLabel+job)
+
+	exec, err := viaProxy.ExecCreate(ctx, created.ID, mobyclient.ExecCreateOptions{Cmd: []string{"cat"}, AttachStdin: true, AttachStdout: true, TTY: true})
+	require.NoError(t, err)
+	attached, err := viaProxy.ExecAttach(ctx, exec.ID, mobyclient.ExecAttachOptions{TTY: true})
+	require.NoError(t, err)
+	_, err = attached.Conn.Write([]byte("hello\n"))
+	require.NoError(t, err)
+	echoed, err := attached.Reader.ReadString('\n')
+	require.NoError(t, err)
+	assert.Equal(t, "hello\r\n", echoed)
+	attached.Close()
+
+	require.NoError(t, proxy.Close(ctx))
+	require.NoError(t, RemoveDockerJobResources(ctx, job))
+	_, err = direct.ContainerInspect(ctx, created.ID, mobyclient.ContainerInspectOptions{})
+	assert.True(t, cerrdefs.IsNotFound(err))
+	_, err = direct.NetworkInspect(ctx, net.ID, mobyclient.NetworkInspectOptions{})
+	assert.True(t, cerrdefs.IsNotFound(err))
+	_, err = direct.VolumeInspect(ctx, job, mobyclient.VolumeInspectOptions{})
+	assert.True(t, cerrdefs.IsNotFound(err))
+}
+
+func BenchmarkDockerProxy(b *testing.B) {
+	ctx := context.Background()
+	direct, err := GetDockerClient(ctx)
+	require.NoError(b, err)
+	defer direct.Close()
+	if _, err := direct.Ping(ctx, mobyclient.PingOptions{}); err != nil {
+		b.Skipf("docker daemon unreachable: %v", err)
+	}
+	proxy, err := StartDockerProxy(daemonSocketPath(b, direct), shortTempDir(b), "bench")
+	require.NoError(b, err)
+	defer func() { _ = proxy.Close(ctx) }()
+	viaProxy, err := mobyclient.New(mobyclient.WithHost("unix://" + proxy.Socket))
+	require.NoError(b, err)
+	defer viaProxy.Close()
+
+	require.NoError(b, NewDockerPullExecutor(NewDockerPullExecutorInput{Image: "alpine"})(ctx))
+	created, err := direct.ContainerCreate(ctx, mobyclient.ContainerCreateOptions{Config: &container.Config{Image: "alpine", Cmd: []string{"sleep", "600"}}})
+	require.NoError(b, err)
+	defer func() { _, _ = direct.ContainerRemove(ctx, created.ID, mobyclient.ContainerRemoveOptions{Force: true}) }()
+	_, err = direct.ContainerStart(ctx, created.ID, mobyclient.ContainerStartOptions{})
+	require.NoError(b, err)
+
+	var archive bytes.Buffer
+	writer := tar.NewWriter(&archive)
+	payload := make([]byte, 64<<20)
+	require.NoError(b, writer.WriteHeader(&tar.Header{Name: "blob", Mode: 0o600, Size: int64(len(payload))}))
+	_, _ = writer.Write(payload)
+	require.NoError(b, writer.Close())
+
+	for name, cli := range map[string]mobyclient.APIClient{"direct": direct, "proxy": viaProxy} {
+		b.Run("ping/"+name, func(b *testing.B) {
+			for b.Loop() {
+				if _, err := cli.Ping(ctx, mobyclient.PingOptions{}); err != nil {
+					b.Fatal(err)
+				}
+			}
+		})
+		b.Run("copy64MiB/"+name, func(b *testing.B) {
+			b.SetBytes(int64(archive.Len()))
+			for b.Loop() {
+				_, err := cli.CopyToContainer(ctx, created.ID, mobyclient.CopyToContainerOptions{DestinationPath: "/tmp", Content: bytes.NewReader(archive.Bytes())})
+				if err != nil {
+					b.Fatal(err)
+				}
+			}
+		})
+	}
+}
+
+type probeClient struct {
+	mobyclient.APIClient
+	create     func(context.Context, mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error)
+	remove     func(context.Context, string, mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error)
+	stat       func(string) error
+	mounts     []container.MountPoint
+	containers []container.Summary
+}
+
+func (c *probeClient) Info(_ctx context.Context, _opts mobyclient.InfoOptions) (mobyclient.SystemInfoResult, error) {
+	return mobyclient.SystemInfoResult{}, nil
+}
+
+func (c *probeClient) Close() error {
+	return nil
+}
+
+func (c *probeClient) ContainerList(context.Context, mobyclient.ContainerListOptions) (mobyclient.ContainerListResult, error) {
+	return mobyclient.ContainerListResult{Items: c.containers}, nil
+}
+
+func (c *probeClient) ContainerKill(context.Context, string, mobyclient.ContainerKillOptions) (mobyclient.ContainerKillResult, error) {
+	return mobyclient.ContainerKillResult{}, cerrdefs.ErrConflict
+}
+
+func (c *probeClient) ContainerInspect(context.Context, string, mobyclient.ContainerInspectOptions) (mobyclient.ContainerInspectResult, error) {
+	return mobyclient.ContainerInspectResult{Container: container.InspectResponse{Mounts: c.mounts}}, nil
+}
+
+func (c *probeClient) ImageList(context.Context, mobyclient.ImageListOptions) (mobyclient.ImageListResult, error) {
+	return mobyclient.ImageListResult{Items: []image.Summary{{ID: "removed-image"}, {ID: "probe-image"}}}, nil
+}
+
+func (c *probeClient) ContainerCreate(ctx context.Context, opts mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error) {
+	return c.create(ctx, opts)
+}
+
+func (c *probeClient) ContainerRemove(ctx context.Context, id string, opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error) {
+	return c.remove(ctx, id, opts)
+}
+
+func (c *probeClient) ContainerStatPath(_ context.Context, _ string, opts mobyclient.ContainerStatPathOptions) (mobyclient.ContainerStatPathResult, error) {
+	return mobyclient.ContainerStatPathResult{}, c.stat(opts.Path)
+}
+
+func TestDockerProxyDirectoryProbes(t *testing.T) {
+	type result struct {
+		seen bool
+		err  error
+	}
+	for name, createErr := range map[string]error{"unavailable directory": nil, "daemon error": errors.New("probe failed")} {
+		t.Run(name, func(t *testing.T) {
+			synctest.Test(t, func(t *testing.T) {
+				dir := t.TempDir()
+				socket, err := os.Stat(t.TempDir())
+				require.NoError(t, err)
+				key := [3]string{"daemon", dir, dir}
+				release := make(chan struct{})
+				var calls, removals atomic.Int32
+				visible := false
+				cli := &probeClient{
+					create: func(_ctx context.Context, _opts mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error) {
+						calls.Add(1)
+						<-release
+						return mobyclient.ContainerCreateResult{ID: "probe"}, createErr
+					},
+					stat: func(_path string) error {
+						if visible {
+							return nil
+						} else {
+							return cerrdefs.ErrNotFound
+						}
+					},
+					remove: func(_ctx context.Context, _id string, _opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error) {
+						removals.Add(1)
+						return mobyclient.ContainerRemoveResult{}, nil
+					},
+				}
+				results := make(chan result, 8)
+				for range cap(results) {
+					go func() {
+						probe, err := probeDockerProxyDirectory(t.Context(), cli, key, socket)
+						results <- result{probe.seen, err}
+					}()
+				}
+				synctest.Wait()
+				assert.EqualValues(t, 1, calls.Load())
+				replacement, err := os.Stat(t.TempDir())
+				require.NoError(t, err)
+				replaced := make(chan result, 1)
+				go func() {
+					probe, err := probeDockerProxyDirectory(t.Context(), cli, key, replacement)
+					replaced <- result{probe.seen, err}
+				}()
+				synctest.Wait()
+				assert.EqualValues(t, 2, calls.Load())
+				close(release)
+				for range cap(results) {
+					result := <-results
+					require.ErrorIs(t, result.err, createErr)
+					assert.False(t, result.seen)
+				}
+				replacementResult := <-replaced
+				require.ErrorIs(t, replacementResult.err, createErr)
+				assert.False(t, replacementResult.seen)
+				assert.EqualValues(t, 2, calls.Load())
+				if createErr == nil {
+					assert.EqualValues(t, 2, removals.Load())
+				} else {
+					assert.Zero(t, removals.Load())
+				}
+				createErr, visible = nil, true
+				probe, err := probeDockerProxyDirectory(t.Context(), cli, key, socket)
+				require.NoError(t, err)
+				assert.True(t, probe.seen)
+				assert.Equal(t, dir, probe.directory.dir)
+				assert.Equal(t, dir, probe.directory.daemonDir)
+				assert.EqualValues(t, 3, calls.Load())
+				entries, err := os.ReadDir(dir)
+				require.NoError(t, err)
+				assert.Empty(t, entries)
+			})
+		})
+	}
+	t.Run("cancelled caller leaves the probe to finish for the others", func(t *testing.T) {
+		synctest.Test(t, func(t *testing.T) {
+			dir := t.TempDir()
+			socket, err := os.Stat(t.TempDir())
+			require.NoError(t, err)
+			key := [3]string{"daemon", dir, dir}
+			ctx, cancel := context.WithCancel(t.Context())
+			defer cancel()
+			release := make(chan struct{})
+			var calls, removals atomic.Int32
+			cli := &probeClient{
+				create: func(ctx context.Context, _opts mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error) {
+					calls.Add(1)
+					<-release
+					return mobyclient.ContainerCreateResult{ID: "probe"}, ctx.Err()
+				},
+				stat: func(_path string) error { return nil },
+				remove: func(_ctx context.Context, _id string, _opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error) {
+					removals.Add(1)
+					return mobyclient.ContainerRemoveResult{}, nil
+				},
+			}
+			leader, follower, late := make(chan result, 1), make(chan result, 1), make(chan result, 1)
+			go func() {
+				probe, err := probeDockerProxyDirectory(ctx, cli, key, socket)
+				leader <- result{probe.seen, err}
+			}()
+			synctest.Wait()
+			go func() {
+				probe, err := probeDockerProxyDirectory(t.Context(), cli, key, socket)
+				follower <- result{probe.seen, err}
+			}()
+			synctest.Wait()
+			cancel()
+			leaderResult := <-leader
+			require.ErrorIs(t, leaderResult.err, context.Canceled)
+			assert.False(t, leaderResult.seen)
+			go func() {
+				probe, err := probeDockerProxyDirectory(t.Context(), cli, key, socket)
+				late <- result{probe.seen, err}
+			}()
+			synctest.Wait()
+			close(release)
+			for _, results := range []chan result{follower, late} {
+				result := <-results
+				require.NoError(t, result.err)
+				assert.True(t, result.seen)
+			}
+			assert.EqualValues(t, 1, calls.Load())
+			assert.EqualValues(t, 1, removals.Load())
+			_, cached := dockerProxyProbes.Load(key)
+			assert.True(t, cached)
+		})
+	})
+	t.Run("caller joining a probe that ran out of time retries", func(t *testing.T) {
+		synctest.Test(t, func(t *testing.T) {
+			dir := t.TempDir()
+			socket, err := os.Stat(t.TempDir())
+			require.NoError(t, err)
+			var calls atomic.Int32
+			cli := &probeClient{
+				create: func(ctx context.Context, _opts mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error) {
+					if calls.Add(1) == 1 {
+						<-ctx.Done()
+						return mobyclient.ContainerCreateResult{}, ctx.Err()
+					}
+					return mobyclient.ContainerCreateResult{ID: "probe"}, nil
+				},
+				stat: func(_path string) error { return nil },
+				remove: func(_ctx context.Context, _id string, _opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error) {
+					return mobyclient.ContainerRemoveResult{}, nil
+				},
+			}
+			probe, err := probeDockerProxyDirectory(t.Context(), cli, [3]string{"daemon", dir, dir}, socket)
+			require.NoError(t, err)
+			assert.True(t, probe.seen)
+			assert.EqualValues(t, 2, calls.Load())
+		})
+	})
+}
+
+func TestRemoveStaleProbeContainers(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		probeMount := container.MountPoint{Type: mount.TypeBind, Destination: "/gitea-runner-probe"}
+		writableMount := container.MountPoint{Type: mount.TypeBind, Destination: "/gitea-runner-probe", RW: true}
+		var removed []string
+		cli := &probeClient{
+			containers: []container.Summary{
+				{ID: "abandoned", State: container.StateCreated, Mounts: []container.MountPoint{probeMount}},
+				{ID: "foreign", State: container.StateCreated, Mounts: []container.MountPoint{writableMount}},
+				{ID: "started", State: container.StateExited, Mounts: []container.MountPoint{probeMount}},
+			},
+			remove: func(_ctx context.Context, id string, _opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error) {
+				removed = append(removed, id)
+				return mobyclient.ContainerRemoveResult{}, nil
+			},
+		}
+		start := time.Now()
+		removeStaleProbeContainers(cli)
+		assert.Equal(t, []string{"abandoned"}, removed)
+		assert.GreaterOrEqual(t, time.Since(start), dockerProxyProbeWorkerTimeout+dockerProxyProbeTimeout)
+	})
+}
+
+func TestDaemonSeesDir(t *testing.T) {
+	dir := t.TempDir()
+	markers := make(map[string]bool)
+
+	for _, testCase := range []struct {
+		name      string
+		daemonDir string
+		removeErr error
+		seen      bool
+		removed   bool
+	}{
+		{name: "cleanup after cancellation", daemonDir: dir, seen: true, removed: true},
+		{name: "daemon without the directory", daemonDir: filepath.Join(dir, "missing")},
+		{name: "daemon with a different directory at that path", daemonDir: t.TempDir(), removed: true},
+		{name: "cleanup error after cancellation", daemonDir: dir, removeErr: errors.New("cleanup failed"), removed: true},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			ctx, cancel := context.WithCancel(t.Context())
+			defer cancel()
+			removed := false
+			var attemptedImages []string
+			cli := &probeClient{
+				create: func(_ctx context.Context, opts mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error) {
+					assert.Equal(t, []mount.Mount{{Type: mount.TypeBind, Source: testCase.daemonDir, Target: "/gitea-runner-probe", ReadOnly: true}}, opts.HostConfig.Mounts)
+					attemptedImages = append(attemptedImages, opts.Config.Image)
+					if opts.Config.Image == "removed-image" {
+						return mobyclient.ContainerCreateResult{}, cerrdefs.ErrNotFound
+					}
+					cancel()
+					if _, err := os.Stat(testCase.daemonDir); err != nil {
+						return mobyclient.ContainerCreateResult{}, cerrdefs.ErrInvalidArgument
+					}
+					return mobyclient.ContainerCreateResult{ID: "probe"}, nil
+				},
+				stat: func(path string) error {
+					marker := strings.TrimPrefix(path, "/gitea-runner-probe/")
+					assert.False(t, markers[marker])
+					markers[marker] = true
+					if _, err := os.Stat(filepath.Join(testCase.daemonDir, marker)); err != nil {
+						return cerrdefs.ErrNotFound
+					}
+					return nil
+				},
+				remove: func(ctx context.Context, id string, opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error) {
+					removed = true
+					assert.Equal(t, "probe", id)
+					assert.Equal(t, mobyclient.ContainerRemoveOptions{Force: true, RemoveVolumes: true}, opts)
+					require.NoError(t, ctx.Err())
+					_, bounded := ctx.Deadline()
+					assert.True(t, bounded)
+					return mobyclient.ContainerRemoveResult{}, testCase.removeErr
+				},
+			}
+			seen, err := daemonSeesDir(ctx, cli, dir, testCase.daemonDir)
+			require.ErrorIs(t, err, testCase.removeErr)
+			assert.Equal(t, []string{"removed-image", "probe-image"}, attemptedImages)
+			assert.Equal(t, testCase.seen, seen)
+			assert.Equal(t, testCase.removed, removed)
+
+			entries, err := os.ReadDir(dir)
+			require.NoError(t, err)
+			assert.Empty(t, entries)
+		})
+	}
+}
+
+func TestRunnerContainerWorkdir(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("a runner container is Linux")
+	}
+	workdir := t.TempDir()
+	t.Chdir(workdir)
+	volume := container.MountPoint{Type: mount.TypeVolume, Source: "/daemon/_data", Destination: filepath.Dir(workdir)}
+	for _, testCase := range []struct {
+		name      string
+		mount     container.MountPoint
+		foreign   bool
+		daemonDir string
+	}{
+		{name: "volume above the working directory", mount: volume, daemonDir: filepath.Join(volume.Source, filepath.Base(workdir))},
+		{name: "tmpfs", mount: container.MountPoint{Type: mount.TypeTmpfs, Destination: volume.Destination}},
+		{name: "hostname of another container", mount: volume, foreign: true},
+	} {
+		cli := &probeClient{
+			mounts: []container.MountPoint{testCase.mount},
+			stat: func(path string) error {
+				if _, err := os.Stat(path); err != nil || testCase.foreign {
+					return cerrdefs.ErrNotFound
+				}
+				return nil
+			},
+		}
+		dir, daemonDir := runnerContainerWorkdir(t.Context(), cli)
+		assert.Equal(t, testCase.daemonDir, daemonDir, testCase.name)
+		assert.Equal(t, testCase.daemonDir != "", dir == workdir, testCase.name)
+	}
+	entries, err := os.ReadDir(workdir)
+	require.NoError(t, err)
+	assert.Empty(t, entries)
+}

act/container/docker_proxy_unix.go

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

act/container/docker_proxy_windows.go

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

act/container/docker_pull.go

@@ -2,7 +2,7 @@
 // Copyright 2020 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 
@@ -114,7 +114,7 @@ func getImagePullOptions(ctx context.Context, input NewDockerPullExecutorInput)
 		if err != nil {
 			return imagePullOptions, err
 		}
-		if authConfig.Username == "" && authConfig.Password == "" {
+		if authConfig.Username == "" && authConfig.Password == "" && authConfig.IdentityToken == "" && authConfig.RegistryToken == "" {
 			return imagePullOptions, nil
 		}
 		logger.Info("using DockerAuthConfig authentication for docker pull")

act/container/docker_pull_test.go

@@ -5,20 +5,24 @@
 package container
 
 import (
-	"context"
 	"io"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
+	"testing/iotest"
 
-	"github.com/docker/cli/cli/config"
-	log "github.com/sirupsen/logrus"
-	"github.com/sirupsen/logrus/hooks/test"
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/act/common/logging/logtest"
+
+	"github.com/moby/moby/api/pkg/authconfig"
+	"github.com/moby/moby/api/types/registry"
 	assert "github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 func init() {
-	log.SetLevel(log.DebugLevel)
+	logging.SetLevel(logging.LevelDebug)
 }
 
 func TestCleanImage(t *testing.T) {
@@ -36,18 +40,15 @@ func TestCleanImage(t *testing.T) {
 	}
 
 	for _, table := range tables {
-		imageOut := cleanImage(context.Background(), table.imageIn)
+		imageOut := cleanImage(t.Context(), table.imageIn)
 		assert.Equal(t, table.imageOut, imageOut)
 	}
 }
 
 func TestGetImagePullOptions(t *testing.T) {
-	ctx := context.Background()
+	ctx := t.Context()
 
-	orig := config.Dir()
-	t.Cleanup(func() { config.SetDir(orig) })
-
-	config.SetDir("/non-existent/docker")
+	t.Setenv("DOCKER_CONFIG", "/non-existent/docker")
 
 	options, err := getImagePullOptions(ctx, NewDockerPullExecutorInput{})
 	assert.NoError(t, err, "Failed to create ImagePullOptions")                                                 //nolint:testifylint // pre-existing issue from nektos/act
@@ -61,13 +62,28 @@ func TestGetImagePullOptions(t *testing.T) {
 	assert.NoError(t, err, "Failed to create ImagePullOptions") //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, "eyJ1c2VybmFtZSI6InVzZXJuYW1lIiwicGFzc3dvcmQiOiJwYXNzd29yZCJ9", options.RegistryAuth, "Username and Password should be provided")
 
-	config.SetDir("testdata/docker-pull-options")
+	t.Setenv("DOCKER_CONFIG", "testdata/docker-pull-options")
 
 	options, err = getImagePullOptions(ctx, NewDockerPullExecutorInput{
 		Image: "nektos/act",
 	})
 	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")
+
+	dir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "config.json"), []byte(`{"auths":{"identity.example.com":{"identitytoken":"identity-token"},"registry.example.com":{"registrytoken":"registry-token"}}}`), 0o600))
+	t.Setenv("DOCKER_CONFIG", dir)
+	for host, want := range map[string]registry.AuthConfig{
+		"identity.example.com": {IdentityToken: "identity-token", ServerAddress: "identity.example.com"},
+		"registry.example.com": {RegistryToken: "registry-token", ServerAddress: "registry.example.com"},
+	} {
+		options, err := getImagePullOptions(ctx, NewDockerPullExecutorInput{Image: host + "/app"})
+		require.NoError(t, err)
+		require.NotEmpty(t, options.RegistryAuth, host)
+		got, err := authconfig.Decode(options.RegistryAuth)
+		require.NoError(t, err)
+		assert.Equal(t, want, *got)
+	}
 }
 
 // A digest-pinned image is immutable, so its local copy is always current.
@@ -79,11 +95,15 @@ func TestIsPinnedImage(t *testing.T) {
 // 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()
+	logger := logging.New(logtest.New())
 	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"}`))
+	require.NoError(t, streamErr(`{"stream":"`+strings.Repeat("x", 70000)+`"}`))
+	require.ErrorIs(t, logDockerResponse(logger, io.NopCloser(io.MultiReader(
+		strings.NewReader(`{"status":"Downloading"}`+"\n"), iotest.ErrReader(io.ErrUnexpectedEOF),
+	)), false), io.ErrUnexpectedEOF)
 }

act/container/docker_socket.go

@@ -1,138 +0,0 @@
-// Copyright 2024 The Gitea Authors. All rights reserved.
-// Copyright 2024 The nektos/act Authors. All rights reserved.
-// SPDX-License-Identifier: MIT
-
-package container
-
-import (
-	"fmt"
-	"os"
-	"path/filepath"
-	"strings"
-
-	log "github.com/sirupsen/logrus"
-)
-
-var CommonSocketLocations = []string{
-	"/var/run/docker.sock",
-	"/run/podman/podman.sock",
-	"$HOME/.colima/docker.sock",
-	"$XDG_RUNTIME_DIR/docker.sock",
-	"$XDG_RUNTIME_DIR/podman/podman.sock",
-	`\\.\pipe\docker_engine`,
-	"$HOME/.docker/run/docker.sock",
-}
-
-// returns socket URI or false if not found any
-func socketLocation() (string, bool) {
-	if dockerHost, exists := os.LookupEnv("DOCKER_HOST"); exists {
-		return dockerHost, true
-	}
-
-	for _, p := range CommonSocketLocations {
-		if _, err := os.Lstat(os.ExpandEnv(p)); err == nil {
-			if strings.HasPrefix(p, `\\.\`) {
-				return "npipe://" + filepath.ToSlash(os.ExpandEnv(p)), true
-			}
-			return "unix://" + filepath.ToSlash(os.ExpandEnv(p)), true
-		}
-	}
-
-	return "", false
-}
-
-// This function, `isDockerHostURI`, takes a string argument `daemonPath`. It checks if the
-// `daemonPath` is a valid Docker host URI. It does this by checking if the scheme of the URI (the
-// part before "://") contains only alphabetic characters. If it does, the function returns true,
-// indicating that the `daemonPath` is a Docker host URI. If it doesn't, or if the "://" delimiter
-// is not found in the `daemonPath`, the function returns false.
-func isDockerHostURI(daemonPath string) bool {
-	if before, _, ok := strings.Cut(daemonPath, "://"); ok {
-		scheme := before
-		if strings.IndexFunc(scheme, func(r rune) bool {
-			return (r < 'a' || r > 'z') && (r < 'A' || r > 'Z')
-		}) == -1 {
-			return true
-		}
-	}
-	return false
-}
-
-type SocketAndHost struct {
-	Socket string
-	Host   string
-}
-
-func GetSocketAndHost(containerSocket string) (SocketAndHost, error) {
-	log.Debugf("Handling container host and socket")
-
-	// Prefer DOCKER_HOST, don't override it
-	dockerHost, hasDockerHost := socketLocation()
-	socketHost := SocketAndHost{Socket: containerSocket, Host: dockerHost}
-
-	// ** socketHost.Socket cases **
-	// Case 1: User does _not_ want to mount a daemon socket (passes a dash)
-	// Case 2: User passes a filepath to the socket; is that even valid?
-	// Case 3: User passes a valid socket; do nothing
-	// Case 4: User omitted the flag; set a sane default
-
-	// ** DOCKER_HOST cases **
-	// Case A: DOCKER_HOST is set; use it, i.e. do nothing
-	// Case B: DOCKER_HOST is empty; use sane defaults
-
-	// Set host for sanity's sake, when the socket isn't useful
-	if !hasDockerHost && (socketHost.Socket == "-" || !isDockerHostURI(socketHost.Socket) || socketHost.Socket == "") {
-		// Cases: 1B, 2B, 4B
-		socket, found := socketLocation()
-		socketHost.Host = socket
-		hasDockerHost = found
-	}
-
-	// A - (dash) in socketHost.Socket means don't mount, preserve this value
-	// otherwise if socketHost.Socket is a filepath don't use it as socket
-	// Exit early if we're in an invalid state (e.g. when no DOCKER_HOST and user supplied "-", a dash or omitted)
-	if !hasDockerHost && socketHost.Socket != "" && !isDockerHostURI(socketHost.Socket) {
-		// Cases: 1B, 2B
-		// Should we early-exit here, since there is no host nor socket to talk to?
-		return SocketAndHost{}, fmt.Errorf("DOCKER_HOST was not set, couldn't be found in the usual locations, and the container daemon socket ('%s') is invalid", socketHost.Socket)
-	}
-
-	// Default to DOCKER_HOST if set
-	if socketHost.Socket == "" && hasDockerHost {
-		// Cases: 4A
-		log.Debugf("Defaulting container socket to DOCKER_HOST")
-		socketHost.Socket = socketHost.Host
-	}
-	// Set sane default socket location if user omitted it
-	if socketHost.Socket == "" {
-		// Cases: 4B
-		socket, _ := socketLocation()
-		// socket is empty if it isn't found, so assignment here is at worst a no-op
-		log.Debugf("Defaulting container socket to default '%s'", socket)
-		socketHost.Socket = socket
-	}
-
-	// Exit if both the DOCKER_HOST and socket are fulfilled
-	if hasDockerHost {
-		// Cases: 1A, 2A, 3A, 4A
-		if !isDockerHostURI(socketHost.Socket) {
-			// Cases: 1A, 2A
-			log.Debugf("DOCKER_HOST is set, but socket is invalid '%s'", socketHost.Socket)
-		}
-		return socketHost, nil
-	}
-
-	// Set a sane DOCKER_HOST default if we can
-	if isDockerHostURI(socketHost.Socket) {
-		// Cases: 3B
-		log.Debugf("Setting DOCKER_HOST to container socket '%s'", socketHost.Socket)
-		socketHost.Host = socketHost.Socket
-		// Both DOCKER_HOST and container socket are valid; short-circuit exit
-		return socketHost, nil
-	}
-
-	// Here there is no DOCKER_HOST _and_ the supplied container socket is not a valid URI (either invalid or a file path)
-	// Cases: 2B <- but is already handled at the top
-	// I.e. this path should never be taken
-	return SocketAndHost{}, fmt.Errorf("no DOCKER_HOST and an invalid container socket '%s'", socketHost.Socket)
-}

act/container/docker_socket_test.go

@@ -1,167 +0,0 @@
-// Copyright 2024 The Gitea Authors. All rights reserved.
-// Copyright 2024 The nektos/act Authors. All rights reserved.
-// SPDX-License-Identifier: MIT
-
-package container
-
-import (
-	"os"
-	"testing"
-
-	log "github.com/sirupsen/logrus"
-	assert "github.com/stretchr/testify/assert"
-)
-
-func init() {
-	log.SetLevel(log.DebugLevel)
-}
-
-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
-	isolateSocketEnv(t)
-	dockerHost := "unix:///my/docker/host.sock"
-	socketURI := "/path/to/my.socket"
-	t.Setenv("DOCKER_HOST", dockerHost)
-
-	// Act
-	ret, err := GetSocketAndHost(socketURI)
-
-	// Assert
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, SocketAndHost{socketURI, dockerHost}, ret)
-}
-
-func TestGetSocketAndHostNoSocket(t *testing.T) {
-	// Arrange
-	dockerHost := "unix:///my/docker/host.sock"
-	t.Setenv("DOCKER_HOST", dockerHost)
-
-	// Act
-	ret, err := GetSocketAndHost("")
-
-	// Assert
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, SocketAndHost{dockerHost, dockerHost}, ret)
-}
-
-func TestGetSocketAndHostOnlySocket(t *testing.T) {
-	// Arrange
-	isolateSocketEnv(t)
-	socketURI := "/path/to/my.socket"
-	os.Unsetenv("DOCKER_HOST")
-	defaultSocket, defaultSocketFound := socketLocation()
-
-	// Act
-	ret, err := GetSocketAndHost(socketURI)
-
-	// Assert
-	assert.NoError(t, err, "Expected no error from GetSocketAndHost") //nolint:testifylint // pre-existing issue from nektos/act
-	assert.True(t, defaultSocketFound, "Expected to find default socket")
-	assert.Equal(t, socketURI, ret.Socket, "Expected socket to match common location")
-	assert.Equal(t, defaultSocket, ret.Host, "Expected ret.Host to match default socket location")
-}
-
-func TestGetSocketAndHostDontMount(t *testing.T) {
-	// Arrange
-	isolateSocketEnv(t)
-	dockerHost := "unix:///my/docker/host.sock"
-	t.Setenv("DOCKER_HOST", dockerHost)
-
-	// Act
-	ret, err := GetSocketAndHost("-")
-
-	// Assert
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, SocketAndHost{"-", dockerHost}, ret)
-}
-
-func TestGetSocketAndHostNoHostNoSocket(t *testing.T) {
-	// Arrange
-	isolateSocketEnv(t)
-	os.Unsetenv("DOCKER_HOST")
-	defaultSocket, found := socketLocation()
-
-	// Act
-	ret, err := GetSocketAndHost("")
-
-	// Assert
-	assert.True(t, found, "Expected a default socket to be found")
-	assert.NoError(t, err, "Expected no error from GetSocketAndHost") //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, SocketAndHost{defaultSocket, defaultSocket}, ret, "Expected to match default socket location")
-}
-
-// Catch
-// > Your code breaks setting DOCKER_HOST if shouldMount is false.
-// > 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
-	defer os.RemoveAll(mySocket)
-	assert.NoError(t, tmpErr) //nolint:testifylint // pre-existing issue from nektos/act
-	os.Unsetenv("DOCKER_HOST")
-
-	CommonSocketLocations = []string{mySocket}
-	defaultSocket, found := socketLocation()
-
-	// Act
-	ret, err := GetSocketAndHost("")
-
-	// Assert
-	assert.Equal(t, unixSocket, defaultSocket, "Expected default socket to match common socket location")
-	assert.True(t, found, "Expected default socket to be found")
-	assert.NoError(t, err, "Expected no error from GetSocketAndHost") //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, SocketAndHost{unixSocket, unixSocket}, ret, "Expected to match default socket location")
-}
-
-func TestGetSocketAndHostNoHostInvalidSocket(t *testing.T) {
-	// Arrange
-	isolateSocketEnv(t)
-	os.Unsetenv("DOCKER_HOST")
-	mySocket := "/my/socket/path.sock"
-	CommonSocketLocations = []string{"/unusual", "/socket", "/location"}
-	defaultSocket, found := socketLocation()
-
-	// Act
-	ret, err := GetSocketAndHost(mySocket)
-
-	// Assert
-	assert.False(t, found, "Expected no default socket to be found")
-	assert.Equal(t, "", defaultSocket, "Expected no default socket to be found") //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, SocketAndHost{}, ret, "Expected to match default socket location")
-	assert.Error(t, err, "Expected an error in invalid state")
-}
-
-func TestGetSocketAndHostOnlySocketValidButUnusualLocation(t *testing.T) {
-	// Arrange
-	isolateSocketEnv(t)
-	socketURI := "unix:///path/to/my.socket"
-	CommonSocketLocations = []string{"/unusual", "/location"}
-	os.Unsetenv("DOCKER_HOST")
-	defaultSocket, found := socketLocation()
-
-	// Act
-	ret, err := GetSocketAndHost(socketURI)
-
-	// Assert
-	// Default socket locations
-	assert.Equal(t, "", defaultSocket, "Expect default socket location to be empty") //nolint:testifylint // pre-existing issue from nektos/act
-	assert.False(t, found, "Expected no default socket to be found")
-	// Sane default
-	assert.NoError(t, err, "Expect no error from GetSocketAndHost") //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(t, socketURI, ret.Host, "Expect host to default to unusual socket")
-}

act/container/docker_ssh.go

@@ -0,0 +1,111 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
+
+package container
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"os/exec"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	"github.com/docker/cli/cli/connhelper/ssh"
+)
+
+func sshArgs(daemonURL string) ([]string, error) {
+	spec, err := ssh.ParseURL(daemonURL)
+	if err != nil {
+		return nil, err
+	}
+	remote := []string{"docker", "system", "dial-stdio"}
+	if strings.Trim(spec.Path, "/") != "" {
+		remote = []string{"docker", "--host=unix://" + spec.Path, "system", "dial-stdio"}
+	}
+	return spec.Command([]string{"-o", "ConnectTimeout=30", "-T"}, remote...)
+}
+
+func dialCommand(name string, args ...string) (net.Conn, error) {
+	conn := &commandConn{cmd: exec.Command(name, args...)}
+	conn.cmd.SysProcAttr = sshSysProcAttr() // a session of its own like docker's, so a ProxyCommand never reads the runner's terminal: https://github.com/docker/cli/issues/1707
+	conn.cmd.Stderr = &conn.stderr
+	conn.cmd.WaitDelay = time.Second // a ProxyCommand child keeping stderr open would otherwise block Wait after ssh exits
+	conn.wait = sync.OnceValue(func() error {
+		if err := conn.cmd.Wait(); err != nil && !errors.Is(err, exec.ErrWaitDelay) {
+			return fmt.Errorf("%s: %w: %s", strings.Join(conn.cmd.Args, " "), err, strings.TrimSpace(conn.stderr.String()))
+		}
+		return nil
+	})
+	var err error
+	if conn.stdin, err = conn.cmd.StdinPipe(); err != nil {
+		return nil, err
+	}
+	if conn.stdout, err = conn.cmd.StdoutPipe(); err != nil {
+		return nil, err
+	}
+	return conn, conn.cmd.Start()
+}
+
+type commandConn struct {
+	cmd    *exec.Cmd
+	stdin  io.WriteCloser
+	stdout io.ReadCloser
+	stderr cappedBuffer
+	wait   func() error
+}
+
+func (c *commandConn) waitWithin(timeout time.Duration) error {
+	timer := time.AfterFunc(timeout, func() { _ = c.cmd.Process.Kill() })
+	defer timer.Stop()
+	return c.wait()
+}
+
+func (c *commandConn) Read(p []byte) (int, error) {
+	n, err := c.stdout.Read(p)
+	if errors.Is(err, io.EOF) {
+		if waitErr := c.waitWithin(10 * time.Second); waitErr != nil {
+			return n, waitErr
+		}
+	}
+	return n, err
+}
+
+func (c *commandConn) Write(p []byte) (int, error) { return c.stdin.Write(p) }
+
+// CloseWrite lets the daemon see the end of a hijacked stream, like a TCP half-close.
+func (c *commandConn) CloseWrite() error { return c.stdin.Close() }
+
+func (c *commandConn) Close() error {
+	_ = c.stdin.Close()
+	if c.cmd.Process.Signal(syscall.SIGTERM) != nil { // SIGTERM lets ssh take its ProxyCommand down, Windows only kills
+		_ = c.cmd.Process.Kill()
+	}
+	_ = c.waitWithin(3 * time.Second)
+	return nil
+}
+
+func (c *commandConn) LocalAddr() net.Addr { return &net.UnixAddr{Name: "stdio", Net: "unix"} }
+
+func (c *commandConn) RemoteAddr() net.Addr { return &net.UnixAddr{Name: "stdio", Net: "unix"} }
+
+func (c *commandConn) SetDeadline(_deadline time.Time) error { return nil }
+
+func (c *commandConn) SetReadDeadline(_deadline time.Time) error { return nil }
+
+func (c *commandConn) SetWriteDeadline(_deadline time.Time) error { return nil }
+
+type cappedBuffer struct{ bytes.Buffer }
+
+func (b *cappedBuffer) Write(p []byte) (int, error) {
+	if b.Len() > 4096 {
+		b.Reset()
+	}
+	return b.Buffer.Write(p)
+}

act/container/docker_ssh_linux.go

@@ -0,0 +1,12 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !WITHOUT_DOCKER
+
+package container
+
+import "syscall"
+
+func sshSysProcAttr() *syscall.SysProcAttr {
+	return &syscall.SysProcAttr{Setsid: true, Pdeathsig: syscall.SIGKILL}
+}

act/container/docker_ssh_test.go

@@ -0,0 +1,52 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
+
+package container
+
+import (
+	"io"
+	"os/exec"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSSHArgs(t *testing.T) {
+	args, err := sshArgs("ssh://me@host:2222/run/user/1000/my docker.sock")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"-l", "me", "-p", "2222", "-o", "ConnectTimeout=30", "-T", "--", "host", "docker '--host=unix:///run/user/1000/my docker.sock' system dial-stdio"}, args)
+
+	args, err = sshArgs("ssh://[::1]")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"-o", "ConnectTimeout=30", "-T", "--", "::1", "docker system dial-stdio"}, args)
+
+	for _, invalid := range []string{"ssh://me:secret@host", "ssh://host?x=1", "ssh://host#x", "ssh://"} {
+		_, err := sshArgs(invalid)
+		assert.Error(t, err, invalid)
+	}
+}
+
+func TestDialCommandStreamsStdioAndReportsExit(t *testing.T) {
+	t.Parallel()
+	if _, err := exec.LookPath("sh"); err != nil {
+		t.Skip("needs a POSIX shell")
+	}
+	conn, err := dialCommand("sh", "-c", "cat")
+	require.NoError(t, err)
+	_, err = conn.Write([]byte("ping"))
+	require.NoError(t, err)
+	require.NoError(t, conn.(interface{ CloseWrite() error }).CloseWrite())
+	echoed, err := io.ReadAll(conn)
+	require.NoError(t, err)
+	assert.Equal(t, "ping", string(echoed))
+	require.NoError(t, conn.Close())
+
+	conn, err = dialCommand("sh", "-c", "exec 3<&0; cat <&3 >/dev/null & echo 'no route to host' >&2; exit 255")
+	require.NoError(t, err)
+	_, err = io.ReadAll(conn)
+	require.ErrorContains(t, err, "no route to host")
+	require.NoError(t, conn.Close())
+}

act/container/docker_ssh_unix.go

@@ -0,0 +1,12 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !WITHOUT_DOCKER && (darwin || netbsd || freebsd)
+
+package container
+
+import "syscall"
+
+func sshSysProcAttr() *syscall.SysProcAttr {
+	return &syscall.SysProcAttr{Setsid: true}
+}

act/container/docker_ssh_windows.go

@@ -0,0 +1,10 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !WITHOUT_DOCKER
+
+package container
+
+import "syscall"
+
+func sshSysProcAttr() *syscall.SysProcAttr { return nil }

act/container/docker_stub.go

@@ -2,13 +2,14 @@
 // Copyright 2023 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build WITHOUT_DOCKER || !(linux || darwin || windows || netbsd)
+//go:build WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd)
 
 package container
 
 import (
 	"context"
 	"errors"
+	"net/netip"
 	"runtime"
 	"time"
 
@@ -17,6 +18,10 @@ import (
 	"github.com/moby/moby/api/types/system"
 )
 
+func IsolatedCacheContainer(context.Context, netip.Addr, string) (string, error) {
+	return "", nil
+}
+
 // ImageExistsLocally returns a boolean indicating if an image with the
 // requested name, tag and architecture exists in the local docker image store
 func ImageExistsLocally(ctx context.Context, imageName, platform string) (bool, error) {
@@ -29,6 +34,18 @@ func RemoveImage(ctx context.Context, imageName string, force, pruneChildren boo
 	return false, errors.New("Unsupported Operation")
 }
 
+func RemoveDockerJobResources(_ context.Context, _ string) error {
+	return nil
+}
+
+func NewDockerProxy(_ context.Context, _ string) *DockerProxy {
+	return nil
+}
+
+func StartDockerProxy(daemonSocket, dir, job string) (*DockerProxy, error) {
+	return nil, errors.New("Unsupported Operation")
+}
+
 // NewDockerBuildExecutor function to create a run executor for the container
 func NewDockerBuildExecutor(input NewDockerBuildExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
@@ -74,6 +91,30 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 	}
 }
 
-func RemoveOrphanNetworks(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
+func NewDockerNetworkConnectExecutor(_, _ string) common.Executor {
+	return func(_ context.Context) error {
+		return nil
+	}
+}
+
+func NewDockerNetworkDisconnectExecutor(_, _ string) common.Executor {
+	return func(_ context.Context) error {
+		return nil
+	}
+}
+
+func RemoveOrphanNetworks(_ context.Context, _, _ string, _ time.Time) error {
+	return nil
+}
+
+func SanitizeBinds(_ context.Context, _, binds []string) []string {
+	return binds
+}
+
+func CreateJobVolumes(ctx context.Context, runnerUUID string, volumeNames []string) error {
+	return nil
+}
+
+func RemoveOrphanJobVolumes(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
 	return nil
 }

act/container/docker_volume.go

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

act/container/executions_environment.go

@@ -4,7 +4,18 @@
 
 package container
 
-import "context"
+import (
+	"context"
+	"path"
+	"strings"
+)
+
+func JoinPath(elem ...string) string { // path.Join would collapse the leading // of a UNC act path on a Windows host
+	if len(elem) > 0 && strings.HasPrefix(elem[0], "//") {
+		return "/" + path.Join(elem...)
+	}
+	return path.Join(elem...)
+}
 
 type ExecutionsEnvironment interface {
 	Container

act/container/helpers_test.go

@@ -4,7 +4,6 @@
 package container
 
 import (
-	"context"
 	"testing"
 
 	mobyclient "github.com/moby/moby/client"
@@ -15,7 +14,7 @@ import (
 // so the daemon has to be pinged explicitly here to decide whether to skip.
 func requireDocker(t *testing.T) {
 	t.Helper()
-	ctx := context.Background()
+	ctx := t.Context()
 	cli, err := GetDockerClient(ctx)
 	if err != nil {
 		t.Skipf("skipping: docker client unavailable: %v", err)

act/container/host_environment.go

@@ -7,6 +7,7 @@ package container
 import (
 	"archive/tar"
 	"bytes"
+	"cmp"
 	"context"
 	"errors"
 	"fmt"
@@ -26,9 +27,7 @@ import (
 	"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"
-	"github.com/go-git/go-git/v5/plumbing/format/gitignore"
+	"github.com/creack/pty"
 	"golang.org/x/term"
 )
 
@@ -41,7 +40,8 @@ type HostEnvironment struct {
 	// when Workdir points at a caller-owned checkout (e.g. `act` local mode).
 	CleanWorkdir bool
 	ActPath      string
-	CleanUp      func()
+	Root         string
+	TrackingID   string // RUNNER_TRACKING_ID of the job, a step with another value keeps its leftovers
 	StdOut       io.Writer
 	AllocatePTY  bool // allocate a pseudo-TTY for each step's process
 
@@ -66,21 +66,11 @@ func (e *HostEnvironment) processGroup(ctx context.Context) *process.Group {
 }
 
 func (e *HostEnvironment) Create(_, _ []string) common.Executor {
-	return func(ctx context.Context) error {
-		return nil
-	}
-}
-
-func (e *HostEnvironment) ConnectToNetwork(name string) common.Executor {
-	return func(ctx context.Context) error {
-		return nil
-	}
+	return common.NewPipelineExecutor()
 }
 
 func (e *HostEnvironment) Close() common.Executor {
-	return func(ctx context.Context) error {
-		return nil
-	}
+	return common.NewPipelineExecutor()
 }
 
 func (e *HostEnvironment) Copy(destPath string, files ...*FileEntry) common.Executor {
@@ -97,34 +87,7 @@ func (e *HostEnvironment) Copy(destPath string, files ...*FileEntry) common.Exec
 	}
 }
 
-func (e *HostEnvironment) CopyTarStream(ctx context.Context, destPath string, tarStream io.Reader) error {
-	if err := os.RemoveAll(destPath); err != nil {
-		return err
-	}
-	tr := tar.NewReader(tarStream)
-	cp := &filecollector.CopyCollector{
-		DstDir: destPath,
-	}
-	for {
-		ti, err := tr.Next()
-		if errors.Is(err, io.EOF) {
-			return nil
-		} else if err != nil {
-			return err
-		}
-		if ti.FileInfo().IsDir() {
-			continue
-		}
-		if ctx.Err() != nil {
-			return errors.New("CopyTarStream has been cancelled")
-		}
-		if err := cp.WriteFile(ti.Name, ti.FileInfo(), ti.Linkname, tr); err != nil {
-			return err
-		}
-	}
-}
-
-func (e *HostEnvironment) CopyDir(destPath, srcPath string, useGitIgnore bool) common.Executor {
+func (e *HostEnvironment) CopyDir(destPath, srcPath string, useGitIgnore, skipGitDir bool) common.Executor {
 	return func(ctx context.Context) error {
 		logger := common.Logger(ctx)
 		srcPrefix := filepath.Dir(srcPath)
@@ -132,28 +95,27 @@ func (e *HostEnvironment) CopyDir(destPath, srcPath string, useGitIgnore bool) c
 			srcPrefix += string(filepath.Separator)
 		}
 		logger.Debugf("Stripping prefix:%s src:%s", srcPrefix, srcPath)
-		var ignorer gitignore.Matcher
-		if useGitIgnore {
-			ps, err := gitignore.ReadPatterns(polyfill.New(osfs.New(srcPath)), nil)
-			if err != nil {
-				logger.Debugf("Error loading .gitignore: %v", err)
-			}
-
-			ignorer = gitignore.NewMatcher(ps)
-		}
 		fc := &filecollector.FileCollector{
-			Fs:        &filecollector.DefaultFs{},
-			Ignorer:   ignorer,
-			SrcPath:   srcPath,
-			SrcPrefix: srcPrefix,
+			SrcPath:      srcPath,
+			SrcPrefix:    srcPrefix,
+			SkipGitDir:   skipGitDir,
+			UseGitIgnore: useGitIgnore,
 			Handler: &filecollector.CopyCollector{
 				DstDir: destPath,
 			},
 		}
-		return filepath.Walk(srcPath, fc.CollectFiles(ctx, []string{}))
+		return filepath.Walk(srcPath, fc.CollectFiles(ctx))
 	}
 }
 
+func (e *HostEnvironment) DumpLogs(_ context.Context) error {
+	return nil
+}
+
+func (e *HostEnvironment) Inspect(_ context.Context) (*Info, error) {
+	return &Info{Health: HealthNone, Ports: map[string]string{}}, nil
+}
+
 func (e *HostEnvironment) GetContainerArchive(ctx context.Context, srcPath string) (io.ReadCloser, error) {
 	buf := &bytes.Buffer{}
 	tw := tar.NewWriter(buf)
@@ -172,12 +134,11 @@ func (e *HostEnvironment) GetContainerArchive(ctx context.Context, srcPath strin
 			srcPrefix += string(filepath.Separator)
 		}
 		fc := &filecollector.FileCollector{
-			Fs:        &filecollector.DefaultFs{},
 			SrcPath:   srcPath,
 			SrcPrefix: srcPrefix,
 			Handler:   tc,
 		}
-		err = filepath.Walk(srcPath, fc.CollectFiles(ctx, []string{}))
+		err = filepath.Walk(srcPath, fc.CollectFiles(ctx))
 		if err != nil {
 			return nil, err
 		}
@@ -205,15 +166,11 @@ func (e *HostEnvironment) GetContainerArchive(ctx context.Context, srcPath strin
 }
 
 func (e *HostEnvironment) Pull(_ bool) common.Executor {
-	return func(ctx context.Context) error {
-		return nil
-	}
+	return common.NewPipelineExecutor()
 }
 
 func (e *HostEnvironment) Start(_ bool) common.Executor {
-	return func(ctx context.Context) error {
-		return nil
-	}
+	return common.NewPipelineExecutor()
 }
 
 type ptyWriter struct {
@@ -230,7 +187,6 @@ func (w *ptyWriter) Write(buf []byte) (int, error) {
 		}
 		if w.dirtyLine || len(buf) > 1 && buf[len(buf)-2] != '\n' {
 			_, _ = w.Out.Write([]byte("\n"))
-			return n, io.EOF
 		}
 		return n, io.EOF
 	}
@@ -238,24 +194,8 @@ func (w *ptyWriter) Write(buf []byte) (int, error) {
 	return w.Out.Write(buf)
 }
 
-type localEnv struct {
-	env map[string]string
-}
-
-func (l *localEnv) Getenv(name string) string {
-	if runtime.GOOS == "windows" {
-		for k, v := range l.env {
-			if strings.EqualFold(name, k) {
-				return v
-			}
-		}
-		return ""
-	}
-	return l.env[name]
-}
-
 func lookupPathHost(cmd string, env map[string]string, writer io.Writer) (string, error) {
-	f, err := lookpath.LookPath2(cmd, &localEnv{env: env})
+	f, err := lookpath.LookPath2(cmd, env)
 	if err != nil {
 		err := "Cannot find: " + cmd + " in PATH"
 		if _, _err := writer.Write([]byte(err + "\n")); _err != nil {
@@ -267,7 +207,7 @@ func lookupPathHost(cmd string, env map[string]string, writer io.Writer) (string
 }
 
 func setupPty(cmd *exec.Cmd, cmdline string) (*os.File, *os.File, error) {
-	ppty, tty, err := openPty()
+	ppty, tty, err := pty.Open()
 	if err != nil {
 		return nil, nil, err
 	}
@@ -286,53 +226,43 @@ func setupPty(cmd *exec.Cmd, cmdline string) (*os.File, *os.File, error) {
 	return ppty, tty, nil
 }
 
-func writeKeepAlive(ppty io.Writer) {
-	c := 1
-	var err error
-	for c == 1 && err == nil {
-		c, err = ppty.Write([]byte{4})
-		<-time.After(time.Second)
-	}
-}
-
-func copyPtyOutput(writer io.Writer, ppty io.Reader, finishLog context.CancelFunc) {
-	defer func() {
-		finishLog()
-	}()
-	if _, err := io.Copy(writer, ppty); err != nil {
-		return
+func writeKeepAlive(ctx context.Context, ppty io.Writer) {
+	for ctx.Err() == nil {
+		if count, err := ppty.Write([]byte{4}); count != 1 || err != nil {
+			return
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(time.Second):
+		}
 	}
 }
 
 func (e *HostEnvironment) UpdateFromImageEnv(_ *map[string]string) common.Executor {
-	return func(ctx context.Context) error {
-		return nil
-	}
+	return common.NewPipelineExecutor()
 }
 
 func getEnvListFromMap(env map[string]string) []string {
-	envList := make([]string, 0)
-	for k, v := range env {
-		envList = append(envList, fmt.Sprintf("%s=%s", k, v))
+	envList := make([]string, 0, len(env))
+	for key, value := range env {
+		envList = append(envList, key+"="+value)
 	}
 	return envList
 }
 
-func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline string, env map[string]string, _, workdir string) error {
-	envList := getEnvListFromMap(env)
-	var wd string
+func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline string, env map[string]string, workdir string) error {
+	wd := e.Path
 	if workdir != "" {
-		if filepath.IsAbs(workdir) {
-			wd = workdir
-		} else {
+		wd = workdir
+		if !filepath.IsAbs(workdir) {
 			wd = filepath.Join(e.Path, workdir)
 		}
-	} 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)
+	process.UTF8Console()
 
 	f, err := lookupPathHost(command[0], env, e.StdOut)
 	if err != nil {
@@ -341,9 +271,13 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 	cmd := exec.CommandContext(ctx, f)
 	cmd.Path = f
 	cmd.Args = command
-	cmd.Stdin = nil
 	cmd.Stdout = e.StdOut
-	cmd.Env = envList
+	trackingID := e.TrackingID
+	if value, ok := common.LookupFold(env, "RUNNER_TRACKING_ID", e.IsEnvironmentCaseInsensitive()); ok {
+		trackingID = value
+	}
+	tracked := trackingID == e.TrackingID
+	cmd.Env = append(getEnvListFromMap(env), "RUNNER_TRACKING_ID="+trackingID)
 	cmd.Stderr = e.StdOut
 	cmd.Dir = wd
 	cmd.SysProcAttr = process.SysProcAttr(cmdline, false)
@@ -351,6 +285,7 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 	// 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)
+	treeKill.KeepLeftovers = !tracked
 
 	var ppty *os.File
 	var tty *os.File
@@ -375,49 +310,51 @@ func (e *HostEnvironment) exec(ctx context.Context, command []string, cmdline st
 		writer = &ptyWriter{Out: e.StdOut}
 		var finishLog context.CancelFunc
 		logctx, finishLog = context.WithCancel(context.Background())
-		go copyPtyOutput(writer, ppty, finishLog)
-		go writeKeepAlive(ppty)
+		go func() {
+			defer finishLog()
+			_, _ = io.Copy(writer, ppty)
+		}()
+		go writeKeepAlive(logctx, ppty)
 	}
 	if err := cmd.Start(); err != nil {
 		return err
 	}
-	// Assign before the step's Killer so the step's job nests inside the group's;
-	// cancellation still scopes to this step's tree.
-	if err := e.processGroup(ctx).Assign(cmd.Process); err != nil {
-		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)
+	if tracked {
+		if err := e.processGroup(ctx).Assign(cmd.Process); err != nil {
+			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)
+		}
 	}
 	if k, kerr := treeKill.Capture(cmd.Process); kerr != nil {
 		common.Logger(ctx).Warnf("process tree kill setup failed, falling back to single-process kill: %v", kerr)
 	} else {
 		defer k.Close()
 	}
-	err = cmd.Wait()
-	if err != nil {
-		var exitErr *exec.ExitError
-		if errors.As(err, &exitErr) {
-			return ExitCodeError(exitErr.ExitCode())
-		}
-		return err
-	}
+	err = treeKill.Wait(ctx, cmd)
 	if tty != nil {
 		writer.AutoStop.Store(true)
 		if _, err := tty.WriteString("\x04"); err != nil {
 			common.Logger(ctx).Debug("Failed to write EOT")
 		}
-		<-logctx.Done()
+		select {
+		case <-logctx.Done():
+		case <-ctx.Done(): // a cancelled step does not wait on output nobody consumes
+		}
 		ppty.Close()
 		ppty = nil
 	}
+	if exitErr, ok := errors.AsType[*exec.ExitError](err); ok {
+		return ExitCodeError(exitErr.ExitCode())
+	}
 	return err
 }
 
-func (e *HostEnvironment) Exec(command []string /*cmdline string, */, env map[string]string, user, workdir string) common.Executor {
-	return e.ExecWithCmdLine(command, "", env, user, workdir)
+func (e *HostEnvironment) Exec(command []string, env map[string]string, _user, workdir string) common.Executor {
+	return e.ExecWithCmdLine(command, "", env, workdir)
 }
 
-func (e *HostEnvironment) ExecWithCmdLine(command []string, cmdline string, env map[string]string, user, workdir string) common.Executor {
+func (e *HostEnvironment) ExecWithCmdLine(command []string, cmdline string, env map[string]string, workdir string) common.Executor {
 	return func(ctx context.Context) error {
-		if err := e.exec(ctx, command, cmdline, env, user, workdir); err != nil {
+		if err := e.exec(ctx, command, cmdline, env, workdir); err != nil {
 			select {
 			case <-ctx.Done():
 				return fmt.Errorf("this step has been cancelled: %w", err)
@@ -430,15 +367,13 @@ func (e *HostEnvironment) ExecWithCmdLine(command []string, cmdline string, env
 }
 
 func (e *HostEnvironment) UpdateFromEnv(srcPath string, env *map[string]string) common.Executor {
-	return parseEnvFile(e, srcPath, env)
+	return parseEnvFile(e, srcPath, env, runtime.GOOS == "windows")
 }
 
 // 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).
+// Returns on cancel while an uninterruptible delete keeps running, freeing the runner's capacity slot.
 func removeAllWithContext(ctx context.Context, path string) error {
 	done := make(chan error, 1)
 	go func() { done <- removeAll(path) }()
@@ -480,35 +415,6 @@ func removePathWithRetry(ctx context.Context, path string) error {
 	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
@@ -542,20 +448,10 @@ func (e *HostEnvironment) terminateRunningProcesses(ctx context.Context) {
 		return
 	}
 
-	script := buildWindowsWorkspaceKillScript(dirs)
-
-	cmd := exec.CommandContext(killCtx, "powershell.exe", "-NoProfile", "-NonInteractive", "-Command", script)
-	out, err := cmd.CombinedOutput()
-	if err != nil {
-		logger.Debugf("workspace process-tree kill via PowerShell failed: %v output=%s", 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)
+	if killed, err := process.KillProcessesWithPaths(killCtx, dirs, e.TrackingID); err != nil {
+		logger.Debugf("workspace process cleanup reported errors: %v", err)
 	} else if killed > 0 {
-		logger.Debugf("terminated %d leftover process(es) by workspace working directory", killed)
+		logger.Debugf("terminated %d leftover workspace process(es)", killed)
 	}
 }
 
@@ -563,26 +459,6 @@ func (e *HostEnvironment) terminateRunningProcesses(ctx context.Context) {
 // 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 {
 		logger := common.Logger(ctx)
@@ -594,25 +470,14 @@ func (e *HostEnvironment) Remove() common.Executor {
 		}
 		e.terminateRunningProcesses(ctx)
 
-		// 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 {
-			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")
-			}
-		}
-
 		// 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(rmCtx, e.Path); err != nil {
-			logger.Warnf("failed to remove host misc state %s: %v", e.Path, err)
+		if err := removePathWithRetry(rmCtx, cmp.Or(e.Root, e.Path)); err != nil {
+			logger.Warnf("failed to remove host misc state %s: %v", cmp.Or(e.Root, e.Path), err)
 			errs = append(errs, err)
 		}
 		if e.CleanWorkdir {
@@ -659,8 +524,7 @@ func (*HostEnvironment) GetPathVariableName() string {
 }
 
 func (e *HostEnvironment) DefaultPathVariable() string {
-	v, _ := os.LookupEnv(e.GetPathVariableName())
-	return v
+	return os.Getenv(e.GetPathVariableName())
 }
 
 func (*HostEnvironment) JoinPathVariable(paths ...string) string {
@@ -670,25 +534,23 @@ func (*HostEnvironment) JoinPathVariable(paths ...string) string {
 // Reference for Arch values for runner.arch
 // https://docs.github.com/en/actions/learn-github-actions/contexts#runner-context
 func goArchToActionArch(arch string) string {
-	archMapper := map[string]string{
+	return cmp.Or(map[string]string{
 		"x86_64":  "X64",
+		"amd64":   "X64",
 		"386":     "X86",
+		"arm":     "ARM",
 		"aarch64": "ARM64",
-	}
-	if arch, ok := archMapper[arch]; ok {
-		return arch
-	}
-	return arch
+		"arm64":   "ARM64",
+	}[arch], arch)
 }
 
 func goOsToActionOs(os string) string {
-	osMapper := map[string]string{
-		"darwin": "macOS",
-	}
-	if os, ok := osMapper[os]; ok {
-		return os
-	}
-	return os
+	return cmp.Or(map[string]string{
+		"linux":   "Linux",
+		"darwin":  "macOS",
+		"windows": "Windows",
+		"freebsd": "FreeBSD",
+	}[os], os)
 }
 
 func (e *HostEnvironment) GetRunnerContext(_ context.Context) map[string]any {