fix(deps): update go toolchain directive to v1.27.3 (#1332)

Go 1.27.3 includes a crypto/x509 security fix that distrusts a set of intermediate certificates (https://github.com/golang/go/issues/82345), so release builds need the new toolchain.

Reviewed-on: https://gitea.com/gitea/runner/pulls/1332
Reviewed-by: TheFox0x7 <95654+thefox0x7@noreply.gitea.com>

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

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

.gitea/workflows/release-nightly.yml

@@ -17,24 +17,35 @@ jobs:
   goreleaser:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-go@v6
+      # Custom publishers (the R2 upload below) run as the very last
+      # step of goreleaser's publish pipeline, after the Gitea release
+      # 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:
+          R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: "go.mod"
+          check-latest: true
       - name: goreleaser
-        uses: goreleaser/goreleaser-action@v7
+        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # 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 }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
           GORELEASER_FORCE_TOKEN: "gitea"
           GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -43,27 +54,33 @@ jobs:
     strategy:
       matrix:
         variant:
+          # The basic image is built from source and can target any arch the
+          # toolchain supports. The dind variants are limited to the arches the
+          # docker:dind base image publishes.
           - target: basic
             tag_suffix: ""
+            platforms: linux/amd64,linux/arm64,linux/riscv64,linux/s390x
           - target: dind
             tag_suffix: "-dind"
+            platforms: linux/amd64,linux/arm64
           - target: dind-rootless
             tag_suffix: "-dind-rootless"
+            platforms: linux/amd64,linux/arm64
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to DockerHub
-        uses: docker/login-action@v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
@@ -77,14 +94,12 @@ jobs:
           echo REPO_VERSION=$(git describe --tags --always | sed 's/-/+/' | sed 's/^v//') >> $GITHUB_OUTPUT
 
       - name: Build and push
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: ./Dockerfile
           target: ${{ matrix.variant.target }}
-          platforms: |
-            linux/amd64
-            linux/arm64
+          platforms: ${{ matrix.variant.platforms }}
           push: true
           tags: |
             ${{ env.DOCKER_ORG }}/runner:nightly${{ matrix.variant.tag_suffix }}

.gitea/workflows/release-tag.yml

@@ -9,31 +9,42 @@ jobs:
   goreleaser:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0 # all history for all branches and tags
-      - uses: actions/setup-go@v6
+      # Custom publishers (the R2 upload below) run as the very last
+      # step of goreleaser's publish pipeline, after the Gitea release
+      # 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:
+          R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: "go.mod"
+          check-latest: true
       - name: Import GPG key
         id: import_gpg
-        uses: crazy-max/ghaction-import-gpg@v7
+        uses: crazy-max/ghaction-import-gpg@2dc316deee8e90f13e1a351ab510b4d5bc0c82cd # v7
         with:
           gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
           passphrase: ${{ secrets.PASSPHRASE }}
           fingerprint: CC64B1DB67ABBEECAB24B6455FC346329753F4B0
       - name: goreleaser
-        uses: goreleaser/goreleaser-action@v7
+        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
         with:
           distribution: goreleaser-pro
           args: release
         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 }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
           GORELEASER_FORCE_TOKEN: "gitea"
           GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }}
@@ -42,12 +53,18 @@ jobs:
     strategy:
       matrix:
         variant:
+          # The basic image is built from source and can target any arch the
+          # toolchain supports. The dind variants are limited to the arches the
+          # docker:dind base image publishes.
           - target: basic
             tag_suffix: ""
+            platforms: linux/amd64,linux/arm64,linux/riscv64,linux/s390x
           - target: dind
             tag_suffix: "-dind"
+            platforms: linux/amd64,linux/arm64
           - target: dind-rootless
             tag_suffix: "-dind-rootless"
+            platforms: linux/amd64,linux/arm64
     container:
       image: catthehacker/ubuntu:act-latest
     env:
@@ -55,25 +72,25 @@ jobs:
       DOCKER_LATEST: latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to DockerHub
-        uses: docker/login-action@v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
 
       - name: "Docker meta"
         id: docker_meta
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
         with:
           images: |
             ${{ env.DOCKER_ORG }}/runner
@@ -86,14 +103,12 @@ jobs:
             suffix=${{ matrix.variant.tag_suffix }},onlatest=true
 
       - name: Build and push
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: ./Dockerfile
           target: ${{ matrix.variant.target }}
-          platforms: |
-            linux/amd64
-            linux/arm64
+          platforms: ${{ matrix.variant.platforms }}
           push: true
           tags: ${{ steps.docker_meta.outputs.tags }}
           build-args: |

.gitea/workflows/test.yml

@@ -1,22 +1,78 @@
 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
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-go@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: 'go.mod'
+          check-latest: true
+      - name: prepare anonymous docker config
+        run: mkdir -p "$DOCKER_CONFIG" && echo '{}' > "$DOCKER_CONFIG/config.json"
+      # Pre-pull act/runner's two largest base images so a slow pull can't dominate `make test`;
+      # the rest (alpine/ubuntu) pull on demand, absorbed by the make-test -timeout. The host
+      # daemon retains them between runs, so this is usually a fast manifest re-check.
+      - name: pre-pull test images
+        env:
+          TEST_JOB_IMAGE: node:24-bookworm-slim@sha256:d6aa754f16b3197301076f047b5def2f02ea1dbbc2ca920407d46d7ec7f87b20 # renovate: datasource=docker
+          TEST_SERVICE_IMAGE: nginx:alpine@sha256:df221db836e1754089190208cee7eeda94f233197056426eda74a43ab1abeac2 # renovate: datasource=docker
+        run: |
+          for image in "$TEST_JOB_IMAGE" "$TEST_SERVICE_IMAGE"; do
+            for attempt in 1 2 3; do
+              docker pull "$image" && break
+              [ "$attempt" = 3 ] || sleep 5
+            done
+            docker tag "$image" "${image%@*}"
+          done
       - name: lint
         run: make lint
+      - name: checks
+        run: make checks
       - name: build
         run: make build
       - name: test
-        run: make test
+        run: make test
+      # Build the dind image and run the daemon-facing tests against the docker version it
+      # ships, catching daemon-level regressions (e.g. gitea/runner#981) before release. Runs
+      # after `make test` so the images it needs are already present on the host daemon.
+      - name: test against dind image
+        run: make test-dind
+      - name: test against podman
+        run: make test-dind TARGET=podman
+      - name: coverage report
+        run: |
+          make coverage-report
+          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: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version-file: 'go.mod'
+          check-latest: true
+      - 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

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

.golangci.yml

@@ -11,6 +11,7 @@ linters:
     - dupl
     - errcheck
     - forbidigo
+    - forcetypeassert
     - gocheckcompilerdirectives
     - gocritic
     - goheader
@@ -36,12 +37,15 @@ linters:
       rules:
         main:
           deny:
-            - pkg: io/ioutil
-              desc: use os or io instead
             - pkg: golang.org/x/exp
               desc: it's experimental and unreliable
-            - pkg: github.com/pkg/errors
-              desc: use builtin errors package instead
+        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
@@ -49,8 +53,7 @@ linters:
     gocritic:
       enabled-checks:
         - equalFold
-      disabled-checks:
-        - ifElseChain
+      disabled-checks: []
     revive:
       severity: error
       rules:
@@ -74,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:
@@ -95,13 +102,14 @@ linters:
     generated: lax
     presets:
       - comments
-      - common-false-positives
-      - legacy
       - std-error-handling
     rules:
       - linters:
           - forbidigo
         path: cmd
+      - linters:
+          - forcetypeassert
+        path: _test\.go
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0
@@ -118,7 +126,8 @@ formatters:
         - blank
         - default
     gofumpt:
-      extra-rules: true
+      extra:
+        group-params: true
   exclusions:
     generated: lax
 run:

.goreleaser.yaml

@@ -83,18 +83,37 @@ 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}}"
+# 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`
+# as UploadableFile artifacts, and `internal/exec`'s filterArtifacts
+# appends this block's own extra_files with no de-duplication. It
+# can't be globbed away, since gobwas/glob (via goreleaser/fileglob)
+# has no substring-exclusion matcher. It's harmless: PUT is
+# idempotent, and the `./**.xz` glob below is kept deliberately so
+# this publisher declares its own complete file set rather than
+# implicitly depending on the `release:` block's globs.
+publishers:
+  - name: cloudflare-r2
+    checksum: true
     extra_files:
       - glob: ./**.xz
       - glob: ./**.sha256
+    cmd: sh scripts/upload-r2.sh {{ abs .ArtifactPath }} gitea-runner/{{ .Version }}/{{ .ArtifactName }}
+    env:
+      - R2_ENDPOINT={{ index .Env "R2_ENDPOINT" }}
+      - R2_BUCKET={{ index .Env "R2_BUCKET" }}
+      - R2_ACCESS_KEY_ID={{ index .Env "R2_ACCESS_KEY_ID" }}
+      - R2_SECRET_ACCESS_KEY={{ index .Env "R2_SECRET_ACCESS_KEY" }}
 
 archives:
-  - format: binary
+  - formats: [binary]
     name_template: "{{ .Binary }}"
     allow_different_binary_count: true
 

AGENTS.md

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

CLAUDE.md

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

DEVELOPMENT.md

@@ -0,0 +1,63 @@
+# 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 reporter
+  decodes exactly those two when folding a location into an annotation.
+
+## 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.
+
+The suite shares one Gitea and regular runner. Cache and ephemeral scenarios use isolated
+repository runners. A run path is `<workflow>@<ref>` and a log row is `<timestamp>Z <payload>`.

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
@@ -17,14 +17,14 @@ RUN make clean && make build
 ### DIND VARIANT
 #
 #
-FROM docker:29.5.2-dind AS dind
+FROM docker:29.9.1-dind AS dind
 
 ARG VERSION=dev
 
 LABEL org.opencontainers.image.source="https://gitea.com/gitea/runner"
 LABEL org.opencontainers.image.version="${VERSION}"
 
-RUN apk add --no-cache s6 bash git tzdata
+RUN apk add --no-cache s6 bash git tzdata nftables
 
 COPY --from=builder /opt/src/runner/gitea-runner /usr/local/bin/gitea-runner
 COPY scripts/run.sh /usr/local/bin/run.sh
@@ -32,12 +32,14 @@ COPY scripts/s6 /etc/s6
 
 VOLUME /data
 
+ENV TINI_SUBREAPER=1
+
 ENTRYPOINT ["s6-svscan","/etc/s6"]
 
 ### DIND-ROOTLESS VARIANT
 #
 #
-FROM docker:29.5.2-dind-rootless AS dind-rootless
+FROM docker:29.9.1-dind-rootless AS dind-rootless
 
 ARG VERSION=dev
 
@@ -45,7 +47,7 @@ LABEL org.opencontainers.image.source="https://gitea.com/gitea/runner"
 LABEL org.opencontainers.image.version="${VERSION}"
 
 USER root
-RUN apk add --no-cache s6 bash git tzdata
+RUN apk add --no-cache s6 bash git tzdata nftables
 
 COPY --from=builder /opt/src/runner/gitea-runner /usr/local/bin/gitea-runner
 COPY scripts/run.sh /usr/local/bin/run.sh
@@ -56,6 +58,7 @@ VOLUME /data
 RUN mkdir -p /data && chown -R rootless:rootless /etc/s6 /data
 
 ENV DOCKER_HOST=unix:///run/user/1000/docker.sock
+ENV TINI_SUBREAPER=1
 
 USER rootless
 ENTRYPOINT ["s6-svscan","/etc/s6"]
@@ -63,7 +66,7 @@ ENTRYPOINT ["s6-svscan","/etc/s6"]
 ### BASIC VARIANT
 #
 #
-FROM alpine:3.23 AS basic
+FROM alpine:3.24 AS basic
 
 ARG VERSION=dev
 

Makefile

@@ -1,16 +1,14 @@
 DIST := dist
 EXECUTABLE := gitea-runner
-DIST_DIRS := $(DIST)/binaries $(DIST)/release
 GO ?= go
-SHASUM ?= shasum -a 256
 HAS_GO = $(shell hash $(GO) > /dev/null 2>&1 && echo "GO" || echo "NOGO" )
-XGO_PACKAGE ?= src.techknowlogick.com/xgo@latest
-XGO_VERSION := go-1.26.x
-GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/gxz@v0.5.10
 
-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:0e62e56b382ebf485bff1e51a05cbe27c708545a2e91425467fd31eb3e249521 # 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
+
 GOFILES := $(shell find . -type f -name "*.go" -o -name "go.mod" ! -name "generated.*")
 
 DOCKER_IMAGE ?= gitea/runner
@@ -18,8 +16,10 @@ DOCKER_TAG ?= nightly
 DOCKER_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)
 DOCKER_ROOTLESS_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)-dind-rootless
 
-GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
-GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.3.0
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.14.0 # renovate: datasource=go
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.8.0 # renovate: datasource=go
+
+GOTEST_FLAGS ?= -race -timeout 20m -parallel 8
 
 STATIC ?=
 EXTLDFLAGS ?=
@@ -30,20 +30,20 @@ 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
 
 STORED_VERSION_FILE := VERSION
@@ -91,29 +91,30 @@ go-check:
 	fi
 
 .PHONY: fmt-check
-fmt-check: fmt
-	@diff=$$(git diff --color=always); \
-	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
 
+.PHONY: checks
+checks: tidy-check fmt-check security-check ## run the non-lint source checks
+
 .PHONY: lint
-lint: lint-go ## lint everything
+lint: lint-go lint-go-windows ## lint everything
 
 .PHONY: lint-go
 lint-go: ## lint go files
 	$(GO) run $(GOLANGCI_LINT_PACKAGE) run
 
+.PHONY: lint-go-windows
+lint-go-windows: ## lint Windows go files
+	$(GO) install $(GOLANGCI_LINT_PACKAGE)
+	$(GO_ENV_WINDOWS) golangci-lint run
+
 .PHONY: lint-go-fix
 lint-go-fix: ## lint go files and fix issues
 	$(GO) run $(GOLANGCI_LINT_PACKAGE) run --fix
@@ -123,25 +124,41 @@ lint-pr-title: ## lint PR title against Conventional Commits (set PR_TITLE=...)
 	@node ./tools/lint-pr-title.ts
 
 .PHONY: security-check
-security-check: deps-tools
-	GOEXPERIMENT= $(GO) run $(GOVULNCHECK_PACKAGE) -show color ./... || true
+security-check:
+	$(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
-
-.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; \
+	@# 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: ## check that go.mod and go.sum are tidy
+	$(GO) mod tidy -diff
+
 .PHONY: test
-test: fmt-check security-check ## test everything
-	@$(GO) test -race -short -v -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
+test: ## test everything (integration tests self-skip without docker/network)
+	@$(GO) test $(GOTEST_FLAGS) -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
+
+.PHONY: coverage-report
+coverage-report: ## turn coverage.txt from `make test` into .tmp/coverage.md
+	@mkdir -p .tmp
+	@node ./tools/coverage-report.ts -i coverage.txt -o .tmp/coverage.md
+	@echo "Wrote .tmp/coverage.md"
+
+.PHONY: test-dind
+test-dind: ## run the daemon-facing tests against the built dind image or podman (TARGET=dind|dind-rootless|podman)
+	@PODMAN_TEST_IMAGE=$(PODMAN_TEST_IMAGE) ./scripts/test-dind.sh $(TARGET)
+
+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
 
 .PHONY: install
 install: $(GOFILES) ## install the runner binary via `go install`
@@ -157,45 +174,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 \
@@ -206,7 +184,7 @@ docker: ## build the docker image
 .PHONY: clean
 clean: ## delete binary and coverage files
 	$(GO) clean -x -i ./...
-	rm -rf coverage.txt $(EXECUTABLE) $(DIST)
+	rm -rf coverage.txt .tmp $(EXECUTABLE) $(DIST)
 
 .PHONY: version
 version: ## print the version

README.md

@@ -4,7 +4,19 @@
 
 ### 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/).
+On the runner:
+
+- `git` 2.34.1 or newer on `PATH`, to clone reusable workflows, and actions whose host serves no archive of them.
+- `docker` or `podman` with `podman.socket` enabled, for docker mode, Docker actions and `docker://` steps. To install Docker CE, follow the official [install instructions](https://docs.docker.com/engine/install/).
+
+Where steps run, in the job image or on the runner in host mode:
+
+- `bash` or `sh` for `run` steps, `pwsh` or `powershell` on a Windows host.
+- `node` for JavaScript actions and `hashFiles()`.
+- `git` 2.34.1 or newer for [`builtin:checkout`](docs/builtin-actions.md).
+- `git-lfs` and `ssh` for `builtin:checkout`, only when its `lfs` or `ssh-key` input is used.
+
+Kubernetes mode needs [a few more tools](docs/kubernetes.md) in job images.
 
 ### Download pre-built binary
 
@@ -79,52 +91,272 @@ If the registry succeed, it will run immediately. Next time, you could run the r
 
 ### Run with docker
 
+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 -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
+docker run --privileged -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> \
+  -v "$PWD/data:/data" -v runner-docker:/var/lib/docker --name my_runner gitea/runner:nightly-dind
 ```
 
-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)).
+The volumes keep the runner's registration and the job image cache across container recreation.
+
+### Image flavours
+
+| Tag | Docker daemon for jobs |
+| --- | --- |
+| `latest-dind` (recommended) | Bundled, needs `--privileged`. |
+| `latest-dind-rootless` | Bundled, runs as a non-root user (UID 1000) for stronger isolation. Needs `--privileged` and [rootless Docker](https://docs.docker.com/engine/security/rootless/) support on the host. Keeps its image cache in `/home/rootless/.local/share/docker`. |
+| `latest` | None. Mount the host's socket with `-v /var/run/docker.sock:/var/run/docker.sock`, or set `DOCKER_HOST`. |
+
+Versioned and `nightly` tags carry the same suffixes, for example `nightly-dind`. The images target Docker, not Podman.
 
 ### Configuration
 
-The runner is configured with a YAML file. Generate a starting point (this matches what ships in the tree):
+The runner reads a YAML file. Without one, every option keeps its default.
 
 ```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). Every value in it is commented out, so copy the lines you want to change into your own file and uncomment them.
+
+#### Editing a config file
+
+`config` edits a file in place, which is handy in 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.timeout 90m  # written as 1h30m0s
+./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).
+A key is its dotted YAML path. An unknown key, a value of the wrong type, or `add`/`remove` on anything but a list is refused before the file is touched. `set` replaces a whole list when you give it several values.
 
-#### Without a config file
+An edit keeps the comments and the key order of the file. Indentation becomes two spaces, and a blank line between two values is dropped.
 
-If you omit `-c`, built-in defaults apply (same as an empty YAML document). A small set of **deprecated** environment variables can still override parts of that default config, but **only when no `-c` path was given**; they are ignored if you use a config file:
+`config get`, `set`, `add` and `remove` use `config.yaml` (or `config.yml`) from the working directory, then from the directory of the binary, and print their choice to stderr. `config init` writes `config.yaml` in the working directory, and refuses to overwrite an existing config without `--force`. Pass `-c` for another path.
 
-| Variable | Effect |
+#### Tool cache
+
+Setup actions like `setup-go` install tools into `RUNNER_TOOL_CACHE`, which is `/opt/hostedtoolcache` inside a job. `runner.tool_cache_mode` selects what backs it:
+
+| Mode | Tool cache | Trade-off |
+| --- | --- | --- |
+| `none` (default) | Per job, provided by the job image | A version the image lacks is downloaded in every job |
+| `shared` | One volume reused by every job | Two jobs writing the same tool version at once corrupt it, so use it only with `runner.capacity: 1` |
+
+With `none`, tools must come from the job image. Install them into `/opt/hostedtoolcache/<tool>/<version>/<arch>`, with an empty `<arch>.complete` file next to the directory:
+
+```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"
+```
+
+A workflow requesting a minor version, `go-version: "1.26"`, resolves to the newest matching version in the cache, so a patch update in the image still hits it.
+
+Of the [runner images](https://gitea.com/gitea/runner-images), the `-full` flavour is the one that ships tools in this layout.
+
+`gitea-runner exec` reads no config file and takes `--tool-cache-mode` instead, defaulting to `none`.
+
+#### Environment variables
+
+Earlier releases let a few environment variables (`GITEA_DEBUG`, `GITEA_TRACE`, `GITEA_RUNNER_CAPACITY`, `GITEA_RUNNER_FILE`, `GITEA_RUNNER_ENVIRON`, `GITEA_RUNNER_ENV_FILE`) override parts of the config. They are gone, use the YAML file for all settings. Config values can read the runner's environment as `${NAME}`, for example `capacity: ${RUNNER_CAPACITY}`. An unset `NAME` fails the load, and `$${NAME}` is a literal `${NAME}`. The Docker images still read their own variables, such as `RUNNER_STATE_FILE`, see [scripts/run.sh](scripts/run.sh) and the container documentation below.
+
+### Labels
+
+Labels decide **which jobs a runner accepts** and **how it runs them**. A job's `runs-on` is matched against the runner's label names; the first match wins and selects the execution environment for that job.
+
+A label is written as:
+
+```text
+<name>[:<schema>[:<args>]]
+```
+
+| Part | Meaning |
 | --- | --- |
-| `GITEA_DEBUG` | If true, sets log level to `debug` |
-| `GITEA_TRACE` | If true, sets log level to `trace` |
-| `GITEA_RUNNER_CAPACITY` | Concurrent jobs (integer) |
-| `GITEA_RUNNER_FILE` | Registration state file path (default `.runner`) |
-| `GITEA_RUNNER_ENVIRON` | Extra job env vars as comma-separated `KEY:VALUE` pairs |
-| `GITEA_RUNNER_ENV_FILE` | Path to an env file merged into job env (same idea as `runner.env_file` in YAML) |
+| `name` | The name a workflow refers to in `runs-on`, e.g. `ubuntu-latest`. |
+| `schema` | `docker`, `kubernetes` or `host`. Defaults to `host` when omitted. |
+| `args` | Only used by the `docker` and `kubernetes` schemas: the image to run the job in. |
 
-Prefer a YAML file for all settings.
+Three 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
+  ```
+
+- **`kubernetes://<image>`** — the job runs as a Kubernetes pod created from `<image>`, see **[docs/kubernetes.md](docs/kubernetes.md)**:
+
+  ```text
+  ubuntu-latest:kubernetes://docker.gitea.com/runner-images:ubuntu-latest
+  ```
+
+- **`host`** — the job's steps run directly on the machine the runner is on, using the tools installed there:
+
+  ```text
+  macos:host
+  ```
+
+So with the labels
+
+```text
+ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,macos:host
+```
+
+a workflow with `runs-on: ubuntu-latest` is executed in the `runner-images:ubuntu-latest` container, and one with `runs-on: macos` is executed directly on the host.
+
+Names may themselves contain a colon, for example `pool:e57e18d4-10d4-406f-93bf-60f127221bdd`. Only `host`, `docker` and `kubernetes` are treated as schemas.
+
+Jobs run on `runner.default_image` when no runner label matches their `runs-on`: as a pod on runners with `kubernetes` labels, otherwise in a container, or on the host when docker is unavailable. Suitable images are listed at [gitea/runner-images](https://gitea.com/gitea/runner-images).
+
+Labels are chosen at registration time (`--labels`, or the interactive prompt) and can be changed afterwards by editing `runner.labels` in the config file, or in the Gitea UI under the runner's settings.
 
 #### Registration vs config labels
 
 If `runner.labels` is set in the YAML file, those labels are used during `register` and the `--labels` CLI flag is ignored.
 
-#### External cache (`actions/cache`)
+The `daemon` command also accepts `--labels` (which defaults to the `GITEA_RUNNER_LABELS` environment variable), so the labels of an already registered runner can be changed without deleting its registration file. The most explicit source wins:
 
-If `cache.external_server` is set, you must set `cache.external_secret` to the same value on this runner and on the standalone cache server. Run the server with `gitea-runner cache-server` using a config that defines `cache.external_secret` (and matching `cache.dir` / host / port as needed). Flags `--dir`, `--host`, and `--port` on `cache-server` override the file.
+```
+--labels / GITEA_RUNNER_LABELS   >   runner.labels in the config file   >   labels in the .runner file
+```
+
+Whenever the resulting labels differ from the ones in the registration file, they are written back to it and re-declared to the Gitea instance on startup.
+
+> **Note:** A runner that only exposes `host` labels still needs access to a Docker daemon (e.g. a mounted `/var/run/docker.sock`) whenever a job uses a `docker://` action or a service container. `host` labels only change where the job's own steps run; container-based steps and actions are still executed with Docker.
+
+#### Service containers
+
+A job's `services` are started before its steps run. When a service's image or its `options` declare a healthcheck, the runner waits for it to report healthy, so a workflow does not have to poll for its own services:
+
+```yaml
+services:
+  postgres:
+    image: postgres:18
+    options: >-
+      --health-cmd pg_isready
+      --health-interval 5s
+      --health-retries 10
+```
+
+A service that reports unhealthy fails the job right away, with its container log. One that never becomes healthy fails it after `container.service_ready_timeout` (default `5m`, negative disables the wait). A service that exits without declaring a healthcheck only gets its log and a warning.
+
+A job in a container reaches a service by its id on the job network, on the port the service listens on, for example `psql -h postgres -p 5432`. The started containers also fill the `job` context: `job.container.{id,network}` and `job.services.<id>.{id,network,ports}`, where `ports` maps a container port to the host port Docker published it on, for the services that publish one.
+
+Unlike GitHub, a job whose steps run on the host (a `host` label without `container:`) starts no service containers, so `job.services` and `job.container` stay empty. Give such a job a `container:` when it needs services.
+
+#### Docker from a job (`GITEA_DOCKER_WORKSPACE`)
+
+Containers a job starts through the Docker socket can bind-mount the workspace by the job's own path, as on a host, for example `docker run -v "$PWD:/src"`. Without the Docker proxy, for example with a remote `DOCKER_HOST`, use `GITEA_DOCKER_WORKSPACE`, the path the daemon sees, as the prefix of workspace binds, with `.` as the fallback for local use:
+
+```yaml
+volumes:
+  - ${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data
+```
+
+Linux container jobs use a Docker proxy when socket sharing and permissions allow it. Other setups use the daemon socket directly. Host jobs use their existing Docker access, where `.` works. The proxy removes the containers, networks and volumes a job creates, `docker compose` services included, after post steps and the completed hook. Set `container.sweep: false` when jobs deploy services to the runner's Docker daemon.
+
+#### Proxy
+
+Set these variables in the runner's environment, with systemd `Environment=`, `docker run -e`, or Kubernetes `env:`:
+
+```sh
+http_proxy=http://proxy.example:3128
+https_proxy=http://proxy.example:3128
+no_proxy=gitea.internal,.example.local
+```
+
+The runner uses them for its own requests and gives them to every job, in lower and upper case.
+
+These hosts are added to `no_proxy` for jobs, so they are always reached directly:
+
+- the built-in cache server, whose address is assigned at startup
+- `localhost`, `127.0.0.1` and `::1`
+- the job's service containers
+- the Docker daemon, when it is reached over `tcp://`
+
+Gitea is not added. Add it to `no_proxy` yourself if it should be reached directly.
+
+For one step, set it in the step's `env:`, for the rest of a job, write it to `$GITHUB_ENV`. Setting it at workflow or job level or in `container.env` has no effect. To change it for the whole runner, set it in `runner.envs`. A `no_proxy` set there is added to the list above instead of replacing it.
+
+Images are pulled by the Docker daemon, which needs its own proxy setting. In the `dind` images the daemon runs in the same container and reads the variables above. For any other daemon, see [the Docker documentation](https://docs.docker.com/engine/daemon/proxy/). The runner logs a warning at startup if it has a proxy and the daemon does not.
+
+Dockerfile actions are built with these variables as build arguments, so their `RUN` steps can reach the network.
+
+A password in a proxy URL is hidden in job logs. Any step can still read it, because the step is given the proxy URL in its environment.
+
+#### Built-in actions (`uses: builtin:<name>`)
+
+Use `uses: builtin:checkout` to check out a repository without downloading `actions/checkout` or needing Node in the job image, see **[docs/builtin-actions.md](docs/builtin-actions.md)**.
+
+#### Caching (`actions/cache`)
+
+Each runner starts its own cache server, so runners do not share cached entries. A runner in a container on the jobs' Docker daemon attaches itself to each job network, so jobs reach its cache without extra setup.
+
+**Sharing a cache between runners**
+
+Run one `gitea-runner cache-server` and point every runner at it, using the same secret everywhere, 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>"
+```
+
+`--dir`, `--host` and `--port` override the matching `cache` keys. Eviction settings take effect on the cache server, not on the runners.
+
+Runners can also share one `cache.dir` on a file system with working file locks, at the cost of slower cache requests.
+
+**Storing the cache in an S3-compatible bucket**
+
+The cache can also be stored in an S3-compatible bucket such as AWS S3, MinIO or RustFS, with no cache server. Runners with the same settings use the same cache:
+
+```yaml
+cache:
+  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"
+```
+
+A cache saved on one runner can be restored on the others within 30 seconds. The eviction settings below do not apply to the bucket, so add lifecycle rules to it that expire old caches and abort incomplete multipart uploads.
+
+**Eviction**
+
+Entries not read or written within `retention` (default `168h`) are removed. A repository over `repo_size_limit` (default `10GB`) loses its least recently used entries, and `size_limit` (off by default) caps the whole cache the same way. Entries in use are never removed. The cache also keeps 1024 MiB free on its volume, or `health_check.min_free_disk_space_mb` when health checks are enabled. See [config.example.yaml](internal/pkg/config/config.example.yaml) for all options.
+
+**Cache service v2**
+
+`actions/cache` v3.4.0, v4.2.0 and later use the cache service v2 API, which the runner serves by default. These actions fall back to v1 on hosts they do not recognize as GitHub, so the runner removes that check from them while a job runs. This also lets the stock `actions/upload-artifact` v4.4.0 and `actions/download-artifact` v4.1.8 and later work without the `gitea-upload-artifact` fork. With `runner.patch_actions: false`, the cache stays on v1 and the artifact actions fail.
+
+With v2, artifact calls also go through the cache server, so jobs must be able to reach it. `cache.v2: false` sends them to Gitea directly, unless the Gitea URL has a path or `runner.insecure` is set with HTTPS.
 
 #### Official Docker image
 
@@ -132,11 +364,47 @@ Besides `GITEA_INSTANCE_URL` and `GITEA_RUNNER_REGISTRATION_TOKEN`, the image en
 
 For a fuller container-oriented walkthrough, see [examples/docker](examples/docker/README.md).
 
-When `container.bind_workdir` is enabled, stale task workspace directories can be cleaned while the runner is idle:
-- directories older than `runner.workdir_cleanup_age` are removed (default: `24h`; set `0` to disable)
-- cleanup runs every `runner.idle_cleanup_interval` (default: `10m`; set `0` to disable)
+While the runner is idle it cleans up after earlier jobs:
+- when `container.bind_workdir` is enabled, stale task workspace directories older than `runner.workdir_cleanup_age` are removed (default: `24h`; set `0` to disable)
 - only purely numeric subdirectories under `container.workdir_parent` are treated as task workspaces and may be removed
 - cleanup assumes `container.workdir_parent` is not shared across multiple runners
+- on runners that use docker, per-job networks and volumes left behind by jobs the runner did not live to tear down are removed once unused and 10 minutes old, identified by the `com.gitea.runner.uuid` label carrying this runner's uuid
+- on runners with `kubernetes` labels, job pods with that label older than `runner.workdir_cleanup_age` are removed the same way, together with their Secrets
+- cleanup runs every `runner.idle_cleanup_interval` (default: `10m`; set `0` to disable), and setting either knob to `0` disables all of the above
+
+#### Post-task script (`runner.post_task_script`)
+
+Optional host script that runs **after** each task's built-in cleanup (post-steps, container teardown, bind-workdir removal). Use it for extra machine housekeeping — Docker pruning, disk cleanup, and similar.
+
+**While the script runs, the runner stops task heartbeats and stays offline from Gitea's perspective until the script exits (or hits `runner.post_task_script_timeout`, default `5m`).** A script that blocks without exiting keeps the runner from taking new work for up to that timeout. Script output goes to the runner log, not the job log; a non-zero exit is warned but does not change the job result.
+
+On Windows, use `.exe`, `.bat`, or `.cmd` paths; **PowerShell (`.ps1`) is not supported yet** as the configured path — wrap commands in a `.cmd` file instead.
+
+See **[docs/post-task-script.md](docs/post-task-script.md)** for lifecycle details, environment variables, timeout interaction, and platform notes.
+
+#### Job hooks (`runner.hooks.job_started`, `runner.hooks.job_completed`)
+
+Optional scripts that run **inside the job environment** (the job container, or the host in host mode), before the job's first step and after its last one. They are the equivalent of GitHub's `ACTIONS_RUNNER_HOOK_JOB_STARTED` / `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`, which are read when the settings are unset.
+
+Because they run where the steps run and see the job's environment, they are the place for per-job setup no workflow should have to carry: registry logins, mirror configuration, or masking runner-wide secrets with `::add-mask::`. Their output is part of the job log and is scanned for workflow commands, and they can export to the job through `$GITHUB_ENV` and `$GITHUB_PATH`.
+
+Both hooks are synchronous and block the job while they run. Either one exiting non-zero fails the job, and there is no per-hook timeout.
+
+See **[docs/job-hooks.md](docs/job-hooks.md)** for the execution order, environment, and platform notes.
+
+#### OpenTelemetry (`OTEL_*`)
+
+Set `OTEL_EXPORTER_OTLP_ENDPOINT` in the runner's environment to send a trace of every job, and the runner's metrics, to an OpenTelemetry collector. See **[docs/telemetry.md](docs/telemetry.md)**.
+
+#### Local job logs (`log.job.dir`)
+
+Set `log.job.dir` to a path and the runner writes a copy of every task's log there as `<start time>-task-<id>.log`: the rows exactly as Gitea received them, with the same secrets masked and the job's result on the last line. Off by default, and what Gitea shows does not change.
+
+#### Secret masking
+
+A job's secrets and its `::add-mask::` values are hidden from what the runner writes and uploads: the job log, the local copy above, job summaries, and the names of the containers it creates. A job output carrying one is skipped with a warning rather than sent masked, as GitHub does, so a downstream `needs.<job>.outputs.<name>` reading it is empty.
+
+`log.job.retention` (default `168h`) is how long a log is kept, expired ones being deleted as new tasks start, and `log.job.max_size` (default `1GB`) caps one log. Keep `retention` above `runner.timeout` so a long job cannot outlive its own log, and prefer local disk, the file is written while the job runs. Only the runner's own user can read it.
 
 ### Example Deployments
 

act/artifactcache/handler_test.go

@@ -7,10 +7,12 @@ package artifactcache
 import (
 	"bytes"
 	"crypto/rand"
-	"encoding/json"
+	"encoding/json/v2"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
@@ -41,18 +43,74 @@ func (b *bearerTransport) RoundTrip(r *http.Request) (*http.Response, error) {
 
 var testClient = &http.Client{Transport: &bearerTransport{token: testToken}}
 
+// testRetention mirrors config.DefaultCacheRetention; Policy has no defaults of its own.
+const testRetention = 7 * 24 * time.Hour
+
 // signArtifactURL builds a signed download URL the same way the server does;
 // tests use it to reach the get handler directly without going through a
 // find/cache-hit round trip.
 func signArtifactURL(h *Handler, id int64) string {
-	return h.signedArtifactURL(uint64(id), time.Now().Add(artifactURLTTL))
+	return h.signedArtifactURL(JobCredential{}, uint64(id), time.Now().Add(artifactURLTTL))
+}
+
+func TestHandler_ExternalURL(t *testing.T) {
+	assert.Equal(t, "http://[2001:db8::1]:8080", (&Handler{outboundIP: "2001:db8::1", port: 8080}).ExternalURL())
+}
+
+func TestHandler_Upstream(t *testing.T) {
+	var upstream *httptest.Server
+	upstream = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPut, r.Method)
+		assert.Equal(t, "/cache%20server"+blobPath+"/%34%32", r.URL.EscapedPath())
+		assert.Equal(t, "sig=opaque%2Fvalue&raw=a;b", r.URL.RawQuery)
+		assert.Equal(t, strings.TrimPrefix(upstream.URL, "http://"), r.Host)
+		assert.Equal(t, "Bearer unregistered", r.Header.Get("Authorization"))
+		_, err := io.Copy(w, r.Body)
+		assert.NoError(t, err)
+	}))
+	t.Cleanup(upstream.Close)
+	dir := filepath.Join(t.TempDir(), "artifactcache")
+	handler, err := StartHandler(Options{
+		Dir:        dir,
+		OutboundIP: "127.0.0.1",
+		Upstream:   upstream.URL + "/cache%20server//",
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, handler.Close()) })
+
+	req, err := http.NewRequestWithContext(t.Context(), http.MethodPut,
+		handler.ExternalURL()+blobPath+"/%34%32?sig=opaque%2Fvalue&raw=a;b", strings.NewReader("cache content"))
+	require.NoError(t, err)
+	req.Header.Set("Authorization", "Bearer unregistered")
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	forwarded, err := io.ReadAll(resp.Body)
+	resp.Body.Close()
+	require.NoError(t, err)
+	assert.Equal(t, "cache content", string(forwarded))
+
+	resp, err = http.Post(handler.ExternalURL()+internalPath+"/register", "application/json", nil)
+	require.NoError(t, err)
+	resp.Body.Close()
+	assert.Equal(t, http.StatusNotFound, resp.StatusCode)
+
+	upstream.Close()
+	resp, err = http.Post(handler.ExternalURL()+cacheServiceV2Path+"/CreateCacheEntry", "application/json", strings.NewReader(`{}`))
+	require.NoError(t, err)
+	var failure map[string]string
+	err = json.UnmarshalRead(resp.Body, &failure)
+	resp.Body.Close()
+	require.NoError(t, err)
+	assert.Equal(t, http.StatusServiceUnavailable, resp.StatusCode)
+	assert.Equal(t, map[string]string{"code": "unavailable", "msg": "cache upstream is unavailable"}, failure)
+	assert.NoDirExists(t, dir)
 }
 
 func TestHandler(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
-	handler.RegisterJob(testToken, testRepo)
+	handler.RegisterJob(testToken, JobCredential{Repo: testRepo})
 
 	base := fmt.Sprintf("%s%s", handler.ExternalURL(), apiPath)
 
@@ -132,7 +190,7 @@ func TestHandler(t *testing.T) {
 			defer resp.Body.Close()
 			assert.Equal(t, 200, resp.StatusCode)
 
-			require.NoError(t, json.NewDecoder(resp.Body).Decode(&first))
+			require.NoError(t, json.UnmarshalRead(resp.Body, &first))
 			assert.NotZero(t, first.CacheID)
 		}
 		{
@@ -147,7 +205,7 @@ func TestHandler(t *testing.T) {
 			defer resp.Body.Close()
 			assert.Equal(t, 200, resp.StatusCode)
 
-			require.NoError(t, json.NewDecoder(resp.Body).Decode(&second))
+			require.NoError(t, json.UnmarshalRead(resp.Body, &second))
 			assert.NotZero(t, second.CacheID)
 		}
 
@@ -200,7 +258,7 @@ func TestHandler(t *testing.T) {
 			got := struct {
 				CacheID uint64 `json:"cacheId"`
 			}{}
-			require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 			id = got.CacheID
 		}
 		{
@@ -255,7 +313,7 @@ func TestHandler(t *testing.T) {
 			got := struct {
 				CacheID uint64 `json:"cacheId"`
 			}{}
-			require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 			id = got.CacheID
 		}
 		{
@@ -311,7 +369,7 @@ func TestHandler(t *testing.T) {
 			got := struct {
 				CacheID uint64 `json:"cacheId"`
 			}{}
-			require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 			id = got.CacheID
 		}
 		{
@@ -358,7 +416,7 @@ func TestHandler(t *testing.T) {
 			got := struct {
 				CacheID uint64 `json:"cacheId"`
 			}{}
-			require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 			id = got.CacheID
 		}
 
@@ -409,7 +467,7 @@ func TestHandler(t *testing.T) {
 			got := struct {
 				CacheID uint64 `json:"cacheId"`
 			}{}
-			require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 			id = got.CacheID
 		}
 		{
@@ -445,13 +503,6 @@ func TestHandler(t *testing.T) {
 		require.Equal(t, 404, resp.StatusCode)
 	})
 
-	t.Run("get with not exist id", func(t *testing.T) {
-		resp, err := testClient.Get(signArtifactURL(handler, 100))
-		require.NoError(t, err)
-		defer resp.Body.Close()
-		require.Equal(t, 404, resp.StatusCode)
-	})
-
 	t.Run("get with multiple keys", func(t *testing.T) {
 		version := "c19da02a2bd7e77277f1ac29ab45c09b7d46a4ee758284e26bb3045ad11d9d20"
 		key := strings.ToLower(t.Name())
@@ -469,7 +520,8 @@ func TestHandler(t *testing.T) {
 			_, err := rand.Read(contents[i])
 			require.NoError(t, err)
 			uploadCacheNormally(t, base, keys[i], version, contents[i])
-			time.Sleep(time.Second) // ensure CreatedAt of caches are different
+			// ensure CreatedAt of caches are different, in upload order
+			backdateCache(t, handler, keys[i], time.Duration(len(contents)-i)*time.Second)
 		}
 
 		reqKeys := strings.Join([]string{
@@ -495,7 +547,7 @@ func TestHandler(t *testing.T) {
 			ArchiveLocation string `json:"archiveLocation"`
 			CacheKey        string `json:"cacheKey"`
 		}{}
-		require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+		require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 		assert.Equal(t, "hit", got.Result)
 		assert.Equal(t, keys[except], got.CacheKey)
 
@@ -530,7 +582,7 @@ func TestHandler(t *testing.T) {
 				ArchiveLocation string `json:"archiveLocation"`
 				CacheKey        string `json:"cacheKey"`
 			}{}
-			require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 			assert.Equal(t, "hit", got.Result)
 			assert.Equal(t, key, got.CacheKey)
 			assert.NotEqual(t, strings.ToLower(key), got.CacheKey)
@@ -554,7 +606,8 @@ func TestHandler(t *testing.T) {
 			_, err := rand.Read(contents[i])
 			require.NoError(t, err)
 			uploadCacheNormally(t, base, keys[i], version, contents[i])
-			time.Sleep(time.Second) // ensure CreatedAt of caches are different
+			// ensure CreatedAt of caches are different, in upload order
+			backdateCache(t, handler, keys[i], time.Duration(len(contents)-i)*time.Second)
 		}
 
 		reqKeys := strings.Join([]string{
@@ -578,7 +631,7 @@ func TestHandler(t *testing.T) {
 			ArchiveLocation string `json:"archiveLocation"`
 			CacheKey        string `json:"cacheKey"`
 		}{}
-		require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+		require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 		assert.Equal(t, keys[expect], got.CacheKey)
 
 		contentResp, err := testClient.Get(got.ArchiveLocation)
@@ -607,7 +660,8 @@ func TestHandler(t *testing.T) {
 			_, err := rand.Read(contents[i])
 			require.NoError(t, err)
 			uploadCacheNormally(t, base, keys[i], version, contents[i])
-			time.Sleep(time.Second) // ensure CreatedAt of caches are different
+			// ensure CreatedAt of caches are different, in upload order
+			backdateCache(t, handler, keys[i], time.Duration(len(contents)-i)*time.Second)
 		}
 
 		reqKeys := strings.Join([]string{
@@ -633,7 +687,7 @@ func TestHandler(t *testing.T) {
 			ArchiveLocation string `json:"archiveLocation"`
 			CacheKey        string `json:"cacheKey"`
 		}{}
-		require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+		require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 		assert.Equal(t, keys[expect], got.CacheKey)
 
 		contentResp, err := testClient.Get(got.ArchiveLocation)
@@ -646,7 +700,21 @@ func TestHandler(t *testing.T) {
 	})
 }
 
-func uploadCacheNormally(t *testing.T, base, key, version string, content []byte) { //nolint:unparam // pre-existing issue from nektos/act
+// backdateCache rewrites a cache's CreatedAt. It has one-second resolution, so age-ordering
+// tests set it directly instead of sleeping a second between uploads.
+func backdateCache(t *testing.T, handler *Handler, key string, age time.Duration) {
+	db, err := handler.openDB()
+	require.NoError(t, err)
+	defer db.Close()
+
+	var caches []*Cache
+	require.NoError(t, db.Find(&caches, bolthold.Where("Key").Eq(key)))
+	require.Len(t, caches, 1)
+	caches[0].CreatedAt = time.Now().Add(-age).Unix()
+	require.NoError(t, db.Update(caches[0].ID, caches[0]))
+}
+
+func uploadCacheNormally(t *testing.T, base, key, version string, content []byte) {
 	var id uint64
 	{
 		body, err := json.Marshal(&Request{
@@ -663,7 +731,7 @@ func uploadCacheNormally(t *testing.T, base, key, version string, content []byte
 		got := struct {
 			CacheID uint64 `json:"cacheId"`
 		}{}
-		require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+		require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 		id = got.CacheID
 	}
 	{
@@ -694,7 +762,7 @@ func uploadCacheNormally(t *testing.T, base, key, version string, content []byte
 			ArchiveLocation string `json:"archiveLocation"`
 			CacheKey        string `json:"cacheKey"`
 		}{}
-		require.NoError(t, json.NewDecoder(resp.Body).Decode(&got))
+		require.NoError(t, json.UnmarshalRead(resp.Body, &got))
 		assert.Equal(t, "hit", got.Result)
 		assert.Equal(t, key, got.CacheKey)
 		archiveLocation = got.ArchiveLocation
@@ -712,7 +780,7 @@ func uploadCacheNormally(t *testing.T, base, key, version string, content []byte
 
 func TestHandler_gcCache(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir, Policy: Policy{Retention: testRetention}})
 	require.NoError(t, err)
 
 	defer func() {
@@ -742,8 +810,8 @@ func TestHandler_gcCache(t *testing.T) {
 				Key:       "test_key_2",
 				Version:   "test_version",
 				Complete:  false,
-				UsedAt:    now.Add(-(keepTemp + time.Second)).Unix(),
-				CreatedAt: now.Add(-(keepTemp + time.Hour)).Unix(),
+				UsedAt:    now.Add(-(inUseGrace + time.Second)).Unix(),
+				CreatedAt: now.Add(-(inUseGrace + time.Hour)).Unix(),
 			},
 			Kept: false,
 		},
@@ -753,21 +821,21 @@ func TestHandler_gcCache(t *testing.T) {
 				Key:       "test_key_3",
 				Version:   "test_version",
 				Complete:  true,
-				UsedAt:    now.Add(-(keepUnused + time.Second)).Unix(),
-				CreatedAt: now.Add(-(keepUnused + time.Hour)).Unix(),
+				UsedAt:    now.Add(-(testRetention + touchStale + time.Second)).Unix(),
+				CreatedAt: now.Add(-(testRetention + time.Hour)).Unix(),
 			},
 			Kept: false,
 		},
 		{
-			// should be removed, since it's used but too old.
+			// should be kept, since age alone does not retire an entry that is still used.
 			Cache: &Cache{
 				Key:       "test_key_3",
 				Version:   "test_version",
 				Complete:  true,
 				UsedAt:    now.Unix(),
-				CreatedAt: now.Add(-(keepUsed + time.Second)).Unix(),
+				CreatedAt: now.Add(-365 * 24 * time.Hour).Unix(),
 			},
-			Kept: false,
+			Kept: true,
 		},
 		{
 			// should be kept, since it has a newer edition but be used recently.
@@ -775,7 +843,7 @@ func TestHandler_gcCache(t *testing.T) {
 				Key:       "test_key_1",
 				Version:   "test_version",
 				Complete:  true,
-				UsedAt:    now.Add(-(keepOld - time.Minute)).Unix(),
+				UsedAt:    now.Add(-(inUseGrace - time.Minute)).Unix(),
 				CreatedAt: now.Add(-(time.Hour + time.Second)).Unix(),
 			},
 			Kept: true,
@@ -786,7 +854,7 @@ func TestHandler_gcCache(t *testing.T) {
 				Key:       "test_key_1",
 				Version:   "test_version",
 				Complete:  true,
-				UsedAt:    now.Add(-(keepOld + time.Second)).Unix(),
+				UsedAt:    now.Add(-(inUseGrace + time.Second)).Unix(),
 				CreatedAt: now.Add(-(time.Hour + time.Second)).Unix(),
 			},
 			Kept: false,
@@ -796,7 +864,7 @@ func TestHandler_gcCache(t *testing.T) {
 	db, err := handler.openDB()
 	require.NoError(t, err)
 	for _, c := range cases {
-		require.NoError(t, insertCache(db, c.Cache))
+		require.NoError(t, handler.insertCache(db, c.Cache))
 	}
 	require.NoError(t, db.Close())
 
@@ -819,11 +887,289 @@ func TestHandler_gcCache(t *testing.T) {
 	require.NoError(t, db.Close())
 }
 
+// TestHandler_evictPolicy covers the non-default policies; TestHandler_gcCache covers the
+// defaults across every pass.
+func TestHandler_evictPolicy(t *testing.T) {
+	now := time.Now()
+	stale := func(d time.Duration) int64 { return now.Add(-d).Unix() }
+	mib := func(n int64) int64 { return n * miB }
+
+	for _, tc := range []struct {
+		name    string
+		policy  Policy
+		entries []*Cache
+		kept    []string
+	}{
+		{
+			name:   "a zero retention keeps an entry nothing has touched",
+			policy: Policy{Retention: 0},
+			entries: []*Cache{
+				{Key: "idle", UsedAt: stale(testRetention + time.Hour)},
+			},
+			kept: []string{"idle"},
+		},
+		{
+			name:   "evicts least recently accessed until the repository fits",
+			policy: Policy{RepoSizeLimit: mib(10)},
+			entries: []*Cache{
+				{Repo: "o/a", Key: "oldest", Size: mib(4), UsedAt: stale(3 * time.Hour)},
+				{Repo: "o/a", Key: "middle", Size: mib(4), UsedAt: stale(2 * time.Hour)},
+				{Repo: "o/a", Key: "newest", Size: mib(4), UsedAt: stale(time.Hour)},
+			},
+			kept: []string{"middle", "newest"},
+		},
+		{
+			name:   "spares entries that may still be downloading",
+			policy: Policy{RepoSizeLimit: mib(10)},
+			entries: []*Cache{
+				{Repo: "o/a", Key: "fresh_1", Size: mib(6), UsedAt: stale(time.Minute)},
+				{Repo: "o/a", Key: "fresh_2", Size: mib(6), UsedAt: stale(time.Minute)},
+			},
+			kept: []string{"fresh_1", "fresh_2"},
+		},
+		{
+			name:   "one repository over its limit leaves another alone",
+			policy: Policy{RepoSizeLimit: mib(10)},
+			entries: []*Cache{
+				{Repo: "o/a", Key: "a_old", Size: mib(6), UsedAt: stale(3 * time.Hour)},
+				{Repo: "o/a", Key: "a_new", Size: mib(6), UsedAt: stale(time.Hour)},
+				{Repo: "o/b", Key: "b_old", Size: mib(6), UsedAt: stale(4 * time.Hour)},
+			},
+			kept: []string{"a_new", "b_old"},
+		},
+		{
+			name:   "the total limit evicts across repositories once each fits its own",
+			policy: Policy{RepoSizeLimit: mib(10), SizeLimit: mib(12)},
+			entries: []*Cache{
+				{Repo: "o/a", Key: "a_old", Size: mib(8), UsedAt: stale(3 * time.Hour)},
+				{Repo: "o/b", Key: "b_new", Size: mib(8), UsedAt: stale(time.Hour)},
+			},
+			kept: []string{"b_new"},
+		},
+		{
+			// Retention below inUseGrace would otherwise drop an entry whose signed URL a job
+			// is still holding.
+			name:   "a retention shorter than the grace still spares a just-served entry",
+			policy: Policy{Retention: time.Minute},
+			entries: []*Cache{
+				{Key: "just_served", UsedAt: stale(2 * time.Minute)},
+				{Key: "idle", UsedAt: stale(time.Hour)},
+			},
+			kept: []string{"just_served"},
+		},
+		{
+			name:   "an entry over the limit goes without emptying the repository",
+			policy: Policy{RepoSizeLimit: mib(10)},
+			entries: []*Cache{
+				{Repo: "o/a", Key: "keeps", Size: mib(4), UsedAt: stale(3 * time.Hour)},
+				{Repo: "o/a", Key: "huge", Size: mib(20), UsedAt: stale(2 * time.Hour)},
+			},
+			kept: []string{"keeps"},
+		},
+		{
+			name:   "a zero limit keeps everything",
+			policy: Policy{RepoSizeLimit: 0},
+			entries: []*Cache{
+				{Repo: "o/a", Key: "huge_1", Size: mib(100), UsedAt: stale(3 * time.Hour)},
+				{Repo: "o/a", Key: "huge_2", Size: mib(100), UsedAt: stale(2 * time.Hour)},
+			},
+			kept: []string{"huge_1", "huge_2"},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			for _, e := range tc.entries {
+				e.Complete = true // only completed entries carry a measured size, so only they count
+			}
+			handler := newTestHandler(t, tc.policy, tc.entries...)
+			handler.gcAt = time.Time{} // ensure gcCache will not skip
+			handler.gcCache()
+			assert.ElementsMatch(t, tc.kept, keptKeys(t, handler, tc.entries))
+		})
+	}
+}
+
+// TestHandler_evictForFreeSpace proves the volume backstop sheds only what it must, and only
+// when the disk is actually short.
+func TestHandler_evictForFreeSpace(t *testing.T) {
+	free := func(n int64) func(string) (uint64, error) {
+		return func(string) (uint64, error) { return uint64(n), nil }
+	}
+
+	for _, tc := range []struct {
+		name     string
+		freeDisk func(string) (uint64, error)
+		kept     []string
+	}{
+		{"ample free space evicts nothing", free(defaultMinFreeDisk), []string{"oldest", "middle", "newest"}},
+		{"a small shortfall sheds one entry", free(defaultMinFreeDisk - 4*miB), []string{"middle", "newest"}},
+		{"a shortfall the cache cannot cover sheds all of it", free(0), nil},
+		{
+			"an unreadable volume is treated as unavailable, not as full",
+			func(string) (uint64, error) { return 0, errors.New("unsupported") },
+			[]string{"oldest", "middle", "newest"},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			now := time.Now()
+			entries := []*Cache{
+				{Key: "oldest", Complete: true, Size: 4 * miB, UsedAt: now.Add(-3 * time.Hour).Unix()},
+				{Key: "middle", Complete: true, Size: 4 * miB, UsedAt: now.Add(-2 * time.Hour).Unix()},
+				{Key: "newest", Complete: true, Size: 4 * miB, UsedAt: now.Add(-time.Hour).Unix()},
+			}
+			handler := newTestHandler(t, Policy{}, entries...)
+			handler.freeDisk = tc.freeDisk
+
+			db, err := handler.openDB()
+			require.NoError(t, err)
+			handler.evictForFreeSpace(db)
+			require.NoError(t, db.Close())
+
+			assert.ElementsMatch(t, tc.kept, keptKeys(t, handler, entries))
+		})
+	}
+}
+
+// TestHandler_SweepKeepsEntryWhenBlobSurvives proves a failed unlink leaves the row in place,
+// so the next sweep retries rather than orphaning bytes no row points at and no limit counts.
+func TestHandler_SweepKeepsEntryWhenBlobSurvives(t *testing.T) {
+	cache := &Cache{Key: "stuck", Complete: true, UsedAt: time.Now().Add(-(testRetention + time.Hour)).Unix()}
+	handler := newTestHandler(t, Policy{Retention: testRetention}, cache)
+
+	// A non-empty directory where the blob belongs makes os.Remove fail on every platform.
+	blob := handler.storage.(*Storage).filename(cache.ID)
+	require.NoError(t, os.MkdirAll(blob, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(blob, "held"), []byte("x"), 0o600))
+
+	handler.gcAt = time.Time{}
+	handler.gcCache()
+
+	assert.Equal(t, []string{"stuck"}, keptKeys(t, handler, []*Cache{cache}), "the entry must outlive a blob that could not be removed")
+}
+
+// TestHandler_FindProtectsFromEviction covers the window between a find handing out a signed
+// download URL and the GET that redeems it: the entry promised to a job must not be the next
+// eviction victim just because its last access predates the find.
+func TestHandler_FindProtectsFromEviction(t *testing.T) {
+	// 12 MiB against a 10 MiB limit, so exactly one entry has to go.
+	wanted := &Cache{Repo: testRepo, Key: "wanted", Version: "v", Complete: true, Size: 4 * miB, UsedAt: time.Now().Add(-3 * time.Hour).Unix()}
+	other := &Cache{Repo: testRepo, Key: "other", Version: "v", Complete: true, Size: 4 * miB, UsedAt: time.Now().Add(-2 * time.Hour).Unix()}
+	newest := &Cache{Repo: testRepo, Key: "newest", Version: "v", Complete: true, Size: 4 * miB, UsedAt: time.Now().Add(-time.Hour).Unix()}
+	handler := newTestHandler(t, Policy{RepoSizeLimit: 10 * miB}, wanted, other, newest)
+	writeBlob(t, handler, wanted.ID) // find only reports a hit when the blob is on disk
+
+	resp, err := testClient.Get(fmt.Sprintf("%s%s/cache?keys=wanted&version=v", handler.ExternalURL(), apiPath))
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	require.Equal(t, 200, resp.StatusCode)
+
+	// Evict directly: the request above kicked off an async gcCache, and writing gcAt here
+	// to drive gcCache would race its read.
+	db, err := handler.openDB()
+	require.NoError(t, err)
+	defer func() { require.NoError(t, db.Close()) }()
+	handler.evictOversized(db)
+
+	require.NoError(t, db.Get(wanted.ID, &Cache{}), "the entry just promised to a job must survive")
+	assert.ErrorIs(t, db.Get(other.ID, &Cache{}), bolthold.ErrNotFound, "the next least recently used goes instead")
+}
+
+// TestHandler_evictOnCommit proves a repository that goes over its limit gets space back at
+// once, rather than waiting out the collection interval.
+func TestHandler_evictOnCommit(t *testing.T) {
+	full := &Cache{Repo: testRepo, Key: "full", Version: "v", Complete: true, Size: 4 * miB, UsedAt: time.Now().Add(-time.Hour).Unix()}
+	handler := newTestHandler(t, Policy{RepoSizeLimit: 4 * miB}, full)
+
+	// StartHandler already stamped gcAt, so the periodic sweep stays rate-limited out and
+	// only the commit path can evict.
+	uploadCacheNormally(t, handler.ExternalURL()+apiPath, "new", "v", []byte("some content"))
+
+	assert.Empty(t, keptKeys(t, handler, []*Cache{full}))
+}
+
+func TestHandler_gcCacheInterval(t *testing.T) {
+	cache := &Cache{Key: "temp", UsedAt: time.Now().Add(-time.Hour).Unix()}
+	// Half the default, so a sweep 45m ago is still inside the default but past this one.
+	handler := newTestHandler(t, Policy{SweepInterval: 30 * time.Minute}, cache)
+
+	handler.gcAt = time.Now().Add(-45 * time.Minute) // past the configured interval, still inside the default
+	handler.gcCache()
+	assert.Empty(t, keptKeys(t, handler, []*Cache{cache}))
+}
+
+func TestHandler_touchCacheSkipsFreshCompletedEntries(t *testing.T) {
+	fresh := &Cache{Repo: testRepo, Key: "fresh", Version: "v", Complete: true, UsedAt: time.Now().Unix()}
+	pending := &Cache{Repo: testRepo, Key: "pending", Version: "v", UsedAt: time.Now().Add(-time.Second).Unix()}
+	handler := newTestHandler(t, Policy{}, fresh, pending)
+	txID := func() int {
+		db, err := handler.openDB()
+		require.NoError(t, err)
+		defer db.Close()
+		var id int
+		require.NoError(t, db.Bolt().View(func(tx *bbolt.Tx) error { id = tx.ID(); return nil }))
+		return id
+	}
+
+	before := txID()
+	require.NoError(t, handler.touchCache(fresh.ID, false))
+	assert.Equal(t, before, txID())
+	require.NoError(t, handler.touchCache(pending.ID, false))
+	assert.Greater(t, txID(), before)
+}
+
+// newTestHandler starts a handler with testToken registered, seeded with entries.
+func newTestHandler(t *testing.T, policy Policy, entries ...*Cache) *Handler {
+	t.Helper()
+	handler := startTestHandler(t, Options{Policy: policy})
+
+	db, err := handler.openDB()
+	require.NoError(t, err)
+	for _, e := range entries {
+		require.NoError(t, handler.insertCache(db, e))
+	}
+	require.NoError(t, db.Close())
+	return handler
+}
+
+func startTestHandler(t *testing.T, opts Options) *Handler {
+	t.Helper()
+	opts.Dir = filepath.Join(t.TempDir(), "artifactcache")
+	opts.OutboundIP = "127.0.0.1"
+	handler, err := StartHandler(opts)
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, handler.Close()) })
+	handler.RegisterJob(testToken, JobCredential{Repo: testRepo})
+	return handler
+}
+
+// keptKeys reports which of entries are still in the store.
+func keptKeys(t *testing.T, handler *Handler, entries []*Cache) []string {
+	t.Helper()
+	db, err := handler.openDB()
+	require.NoError(t, err)
+	defer func() { require.NoError(t, db.Close()) }()
+
+	var kept []string
+	for _, e := range entries {
+		if err := db.Get(e.ID, &Cache{}); err == nil {
+			kept = append(kept, e.Key)
+		}
+	}
+	return kept
+}
+
+// writeBlob gives an entry the on-disk bytes that find and get require.
+func writeBlob(t *testing.T, handler *Handler, id uint64) {
+	t.Helper()
+	require.NoError(t, handler.storage.Write(id, 0, strings.NewReader("a")))
+	_, err := handler.storage.Commit(id, 1)
+	require.NoError(t, err)
+}
+
 // TestHandler_RejectsMissingBearer covers the advisory's root cause:
 // unauthenticated access to management endpoints is now refused with 401.
 func TestHandler_RejectsMissingBearer(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
 
@@ -856,7 +1202,7 @@ func TestHandler_RejectsMissingBearer(t *testing.T) {
 // accepted after RegisterJob; stale/forged tokens cannot be replayed.
 func TestHandler_RejectsUnknownBearer(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
 
@@ -876,11 +1222,11 @@ func TestHandler_RejectsUnknownBearer(t *testing.T) {
 // working the moment the job ends instead of living for the runner's lifetime.
 func TestHandler_UnregisterRevokes(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
 
-	unregister := handler.RegisterJob("tmp-token", testRepo)
+	unregister := handler.RegisterJob("tmp-token", JobCredential{Repo: testRepo})
 
 	base := handler.ExternalURL() + apiPath
 	req, err := http.NewRequest(http.MethodGet, base+"/cache?keys=x&version=y", nil)
@@ -907,11 +1253,11 @@ func TestHandler_UnregisterRevokes(t *testing.T) {
 // invisible to queries scoped to repoB.
 func TestHandler_CrossRepoIsolation(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
-	handler.RegisterJob("token-a", "owner/repoA")
-	handler.RegisterJob("token-b", "owner/repoB")
+	handler.RegisterJob("token-a", JobCredential{Repo: "owner/repoA"})
+	handler.RegisterJob("token-b", JobCredential{Repo: "owner/repoB"})
 
 	base := handler.ExternalURL() + apiPath
 	key := "shared-key"
@@ -929,7 +1275,7 @@ func TestHandler_CrossRepoIsolation(t *testing.T) {
 	var reserved struct {
 		CacheID uint64 `json:"cacheId"`
 	}
-	require.NoError(t, json.NewDecoder(resp.Body).Decode(&reserved))
+	require.NoError(t, json.UnmarshalRead(resp.Body, &reserved))
 	resp.Body.Close()
 	require.NotZero(t, reserved.CacheID)
 
@@ -973,10 +1319,10 @@ func TestHandler_CrossRepoIsolation(t *testing.T) {
 // working after artifactURLTTL even if the bearer token is still registered.
 func TestHandler_ArtifactSignature(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
-	handler.RegisterJob(testToken, testRepo)
+	handler.RegisterJob(testToken, JobCredential{Repo: testRepo})
 
 	base := handler.ExternalURL() + apiPath
 
@@ -988,7 +1334,7 @@ func TestHandler_ArtifactSignature(t *testing.T) {
 	})
 
 	t.Run("tampered signature", func(t *testing.T) {
-		good := handler.signedArtifactURL(1, time.Now().Add(artifactURLTTL))
+		good := signArtifactURL(handler, 1)
 		bad := good[:len(good)-4] + "dead"
 		resp, err := testClient.Get(bad)
 		require.NoError(t, err)
@@ -997,7 +1343,7 @@ func TestHandler_ArtifactSignature(t *testing.T) {
 	})
 
 	t.Run("expired signature", func(t *testing.T) {
-		expired := handler.signedArtifactURL(1, time.Now().Add(-time.Second))
+		expired := handler.signedArtifactURL(JobCredential{}, 1, time.Now().Add(-time.Second))
 		resp, err := testClient.Get(expired)
 		require.NoError(t, err)
 		resp.Body.Close()
@@ -1006,10 +1352,10 @@ func TestHandler_ArtifactSignature(t *testing.T) {
 
 	t.Run("signature from a different server", func(t *testing.T) {
 		dir2 := filepath.Join(t.TempDir(), "artifactcache2")
-		other, err := StartHandler(dir2, "", 0, "", nil)
+		other, err := StartHandler(Options{Dir: dir2})
 		require.NoError(t, err)
 		defer other.Close()
-		otherURL := other.signedArtifactURL(1, time.Now().Add(artifactURLTTL))
+		otherURL := signArtifactURL(other, 1)
 		// Rewrite the host so the request still lands on our handler, but
 		// the signature was computed with a different secret.
 		parts := strings.SplitN(otherURL, apiPath, 2)
@@ -1028,17 +1374,17 @@ func TestHandler_ArtifactSignature(t *testing.T) {
 func TestHandler_SecretPersistsAcrossRestarts(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
 
-	first, err := StartHandler(dir, "127.0.0.1", 0, "", nil)
+	first, err := StartHandler(Options{Dir: dir, OutboundIP: "127.0.0.1"})
 	require.NoError(t, err)
 	exp := time.Now().Add(artifactURLTTL).Unix()
-	sig := first.computeSignature(42, exp)
+	sig := first.computeSignature("", 42, exp)
 	require.NoError(t, first.Close())
 
-	second, err := StartHandler(dir, "127.0.0.1", 0, "", nil)
+	second, err := StartHandler(Options{Dir: dir, OutboundIP: "127.0.0.1"})
 	require.NoError(t, err)
 	defer second.Close()
 
-	assert.Equal(t, sig, second.computeSignature(42, exp))
+	assert.Equal(t, sig, second.computeSignature("", 42, exp))
 }
 
 // TestHandler_ArtifactSignatureDownload is a happy-path round trip that
@@ -1046,10 +1392,10 @@ func TestHandler_SecretPersistsAcrossRestarts(t *testing.T) {
 // the auth refactor.
 func TestHandler_ArtifactSignatureDownload(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
-	handler.RegisterJob(testToken, testRepo)
+	handler.RegisterJob(testToken, JobCredential{Repo: testRepo})
 
 	base := handler.ExternalURL() + apiPath
 	key := "download-key"
@@ -1063,7 +1409,7 @@ func TestHandler_ArtifactSignatureDownload(t *testing.T) {
 	var hit struct {
 		ArchiveLocation string `json:"archiveLocation"`
 	}
-	require.NoError(t, json.NewDecoder(resp.Body).Decode(&hit))
+	require.NoError(t, json.UnmarshalRead(resp.Body, &hit))
 	resp.Body.Close()
 
 	require.Contains(t, hit.ArchiveLocation, "sig=")
@@ -1086,12 +1432,12 @@ func TestHandler_ArtifactSignatureDownload(t *testing.T) {
 // (restart mid-task, retry), which must not kill the live job's auth.
 func TestHandler_RegisterJob_RefCounted(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
 
-	first := handler.RegisterJob("shared", testRepo)
-	second := handler.RegisterJob("shared", testRepo)
+	first := handler.RegisterJob("shared", JobCredential{Repo: testRepo})
+	second := handler.RegisterJob("shared", JobCredential{Repo: testRepo})
 
 	base := handler.ExternalURL() + apiPath
 	probe := func() int {
@@ -1115,14 +1461,14 @@ func TestHandler_RegisterJob_RefCounted(t *testing.T) {
 
 // TestHandler_GC_PerRepoDedup ensures duplicate-pruning does not evict
 // another repo's entry. Two repos reserve the same (key, version); after the
-// keepOld window, GC must keep the one from each repo.
+// inUseGrace window, GC must keep the one from each repo.
 func TestHandler_GC_PerRepoDedup(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
-	handler.RegisterJob("tok-a", "owner/repoA")
-	handler.RegisterJob("tok-b", "owner/repoB")
+	handler.RegisterJob("tok-a", JobCredential{Repo: "owner/repoA"})
+	handler.RegisterJob("tok-b", JobCredential{Repo: "owner/repoB"})
 
 	key := "shared-dedup-key"
 	version := "c19da02a2bd7e77277f1ac29ab45c09b7d46a4ee758284e26bb3045ad11d9d20"
@@ -1132,11 +1478,11 @@ func TestHandler_GC_PerRepoDedup(t *testing.T) {
 	db, err := handler.openDB()
 	require.NoError(t, err)
 	now := time.Now().Unix()
-	stale := time.Now().Add(-keepOld - time.Minute).Unix()
+	stale := time.Now().Add(-inUseGrace - time.Minute).Unix()
 	a := &Cache{Repo: "owner/repoA", Key: key, Version: version, Complete: true, CreatedAt: stale, UsedAt: stale, Size: 1}
 	b := &Cache{Repo: "owner/repoB", Key: key, Version: version, Complete: true, CreatedAt: now, UsedAt: now, Size: 1}
-	require.NoError(t, insertCache(db, a))
-	require.NoError(t, insertCache(db, b))
+	require.NoError(t, handler.insertCache(db, a))
+	require.NoError(t, handler.insertCache(db, b))
 	// Write the backing blobs so the dedup deletion has something to remove.
 	require.NoError(t, handler.storage.Write(a.ID, 0, strings.NewReader("a")))
 	_, err = handler.storage.Commit(a.ID, 1)
@@ -1169,7 +1515,7 @@ func TestHandler_GC_PerRepoDedup(t *testing.T) {
 // register/revoke when the feature is off.
 func TestHandler_InternalAPI_Disabled(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
-	handler, err := StartHandler(dir, "", 0, "", nil)
+	handler, err := StartHandler(Options{Dir: dir})
 	require.NoError(t, err)
 	defer handler.Close()
 
@@ -1187,7 +1533,7 @@ func TestHandler_InternalAPI_Disabled(t *testing.T) {
 func TestHandler_InternalAPI_AuthAndUsage(t *testing.T) {
 	dir := filepath.Join(t.TempDir(), "artifactcache")
 	const secret = "internal-secret"
-	handler, err := StartHandler(dir, "", 0, secret, nil)
+	handler, err := StartHandler(Options{Dir: dir, InternalSecret: secret})
 	require.NoError(t, err)
 	defer handler.Close()
 
@@ -1230,7 +1576,10 @@ func TestHandler_InternalAPI_AuthAndUsage(t *testing.T) {
 		}
 
 		assert.Equal(t, http.StatusUnauthorized, probe("via-internal-api"))
-		assert.Equal(t, http.StatusOK, post("/_internal/register", secret, `{"token":"via-internal-api","repo":"owner/repo"}`))
+		assert.Equal(t, http.StatusOK, post("/_internal/register", secret, `{"token":"via-internal-api","repo":"owner/repo","public_url":"http://runner.example","results":"https://gitea.example","insecure_tls":true}`))
+		cred, ok := handler.lookupCredential("via-internal-api")
+		require.True(t, ok)
+		assert.Equal(t, JobCredential{Repo: testRepo, PublicURL: "http://runner.example"}, cred)
 		assert.NotEqual(t, http.StatusUnauthorized, probe("via-internal-api"))
 		assert.Equal(t, http.StatusOK, post("/_internal/revoke", secret, `{"token":"via-internal-api"}`))
 		assert.Equal(t, http.StatusUnauthorized, probe("via-internal-api"))

act/artifactcache/handler_v2.go

@@ -0,0 +1,332 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifactcache
+
+import (
+	"cmp"
+	"encoding/json/jsontext"
+	"encoding/json/v2"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// The cache service v2 API. A client on this version talks twirp to
+// `github.actions.results.api.v1.CacheService` instead of the /_apis/artifactcache
+// endpoints, and uploads the archive to the returned URL with the Azure blob protocol.
+// Both API versions are served from the same store, so a repository keeps its cache
+// when a workflow moves between action versions.
+//
+// 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"
+
+	// blobPath authenticates by signature, because the client uploads without an
+	// Authorization header. Downloads are handed the v1 artifact URL instead.
+	blobPath = apiPath + "/blobs"
+
+	// blobUploadPurpose keeps an upload URL from being replayed to read an entry.
+	blobUploadPurpose = "upload:"
+
+	blobUploadURLTTL = time.Hour
+
+	twirpInternal        = "internal"
+	twirpUnavailable     = "unavailable"
+	twirpUnauthenticated = "unauthenticated"
+)
+
+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) {
+	cred := credFromContext(r.Context())
+	req, err := decodeTwirpRequest[v2CreateRequest](r)
+	if err != nil {
+		h.twirpError(w, r, "malformed", err)
+		return
+	}
+	if req.Key == "" || req.Version == "" {
+		h.twirpError(w, r, "invalid_argument", errors.New("key and version are required"))
+		return
+	}
+
+	db, err := h.openDB()
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	defer db.Close()
+
+	// An exact (key, version) match means the entry is already cached; the client then skips
+	// the upload. A prefix match must not count here, or a shorter key would be reported as
+	// existing and silently never saved.
+	if existing, err := findExactCache(db, cred.Repo, req.Key, req.Version, true); err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	} else if existing != nil {
+		h.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
+	}
+
+	// A second live reservation is finalized by whichever job calls last, against the other's upload.
+	owner := hashedToken(bearerToken(r))
+	if pending, err := findExactCache(db, cred.Repo, req.Key, req.Version, false); err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	} else if pending != nil && pending.UsedAt > time.Now().Add(-uploadStallTimeout).Unix() {
+		if pending.Owner != owner {
+			h.twirpNotOK(w, r)
+			return
+		}
+		h.touch(db, pending)                                // still uploading, so it must not go stale under the sweep
+		h.responseJSON(w, r, http.StatusOK, map[string]any{ // this job retrying its own reservation
+			"ok":                true,
+			"signed_upload_url": h.signedURL(cred, blobPath, blobUploadPurpose, pending.ID, time.Now().Add(blobUploadURLTTL)),
+		})
+		return
+	}
+
+	now := time.Now().Unix()
+	cache := &Cache{
+		Repo:      cred.Repo,
+		Key:       req.Key,
+		Version:   req.Version,
+		Owner:     owner,
+		Size:      -1, // the size is only known at finalize time
+		CreatedAt: now,
+		UsedAt:    now,
+	}
+	if err := h.insertCache(db, cache); err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+
+	h.responseJSON(w, r, http.StatusOK, map[string]any{
+		"ok":                true,
+		"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.Repo, req.Key, req.Version, false)
+	if err == nil && cache != nil && cache.Owner != hashedToken(bearerToken(r)) {
+		cache = nil // not the reservation this job made, so not this job's to commit
+	}
+	if err == nil && cache == nil {
+		// A retry whose first response was lost finds the entry already committed.
+		cache, err = findExactCache(db, cred.Repo, req.Key, req.Version, true)
+	}
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	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.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,
+		"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) {
+	id, err := strconv.ParseUint(r.PathValue("id"), 10, 64)
+	if err != nil {
+		h.responseJSON(w, r, http.StatusBadRequest, err)
+		return
+	}
+
+	if err := h.touchCache(id, true); err != nil {
+		h.responseJSON(w, r, http.StatusBadRequest, err)
+		return
+	}
+
+	query := r.URL.Query()
+	switch strings.ToLower(query.Get("comp")) {
+	case "block":
+		blockID := query.Get("blockid")
+		if blockID == "" {
+			h.responseJSON(w, r, http.StatusBadRequest, errors.New("missing blockid"))
+			return
+		}
+		err = h.storage.WriteBlock(id, blockID, r.Body)
+	case "blocklist":
+		var list struct{ Latest []string }
+		if err := xml.NewDecoder(io.LimitReader(r.Body, 8<<20)).Decode(&list); err != nil {
+			h.responseJSON(w, r, http.StatusBadRequest, fmt.Errorf("malformed block list: %w", err))
+			return
+		}
+		err = h.storage.OrderBlocks(id, list.Latest)
+	default:
+		err = h.storage.Write(id, 0, r.Body)
+	}
+	if err != nil {
+		h.responseJSON(w, r, http.StatusInternalServerError, err)
+		return
+	}
+
+	// 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)
+}
+
+// twirpNotOK is the negative answer all three endpoints share: no such entry to restore, no
+// reservation to finalize, or an entry that already exists and need not be uploaded again.
+func (h *Handler) twirpNotOK(w http.ResponseWriter, r *http.Request) {
+	h.responseJSON(w, r, http.StatusOK, map[string]any{"ok": false})
+}
+
+// twirpError reports in the shape a twirp client expects, so the toolkit surfaces the message
+// instead of a parse error.
+func (h *Handler) twirpError(w http.ResponseWriter, r *http.Request, code string, err error) {
+	h.logger.Debugf("%s %s: %v", r.Method, r.URL.Path, err)
+	status := http.StatusBadRequest
+	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()})
+}
+
+// The twirp request bodies. The toolkit's client serialises with useProtoFieldName, so the proto
+// names are what arrive; the camelCase spellings of the same mapping are accepted too, as are
+// int64s sent as a bare number rather than the string the mapping prescribes.
+type (
+	v2CreateRequest struct {
+		Key     string `json:"key"`
+		Version string `json:"version"`
+	}
+
+	v2FinalizeRequest struct {
+		Key            string     `json:"key"`
+		Version        string     `json:"version"`
+		SizeBytes      twirpInt64 `json:"size_bytes"`
+		SizeBytesCamel twirpInt64 `json:"sizeBytes"`
+	}
+
+	v2DownloadRequest struct {
+		Key              string   `json:"key"`
+		Version          string   `json:"version"`
+		RestoreKeys      []string `json:"restore_keys"`
+		RestoreKeysCamel []string `json:"restoreKeys"`
+	}
+)
+
+// 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 {
+		restoreKeys = d.RestoreKeysCamel
+	}
+	return append([]string{d.Key}, restoreKeys...)
+}
+
+func decodeTwirpRequest[T any](r *http.Request) (T, error) {
+	var req T
+	err := json.UnmarshalRead(io.LimitReader(r.Body, 1<<20), &req)
+	return req, err
+}

act/artifactcache/handler_v2_test.go

@@ -0,0 +1,353 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package artifactcache
+
+import (
+	"bytes"
+	"encoding/base64"
+	"encoding/json/v2"
+	"fmt"
+	"io"
+	"net/http"
+	"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()
+
+	body, err := json.Marshal(request)
+	require.NoError(t, err)
+
+	resp, err := client.Post(handler.ExternalURL()+cacheServiceV2Path+"/"+method, "application/json", bytes.NewReader(body))
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	got := map[string]any{}
+	require.NoError(t, json.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()
+
+	req, err := http.NewRequestWithContext(t.Context(), http.MethodPut, url, bytes.NewReader(content))
+	require.NoError(t, err)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusCreated {
+		// The Azure SDK client dereferences this header without checking, so a blob upload that
+		// omits it panics the caller rather than failing it.
+		require.NotEmpty(t, resp.Header.Get("x-ms-request-id"))
+	}
+	return resp.StatusCode
+}
+
+func getURL(t *testing.T, url string) []byte {
+	t.Helper()
+
+	req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, url, nil)
+	require.NoError(t, err)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	return body
+}
+
+// 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["signed_upload_url"].(string)
+	require.NotEmpty(t, uploadURL)
+	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL, content))
+
+	return v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+		"key": key, "version": version,
+		"size_bytes": strconv.Itoa(len(content)),
+	}), uploadURL
+}
+
+// The whole round trip an actions/cache v2 client makes, plus the guarantees on the signed
+// URLs it is handed: unsigned requests are refused, an upload URL cannot be replayed to read
+// or to replace a finalized entry.
+func TestCacheServiceV2RoundTrip(t *testing.T) {
+	handler := newTestHandler(t, Policy{})
+	content := []byte("the cached archive")
+
+	unsigned := fmt.Sprintf("%s%s/1", handler.ExternalURL(), blobPath)
+	assert.Equal(t, http.StatusUnauthorized, putBlob(t, unsigned, content))
+
+	finalized, uploadURL := saveV2(t, handler, "deps-v1", "abc123", content)
+	require.Equal(t, true, finalized["ok"])
+	assert.NotEmpty(t, finalized["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
+	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["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 := newTestHandler(t, Policy{})
+
+	created := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "blocks", "version": "v1"})
+	uploadURL, _ := created["signed_upload_url"].(string)
+	require.NotEmpty(t, uploadURL)
+
+	blocks := map[string][]byte{}
+	var order []string
+	for i, part := range []string{"hello ", "world", "!"} {
+		blockID := base64.StdEncoding.EncodeToString(fmt.Appendf(nil, "block-%d", i))
+		blocks[blockID] = []byte(part)
+		order = append(order, blockID)
+	}
+	// Upload in an order that is not the block list order.
+	for _, blockID := range []string{order[2], order[0], order[1]} {
+		require.Equal(t, http.StatusCreated, putBlob(t, uploadURL+"&comp=block&blockid="+blockID, blocks[blockID]))
+	}
+
+	var list bytes.Buffer
+	list.WriteString(`<?xml version="1.0" encoding="utf-8"?><BlockList>`)
+	for _, blockID := range order {
+		fmt.Fprintf(&list, "<Latest>%s</Latest>", blockID)
+	}
+	list.WriteString(`</BlockList>`)
+	require.Equal(t, http.StatusCreated, putBlob(t, uploadURL+"&comp=blocklist", list.Bytes()))
+	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!"),
+	})
+	require.Equal(t, true, finalized["ok"])
+
+	got := v2Call(t, handler, testClient, "GetCacheEntryDownloadURL", map[string]any{"key": "blocks", "version": "v1"})
+	require.Equal(t, true, got["ok"])
+	assert.Equal(t, "hello world!", string(getURL(t, got["signed_download_url"].(string))))
+}
+
+func TestCacheServiceV2Lookups(t *testing.T) {
+	handler := newTestHandler(t, Policy{})
+	saved, _ := saveV2(t, handler, "deps-abc", "v1", []byte("x"))
+	require.Equal(t, true, saved["ok"])
+
+	t.Run("reports a miss for an unknown key", func(t *testing.T) {
+		got := v2Call(t, handler, testClient, "GetCacheEntryDownloadURL", map[string]any{"key": "nothing", "version": "v1"})
+		assert.Equal(t, false, got["ok"])
+	})
+
+	// The toolkit serialises with the proto field names; the camelCase spellings of the same
+	// proto JSON mapping are accepted alongside them.
+	for _, field := range []string{"restore_keys", "restoreKeys"} {
+		t.Run("restore keys match by prefix, spelled "+field, func(t *testing.T) {
+			got := v2Call(t, handler, testClient, "GetCacheEntryDownloadURL", map[string]any{
+				"key": "deps-zzz", field: []string{"deps-"}, "version": "v1",
+			})
+			require.Equal(t, true, got["ok"])
+			assert.Equal(t, "deps-abc", got["matched_key"])
+		})
+	}
+
+	t.Run("an existing entry is not reserved twice", func(t *testing.T) {
+		again := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "deps-abc", "version": "v1"})
+		assert.Equal(t, false, again["ok"])
+	})
+
+	// A key that is only a prefix of an existing one is a different entry, so the
+	// reservation check must be exact and not a restore-key prefix match, or the shorter
+	// key would be reported as existing and silently never saved.
+	t.Run("a prefix of an existing key is still reserved", func(t *testing.T) {
+		reserved := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "deps", "version": "v1"})
+		require.Equal(t, true, reserved["ok"])
+		assert.NotEmpty(t, reserved["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) {
+		got := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+			"key": "never-reserved", "version": "v1", "size_bytes": 1,
+		})
+		assert.Equal(t, false, got["ok"])
+	})
+
+	// The size the client declares is what Commit validates the assembled archive against.
+	t.Run("finalizing with the wrong size is not ok", func(t *testing.T) {
+		created := v2Call(t, handler, testClient, "CreateCacheEntry", map[string]any{"key": "wrong-size", "version": "v1"})
+		require.Equal(t, http.StatusCreated, putBlob(t, created["signed_upload_url"].(string), []byte("four")))
+
+		got := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+			"key": "wrong-size", "version": "v1", "size_bytes": 99,
+		})
+		assert.Equal(t, false, got["ok"])
+	})
+
+	// Both API versions are served from one store, so an entry written through v2 is a hit for
+	// a v1 client asking for the same key and version.
+	t.Run("a v1 client sees an entry written through v2", func(t *testing.T) {
+		resp, err := testClient.Get(fmt.Sprintf("%s%s/cache?keys=deps-abc&version=v1", handler.ExternalURL(), apiPath))
+		require.NoError(t, err)
+		defer resp.Body.Close()
+		require.Equal(t, http.StatusOK, resp.StatusCode)
+
+		got := map[string]any{}
+		require.NoError(t, json.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", 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"])
+	})
+}
+
+func TestCacheServiceV2RefusalsAreTwirp(t *testing.T) {
+	handler := newTestHandler(t, Policy{})
+
+	tests := []struct {
+		name   string
+		token  string
+		body   string
+		status int
+		code   string
+	}{
+		{"no bearer at all", "", `{"key":"k","version":"v"}`, http.StatusUnauthorized, twirpUnauthenticated},
+		{"a bearer nobody registered", "not-a-job", `{"key":"k","version":"v"}`, http.StatusUnauthorized, twirpUnauthenticated},
+		{"a body that is not the request", testToken, `{`, http.StatusBadRequest, "malformed"},
+		{"a request missing its key", testToken, `{"version":"v"}`, http.StatusBadRequest, "invalid_argument"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req, err := http.NewRequestWithContext(t.Context(), http.MethodPost,
+				handler.ExternalURL()+cacheServiceV2Path+"/CreateCacheEntry", strings.NewReader(tt.body))
+			require.NoError(t, err)
+			if tt.token != "" {
+				req.Header.Set("Authorization", "Bearer "+tt.token)
+			}
+			resp, err := http.DefaultClient.Do(req)
+			require.NoError(t, err)
+			defer resp.Body.Close()
+
+			require.Equal(t, tt.status, resp.StatusCode)
+			got := map[string]string{}
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
+			assert.Equal(t, tt.code, got["code"])
+			assert.NotEmpty(t, got["msg"])
+		})
+	}
+}
+
+func TestCacheServiceV2ConcurrentSaveAndRetries(t *testing.T) {
+	handler := newTestHandler(t, Policy{})
+	content := []byte("the cached archive")
+
+	const otherJob = "another-jobs-token"
+	defer handler.RegisterJob(otherJob, JobCredential{Repo: testRepo})()
+	reserve := func(client *http.Client) map[string]any {
+		return v2Call(t, handler, client, "CreateCacheEntry", map[string]any{"key": "shared", "version": "v1"})
+	}
+	first := reserve(testClient)
+	require.Equal(t, true, first["ok"])
+	retry := reserve(testClient)
+	assert.Equal(t, true, retry["ok"], "a job retrying its own reservation is not a conflict")
+	entryOf := func(reserved map[string]any) string {
+		parsed, err := url.Parse(reserved["signed_upload_url"].(string))
+		require.NoError(t, err)
+		return parsed.Path
+	}
+	assert.Equal(t, entryOf(first), entryOf(retry), "the same reservation, however freshly its URL is signed")
+	assert.Equal(t, false, reserve(&http.Client{Transport: &bearerTransport{token: otherJob}})["ok"],
+		"another job's reservation would be finalized against the first upload")
+
+	otherClient := &http.Client{Transport: &bearerTransport{token: otherJob}}
+	reserved := v2Call(t, handler, otherClient, "CreateCacheEntry", map[string]any{"key": "owned", "version": "v1"})
+	require.Equal(t, true, reserved["ok"])
+	require.Equal(t, http.StatusCreated, putBlob(t, reserved["signed_upload_url"].(string), content))
+	assert.Equal(t, false, v2Call(t, handler, testClient, "FinalizeCacheEntryUpload",
+		map[string]any{"key": "owned", "version": "v1", "size_bytes": strconv.Itoa(len(content))})["ok"],
+		"another job's upload is not this job's to finalize")
+
+	base := handler.ExternalURL() + apiPath
+	reserveV1, err := json.Marshal(&Request{Key: "v1-made", Version: "v1", Size: int64(len(content))})
+	require.NoError(t, err)
+	resp, err := testClient.Post(base+"/caches", "application/json", bytes.NewReader(reserveV1))
+	require.NoError(t, err)
+	var madeByV1 struct {
+		CacheID uint64 `json:"cacheId"`
+	}
+	require.NoError(t, json.UnmarshalRead(resp.Body, &madeByV1))
+	resp.Body.Close()
+	upload, err := http.NewRequestWithContext(t.Context(), http.MethodPatch,
+		fmt.Sprintf("%s/caches/%d", base, madeByV1.CacheID), bytes.NewReader(content))
+	require.NoError(t, err)
+	upload.Header.Set("Content-Range", fmt.Sprintf("bytes 0-%d/*", len(content)-1))
+	resp, err = testClient.Do(upload)
+	require.NoError(t, err)
+	resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	assert.Equal(t, false, v2Call(t, handler, testClient, "FinalizeCacheEntryUpload",
+		map[string]any{"key": "v1-made", "version": "v1", "size_bytes": strconv.Itoa(len(content))})["ok"],
+		"a reservation this job did not make through v2 is not its to commit")
+
+	finalized, _ := saveV2(t, handler, "deps", "v1", content)
+	require.Equal(t, true, finalized["ok"])
+	again := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+		"key": "deps", "version": "v1", "size_bytes": strconv.Itoa(len(content)),
+	})
+	assert.Equal(t, true, again["ok"], "a retry whose first answer was lost must not report a failed save")
+	assert.Equal(t, finalized["entry_id"], again["entry_id"])
+}

act/artifactcache/model.go

@@ -10,29 +10,13 @@ type Request struct {
 	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" boltholdKey:"ID"`
 	Repo      string `json:"repo" boltholdIndex:"Repo"`
 	Key       string `json:"key" boltholdIndex:"Key"`
 	Version   string `json:"version" boltholdIndex:"Version"`
 	Size      int64  `json:"cacheSize"`
+	Owner     string `json:"owner"` // hashed bearer, so a job's own retry is not another job's reservation
 	Complete  bool   `json:"complete" boltholdIndex:"Complete"`
 	UsedAt    int64  `json:"usedAt" boltholdIndex:"UsedAt"`
 	CreatedAt int64  `json:"createdAt" boltholdIndex:"CreatedAt"`

act/artifactcache/results.go

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

act/artifactcache/s3_storage_test.go

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

act/artifactcache/storage.go

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

act/artifacts/server.go

@@ -6,11 +6,12 @@ package artifacts
 
 import (
 	"context"
-	"encoding/json"
+	"encoding/json/v2"
 	"errors"
 	"fmt"
 	"io"
 	"io/fs"
+	"net"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -18,8 +19,6 @@ import (
 	"time"
 
 	"gitea.com/gitea/runner/act/common"
-
-	"github.com/julienschmidt/httprouter"
 )
 
 type FileContainerResourceURL struct {
@@ -50,139 +49,80 @@ 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)
+		safeRunPath := safeResolve(baseDir, req.PathValue("runId"))
 		safePath := safeResolve(safeRunPath, itemPath)
 
-		file, err := func() (WritableFile, error) {
-			contentRange := req.Header.Get("Content-Range")
-			if contentRange != "" && !strings.HasPrefix(contentRange, "bytes 0-") {
-				return fsys.OpenAppendable(safePath)
-			}
-			return fsys.OpenWritable(safePath)
-		}()
+		if err := os.MkdirAll(filepath.Dir(safePath), os.ModePerm); err != nil {
+			panic(err)
+		}
+		flags := os.O_CREATE | os.O_WRONLY | os.O_TRUNC
+		appendUpload := req.Header.Get("Content-Range")
+		if appendUpload != "" && !strings.HasPrefix(appendUpload, "bytes 0-") {
+			flags = os.O_CREATE | os.O_WRONLY | os.O_APPEND
+		}
+		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 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)
+		entries, err := os.ReadDir(safePath)
 		if err != nil {
 			panic(err)
 		}
@@ -195,27 +135,19 @@ 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 !entry.IsDir() {
 				rel, err := filepath.Rel(safePath, path)
 				if err != nil {
@@ -241,33 +173,24 @@ func downloads(router *httprouter.Router, baseDir string, fsys fs.FS) {
 			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 +207,24 @@ 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)
 
 	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

@@ -5,324 +5,160 @@
 package artifacts
 
 import (
-	"context"
-	"encoding/json"
-	"fmt"
+	"bytes"
+	"compress/gzip"
+	"encoding/json/v2"
+	"io"
+	"maps"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"os"
-	"path"
 	"path/filepath"
 	"strings"
 	"testing"
-	"testing/fstest"
+	"time"
 
-	"gitea.com/gitea/runner/act/model"
-	"gitea.com/gitea/runner/act/runner"
-
-	"github.com/julienschmidt/httprouter"
-	log "github.com/sirupsen/logrus"
-	"github.com/stretchr/testify/assert"
-)
-
-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))
-}
-
-type TestJobFileInfo struct {
-	workdir               string
-	workflowPath          string
-	eventName             string
-	errorMessage          string
-	platforms             map[string]string
-	containerArchitecture string
-}
-
-var (
-	artifactsPath = path.Join(os.TempDir(), "test-artifacts")
-	artifactsAddr = "127.0.0.1"
-	artifactsPort = "12345"
+	"github.com/stretchr/testify/require"
 )
 
 func TestArtifactFlow(t *testing.T) {
-	if testing.Short() {
-		t.Skip("skipping integration test")
+	artifactPath := t.TempDir()
+
+	router := http.NewServeMux()
+	uploads(router, artifactPath)
+	downloads(router, artifactPath)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	baseURL := server.URL
+	client := server.Client()
+	client.Timeout = 5 * time.Second
+
+	request := func(t *testing.T, method, rawURL string, body io.Reader, header http.Header) (int, []byte) {
+		t.Helper()
+		req, err := http.NewRequest(method, rawURL, body)
+		require.NoError(t, err)
+		maps.Copy(req.Header, header)
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+		data, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		return resp.StatusCode, data
 	}
 
-	ctx := context.Background()
+	t.Run("upload-and-download", func(t *testing.T) {
+		const runID, item, content = "1", "my-artifact/data.txt", "hello artifact\n"
 
-	cancel := Serve(ctx, artifactsPath, artifactsAddr, artifactsPort)
-	defer cancel()
+		status, data := request(t, http.MethodPost, baseURL+"/_apis/pipelines/workflows/"+runID+"/artifacts", nil, nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+		var prep FileContainerResourceURL
+		require.NoError(t, json.Unmarshal(data, &prep))
+		require.Equal(t, baseURL+"/upload/"+runID, prep.FileContainerResourceURL)
 
-	platforms := map[string]string{
-		"ubuntu-latest": "node:24-bookworm", // Don't use node:24-bookworm-slim because it doesn't have curl command, which is used in the tests
-	}
+		status, data = request(t, http.MethodPut, prep.FileContainerResourceURL+"?itemPath="+url.QueryEscape(item), strings.NewReader(content), nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+		var msg ResponseMessage
+		require.NoError(t, json.Unmarshal(data, &msg))
+		require.Equal(t, "success", msg.Message)
 
-	tables := []TestJobFileInfo{
-		{"testdata", "upload-and-download", "push", "", platforms, ""},
-		{"testdata", "GHSL-2023-004", "push", "", platforms, ""},
-	}
-	log.SetLevel(log.DebugLevel)
+		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)
 
-	for _, table := range tables {
-		runTestJobFile(ctx, t, table)
-	}
-}
+		status, data = request(t, http.MethodGet, baseURL+"/_apis/pipelines/workflows/"+runID+"/artifacts", nil, nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+		var list NamedFileContainerResourceURLResponse
+		require.NoError(t, json.Unmarshal(data, &list))
+		require.Equal(t, 1, list.Count)
+		require.Equal(t, "my-artifact", list.Value[0].Name)
 
-func runTestJobFile(ctx context.Context, t *testing.T, tjfi TestJobFileInfo) {
-	t.Run(tjfi.workflowPath, func(t *testing.T) {
-		fmt.Printf("::group::%s\n", tjfi.workflowPath) //nolint:forbidigo // pre-existing issue from nektos/act
+		status, data = request(t, http.MethodGet, list.Value[0].FileContainerResourceURL+"?itemPath=my-artifact", nil, nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+		var items ContainerItemResponse
+		require.NoError(t, json.Unmarshal(data, &items))
+		require.Len(t, items.Value, 1)
+		require.Equal(t, "file", items.Value[0].ItemType)
+		require.Equal(t, "my-artifact/data.txt", items.Value[0].Path)
 
-		if err := os.RemoveAll(artifactsPath); err != nil {
-			panic(err)
-		}
+		status, data = request(t, http.MethodGet, items.Value[0].ContentLocation, nil, nil)
+		require.Equal(t, http.StatusOK, status)
+		require.Equal(t, content, string(data))
 
-		workdir, err := filepath.Abs(tjfi.workdir)
-		assert.NoError(t, err, workdir) //nolint:testifylint // pre-existing issue from nektos/act
-		fullWorkflowPath := filepath.Join(workdir, tjfi.workflowPath)
-		runnerConfig := &runner.Config{
-			Workdir:               workdir,
-			BindWorkdir:           false,
-			EventName:             tjfi.eventName,
-			Platforms:             tjfi.platforms,
-			ReuseContainers:       false,
-			ContainerArchitecture: tjfi.containerArchitecture,
-			GitHubInstance:        "github.com",
-			ArtifactServerPath:    artifactsPath,
-			ArtifactServerAddr:    artifactsAddr,
-			ArtifactServerPort:    artifactsPort,
-		}
+		stored, err := os.ReadFile(filepath.Join(artifactPath, runID, "my-artifact", "data.txt"))
+		require.NoError(t, err)
+		require.Equal(t, content, string(stored))
+	})
 
-		runner, err := runner.New(runnerConfig)
-		assert.NoError(t, err, tjfi.workflowPath) //nolint:testifylint // pre-existing issue from nektos/act
+	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/11"}})
+		require.Equal(t, http.StatusOK, status, string(data))
 
-		planner, err := model.NewWorkflowPlanner(fullWorkflowPath, true)
-		assert.NoError(t, err, fullWorkflowPath) //nolint:testifylint // pre-existing issue from nektos/act
+		status, data = request(t, http.MethodPut, baseURL+rawURL, strings.NewReader("-second"),
+			http.Header{"Content-Range": []string{"bytes 5-11/11"}})
+		require.Equal(t, http.StatusOK, status, string(data))
 
-		plan, err := planner.PlanEvent(tjfi.eventName)
-		if err == nil {
-			err = runner.NewPlanExecutor(plan)(ctx)
-			if tjfi.errorMessage == "" {
-				assert.NoError(t, err, fullWorkflowPath) //nolint:testifylint // pre-existing issue from nektos/act
-			} else {
-				assert.Error(t, err, tjfi.errorMessage) //nolint:testifylint // pre-existing issue from nektos/act
-			}
-		} else {
-			assert.Nil(t, plan)
-		}
+		stored, err := os.ReadFile(filepath.Join(artifactPath, "4", "chunks.txt"))
+		require.NoError(t, err)
+		require.Equal(t, "first-second", string(stored))
+	})
 
-		fmt.Println("::endgroup::") //nolint:forbidigo // pre-existing issue from nektos/act
+	t.Run("gzip-roundtrip", func(t *testing.T) {
+		const runID, item, content = "2", "logs/app.log", "compressed payload\n"
+
+		var buf bytes.Buffer
+		gz := gzip.NewWriter(&buf)
+		_, err := gz.Write([]byte(content))
+		require.NoError(t, err)
+		require.NoError(t, gz.Close())
+
+		status, data := request(t, http.MethodPut, baseURL+"/upload/"+runID+"?itemPath="+url.QueryEscape(item),
+			&buf, http.Header{"Content-Encoding": []string{"gzip"}})
+		require.Equal(t, http.StatusOK, status, string(data))
+
+		// stored compressed, with the server's gzip marker suffix
+		_, err = os.Stat(filepath.Join(artifactPath, runID, "logs", "app.log.gz__"))
+		require.NoError(t, err)
+
+		status, data = request(t, http.MethodGet, baseURL+"/download/"+runID+"?itemPath=logs", nil, nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+		var items ContainerItemResponse
+		require.NoError(t, json.Unmarshal(data, &items))
+		require.Len(t, items.Value, 1)
+		require.Equal(t, "logs/app.log", items.Value[0].Path)
+
+		status, data = request(t, http.MethodGet, items.Value[0].ContentLocation, nil, nil)
+		require.Equal(t, http.StatusOK, status)
+		require.Equal(t, content, string(data))
+	})
+
+	// GHSL-2023-004: an itemPath that climbs out of the run directory must be neutralised so the
+	// blob cannot be written outside the artifact root.
+	t.Run("GHSL-2023-004", func(t *testing.T) {
+		const runID, content = "3", "contained\n"
+
+		status, data := request(t, http.MethodPut, baseURL+"/upload/"+runID+"?itemPath="+url.QueryEscape("../../escape.txt"),
+			strings.NewReader(content), nil)
+		require.Equal(t, http.StatusOK, status, string(data))
+
+		stored, err := os.ReadFile(filepath.Join(artifactPath, runID, "escape.txt"))
+		require.NoError(t, err)
+		require.Equal(t, content, string(stored))
+
+		_, err = os.Stat(filepath.Join(filepath.Dir(artifactPath), "escape.txt"))
+		require.True(t, os.IsNotExist(err), "upload escaped the artifact root")
+
+		status, data = request(t, http.MethodGet, baseURL+"/artifact/"+runID+"/escape.txt", nil, nil)
+		require.Equal(t, http.StatusOK, status)
+		require.Equal(t, content, string(data))
 	})
 }
 
-func TestMkdirFsImplSafeResolve(t *testing.T) {
-	assert := assert.New(t)
-
+func TestSafeResolve(t *testing.T) {
 	baseDir := "/foo/bar"
 
 	tests := map[string]struct {
@@ -340,60 +176,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, tc.want, safeResolve(baseDir, tc.input))
 		})
 	}
 }
 
-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))
+func TestServeEmptyArtifactPathReturnsCancelableNoop(t *testing.T) {
+	cancel := Serve(t.Context(), "", "127.0.0.1", "0")
+	require.NotNil(t, cancel)
+	cancel()
 }

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

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

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

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

act/common/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

@@ -0,0 +1,66 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"errors"
+	"testing"
+
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/act/common/logging/logtest"
+)
+
+func TestDryrunContext(t *testing.T) {
+	ctx := t.Context()
+	if Dryrun(ctx) {
+		t.Fatal("plain context should not be dryrun")
+	}
+	if !Dryrun(WithDryrun(ctx, true)) {
+		t.Fatal("WithDryrun(true) should set dryrun")
+	}
+	if Dryrun(WithDryrun(ctx, false)) {
+		t.Fatal("WithDryrun(false) should clear dryrun")
+	}
+}
+
+func TestJobErrorContainer(t *testing.T) {
+	ctx := t.Context()
+	err := errors.New("job failed")
+
+	SetJobError(ctx, err)
+	if got := JobError(ctx); got != nil {
+		t.Fatalf("JobError without container = %v, want nil", got)
+	}
+
+	ctx = WithJobErrorContainer(ctx)
+	SetJobError(ctx, err)
+	if got := JobError(ctx); !errors.Is(got, err) {
+		t.Fatalf("JobError = %v, want %v", got, err)
+	}
+}
+
+func TestLoggerAndHandlerContext(t *testing.T) {
+	ctx := t.Context()
+	if Logger(ctx) != logging.Default() {
+		t.Fatal("plain context should use the default logger")
+	}
+	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 := logging.New(logtest.New())
+	ctx = WithLogger(ctx, logger)
+	if Logger(ctx) != logger {
+		t.Fatal("WithLogger should set logger")
+	}
+
+	handler := logtest.New()
+	ctx = WithLoggerHandler(ctx, handler)
+	if LoggerHandler(ctx) != handler {
+		t.Fatal("WithLoggerHandler should set handler")
+	}
+}

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
@@ -54,22 +54,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 {
@@ -90,33 +74,33 @@ 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)
+				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())
+								logging.Errorf("panic in executor: %v\n%s", r, debug.Stack())
 								err = fmt.Errorf("panic: %v", r)
 							}
 						}()
 						return executor(ctx)
 					}()
 				}
-				log.Debugf("Worker %d finished (%d tasks executed)", workerID, taskCount)
+				logging.Debugf("Worker %d finished (%d tasks executed)", workerID, taskCount)
 			}(i, work, errs)
 		}
 
@@ -187,15 +171,8 @@ 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)
+			return fmt.Errorf("error occurred running finally: %v (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_max_parallel_test.go

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

act/common/executor_parallel_advanced_test.go

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

act/common/executor_test.go

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

act/common/git/fetch_action.go

@@ -0,0 +1,238 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package git
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"errors"
+	"io"
+	"math/rand/v2"
+	"net"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"time"
+
+	"gitea.com/gitea/runner/act/common"
+)
+
+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
+	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")
+	if !isFullObjectID(sha) || !exists(tree(sha)) {
+		sha, etag = "", ""
+	} else if 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(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 || exists(filepath.Join(input.Dir, sha)) {
+		return sha, err
+	}
+	archive, err := runGit(ctx, clone.Dir, nil, "archive", "--format=tar", sha)
+	if err != nil {
+		return "", err
+	}
+	_, err = extractTree(bytes.NewReader(archive), input.Dir, false)
+	return sha, err
+}
+
+func extractTree(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 := ""
+	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) && exists(filepath.Join(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:
+			err = writeTreeFile(root, name, header.Mode, reader)
+		case tar.TypeSymlink:
+			if err = root.Symlink(header.Linkname, name); err != nil && runtime.GOOS == "windows" {
+				err = writeTreeFile(root, name, 0, strings.NewReader(header.Linkname))
+			}
+		}
+		if err != nil {
+			return "", err
+		}
+	}
+	if !isFullObjectID(sha) {
+		return "", errors.New("the archive names no commit")
+	}
+	if err := root.Close(); err != nil {
+		return "", err
+	}
+	return sha, os.Rename(temp, filepath.Join(dir, sha))
+}
+
+func writeTreeFile(root *os.Root, name string, mode int64, content io.Reader) 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 err
+	}
+	_, err = io.Copy(file, content)
+	return 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,225 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package git
+
+import (
+	"archive/tar"
+	"bytes"
+	"encoding/base64"
+	"fmt"
+	"net/http"
+	"net/http/cgi"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"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, "commit", "-m", "initial"))
+	require.NoError(t, gitCmd("-C", remote, "tag", "v1"))
+
+	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
+	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/")
+		}
+		archive, _ := runGit(request.Context(), remote, nil, args...)
+		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("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, gitRevParse(t, remote, "v1"), 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)
+		assert.Equal(t, os.FileMode(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"))
+		moved, movedSha, err := FetchAction(t.Context(), input)
+		require.NoError(t, err)
+		assert.Equal(t, gitRevParse(t, remote, "v1"), 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)
+
+		requests, headers := served()
+		assert.Equal(t, 3, requests)
+		require.Len(t, headers, 3)
+		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 := gitRevParse(t, remote, "main")
+		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("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, gitRevParse(t, remote, "main"), 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, gitRevParse(t, remote, "main"), 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, gitRevParse(t, remote, "main"), sha)
+		_, headers := served()
+		assert.Len(t, headers, 1)
+		assert.NoDirExists(t, filepath.Join(input.Dir, "git"))
+	})
+}
+
+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(&archive, dir, false)
+			require.Error(t, err)
+			assert.NoFileExists(t, filepath.Join(dir, "escape"))
+			assert.NoFileExists(t, filepath.Join(outside, "escape"))
+		})
+	}
+}

act/common/git/git.go

@@ -6,47 +6,67 @@ package git
 
 import (
 	"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"
-
-	"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/act/common/logging"
+	"gitea.com/gitea/runner/internal/pkg/lock"
 )
 
 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]+$`)
 
-	cloneLocks sync.Map // key: clone target directory; value: *sync.Mutex
+	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() {
-	v, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
-	mu := v.(*sync.Mutex)
-	mu.Lock()
-	return mu.Unlock
+// 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 {
@@ -54,181 +74,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
-}
+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) {
+func FindGitRevision(ctx context.Context, file string) (shortSHA, sha string, err 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
 	}
-
-	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[:7], sha, nil
 }
 
 // FindGitRef get the current git ref
 func FindGitRef(ctx context.Context, file string) (string, error) {
 	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) {
-	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
@@ -239,71 +175,44 @@ type NewGitCloneExecutorInput struct {
 	Token       string
 	OfflineMode bool
 
+	// Depth limits the clone/fetch to the given number of commits from the tip of the requested ref.
+	// 0 for full clone.
+	Depth int
+
 	// 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 {
-		// Reuse existing clone
-		return r, true, nil
+		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 = git.PlainCloneContext(ctx, input.Dir, false, &cloneOptions)
-	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
@@ -312,126 +221,240 @@ func NewGitCloneExecutor(input NewGitCloneExecutorInput) common.Executor {
 		logger := common.Logger(ctx)
 		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
-		}
-
-		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 := ""
-
-		if !isOfflineMode {
-			if err = w.Pull(&pullOptions); err != nil && err != git.NoErrAlreadyUpToDate {
-				logger.Debugf("Unable to pull %s: %v", refName, err)
-			}
-		} else if 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
 	}
 }
+
+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
+}
+
+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) {
+		for _, name := range []string{cachedRef(ref), "refs/tags/" + ref, "refs/remotes/origin/" + ref} {
+			if sha, err := gitOutput(ctx, dir, "rev-parse", "--verify", name+"^{commit}"); err == nil {
+				return sha, nil
+			}
+		}
+	}
+	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
+}
+
+func isFullObjectID(ref string) bool {
+	return ObjectFormat(ref) != ""
+}
+
+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
+}
+
+// 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) {
+	config := []string{"core.autocrlf=false", "core.eol=lf"} // keep action files LF
+	if input != nil {
+		config = append(config, RemoteConfig(input.Token, input.InsecureSkipTLS)...)
+		if input.ClientCertFile != "" {
+			config = append(config, "http.sslCert="+input.ClientCertFile, "http.sslKey="+input.ClientKeyFile)
+		}
+	}
+	if dir != "" {
+		args = append([]string{"-C", dir}, args...)
+	}
+	cmd := exec.CommandContext(ctx, "git", args...)
+	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")
+	if runtime.GOOS != "windows" {
+		cmd.Cancel = func() error { return cmd.Process.Signal(os.Interrupt) } // lets git remove its lock files
+	}
+	cmd.WaitDelay = time.Second
+	var stderr strings.Builder
+	cmd.Stderr = &stderr
+	output, err := cmd.Output()
+	if err != nil {
+		return output, fmt.Errorf("git %s: %w: %s", strings.Join(args, " "), err, strings.TrimSpace(stderr.String()))
+	}
+	return output, nil
+}

act/common/git/git_test.go

@@ -6,52 +6,65 @@ 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"
 
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/act/common/logging/logtest"
+	"gitea.com/gitea/runner/internal/pkg/lock"
+
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 func TestFindGitSlug(t *testing.T) {
-	assert := assert.New(t)
-
-	slugTests := []struct {
-		url      string // input
-		provider string // expected result
-		slug     string // expected result
+	for _, testcase := range []struct {
+		remoteURL string
+		slug      string
 	}{
-		{"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"},
-	}
-
-	for _, tt := range slugTests {
-		provider, slug, err := findGitSlug(tt.url, "github.com")
-
-		assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
-		assert.Equal(tt.provider, provider)
-		assert.Equal(tt.slug, slug)
+		{"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)
+		})
 	}
 }
 
-func testDir(t *testing.T) string {
-	return t.TempDir()
+func TestErrorWrapsCommitAndCause(t *testing.T) {
+	err := &Error{err: ErrShortRef, commit: "abc123"}
+	require.Equal(t, ErrShortRef.Error(), err.Error())
+	require.ErrorIs(t, err, ErrShortRef)
+	require.Equal(t, "abc123", err.Commit())
 }
 
 func cleanGitHooks(dir string) error {
@@ -75,35 +88,38 @@ func cleanGitHooks(dir string) error {
 	return nil
 }
 
-func TestFindGitRemoteURL(t *testing.T) {
-	assert := assert.New(t)
+func TestFindGitMetadataOfSHA256RepositoryUsesOrigin(t *testing.T) {
+	t.Parallel()
+	basedir := t.TempDir()
+	const remoteURL = "https://github.com/owner/repo.git"
+	require.NoError(t, gitCmd("init", "--object-format=sha256", "--initial-branch=main", basedir))
+	require.NoError(t, cleanGitHooks(basedir))
+	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"))
 
-	basedir := testDir(t)
-	gitConfig()
-	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
+	shortSHA, sha, err := FindGitRevision(t.Context(), basedir)
+	require.NoError(t, err)
+	require.Equal(t, gitRevParse(t, basedir, "HEAD"), sha)
+	require.Len(t, sha, 64)
+	require.Equal(t, sha[:7], shortSHA)
 
-	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
+	ref, err := FindGitRef(t.Context(), basedir)
+	require.NoError(t, err)
+	require.Equal(t, "refs/heads/main", ref)
 
-	u, err := findGitRemoteURL(context.Background(), basedir, "origin")
-	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)
 
-	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)
+	slug, err := FindGithubRepo(t.Context(), basedir)
+	require.NoError(t, err)
+	require.Equal(t, "owner/repo", slug)
 }
 
 func TestGitFindRef(t *testing.T) {
-	basedir := testDir(t)
-	gitConfig()
+	t.Parallel()
+	basedir := t.TempDir()
 
 	for name, tt := range map[string]struct {
 		Prepare func(t *testing.T, dir string)
@@ -173,115 +189,197 @@ func TestGitFindRef(t *testing.T) {
 			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)
+			ref, err := FindGitRef(t.Context(), dir)
 			tt.Assert(t, ref, err)
 		})
 	}
 }
 
 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, os.WriteFile(filepath.Join(workDir, "action.sh"), []byte("#!/bin/sh\necho hi\n"), 0o755))
+	require.NoError(t, gitCmd("-C", workDir, "add", "action.sh"))
+	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))
+
+	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[url \""+remoteDir+"\"]\n\tinsteadOf = https://example.invalid/action\n"), 0o644))
+	t.Setenv("GIT_CONFIG_GLOBAL", hostConfig)
+	t.Setenv("GIT_DIR", t.TempDir())
+
 	for name, tt := range map[string]struct {
-		Err      error
-		URL, Ref string
+		Err error
+		Ref string
 	}{
 		"tag": {
 			Err: nil,
-			URL: "https://github.com/actions/checkout",
 			Ref: "v2",
 		},
 		"branch": {
 			Err: nil,
-			URL: "https://github.com/anchore/scan-action",
 			Ref: "act-fails",
 		},
 		"sha": {
 			Err: nil,
-			URL: "https://github.com/actions/checkout",
-			Ref: "5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f", // v2
+			Ref: fullSha,
 		},
 		"short-sha": {
-			Err: &Error{ErrShortRef, "5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f"},
-			URL: "https://github.com/actions/checkout",
-			Ref: "5a4ac90", // v2
+			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) {
+			dir := t.TempDir()
 			clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
-				URL: tt.URL,
+				URL: "https://example.invalid/action",
 				Ref: tt.Ref,
-				Dir: testDir(t),
+				Dir: dir,
 			})
 
-			err := clone(context.Background())
+			err := clone(t.Context())
 			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
+				assert.Equal(t, tt.Err, clone(t.Context()), "a retry on the cache keeps the error")
+				return
 			}
+			assert.Empty(t, err) //nolint:testifylint // pre-existing issue from nektos/act
+			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")
 		})
 	}
 }
 
-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.
+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))
 
-	gitConfig()
+		workDir := t.TempDir()
+		require.NoError(t, gitCmd("clone", remoteDir, workDir))
+		require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", message))
+		require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
 
-	// Create a bare "remote" repo with an initial commit on main and a feature branch.
+		return remoteDir
+	}
+
+	oldRemoteDir := createRemote("old-action")
+	newRemoteDir := createRemote("new-action")
+	cacheDir := t.TempDir()
+
+	require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+		URL: oldRemoteDir,
+		Ref: "main",
+		Dir: cacheDir,
+	})(t.Context()))
+
+	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)
+	require.NoError(t, err)
+	assert.Equal(t, newRemoteDir, originURL)
+
+	out, err := exec.Command("git", "-C", cacheDir, "log", "--oneline", "-1", "--format=%s").Output()
+	require.NoError(t, err)
+	assert.Equal(t, "new-action", strings.TrimSpace(string(out)))
+
+	_, err = os.Stat(markerPath)
+	require.True(t, os.IsNotExist(err), "stale cached directory should be removed before recloning")
+}
+
+func TestGitCloneExecutorFollowsRemoteRefChanges(t *testing.T) {
+	t.Parallel()
 	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"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "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) {
-	gitConfig()
-
+	t.Parallel()
 	// Build a local "remote" with a single commit on main.
 	remoteDir := t.TempDir()
 	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
@@ -297,7 +395,7 @@ func TestGitCloneExecutorOfflineMode(t *testing.T) {
 		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)
@@ -307,7 +405,7 @@ func TestGitCloneExecutorOfflineMode(t *testing.T) {
 			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()
@@ -322,27 +420,188 @@ func TestGitCloneExecutorOfflineMode(t *testing.T) {
 			Ref:         "never-fetched",
 			Dir:         cacheDir,
 			OfflineMode: true,
-		})(context.Background())
+		})(t.Context())
 		require.Error(t, err)
 	})
 }
 
-func gitConfig() {
-	if os.Getenv("GITHUB_ACTIONS") == "true" {
-		var err error
-		if err = gitCmd("config", "--global", "user.email", "test@test.com"); err != nil {
-			log.Error(err)
-		}
-		if err = gitCmd("config", "--global", "user.name", "Unit Test"); err != nil {
-			log.Error(err)
-		}
+func TestGitCloneExecutorShallow(t *testing.T) {
+	t.Parallel()
+	// Build a local "remote" with several commits on main plus a tag, so a full clone would pull noticeably more history than a shallow one.
+	remoteDir := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	for _, m := range []string{"c1", "c2", "c3"} {
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", m))
 	}
+	require.NoError(t, gitCmd("-C", workDir, "tag", "v1"))
+	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) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "main", Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.FileExists(t, shallowMarker(dir), "clone should be shallow")
+		assert.Equal(t, 1, gitRevCount(t, dir), "only the tip commit should be present")
+		assert.Equal(t, "c3", gitHeadSubject(t, dir))
+	})
+
+	t.Run("tag is cloned shallowly", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "v1", Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.FileExists(t, shallowMarker(dir), "clone should be shallow")
+		assert.Equal(t, 1, gitRevCount(t, dir))
+		assert.Equal(t, "c3", gitHeadSubject(t, dir))
+	})
+
+	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: unadvertisedRemote(t, false), Ref: unadvertisedSHA, Dir: dir, Depth: 1,
+		})(t.Context()))
+		assert.Equal(t, unadvertisedSHA, gitRevParse(t, dir, "HEAD"))
+	})
+
+	t.Run("commit hash is fetched shallowly, moved to another hash, then reused without reaching the remote", func(t *testing.T) {
+		remote := unadvertisedRemote(t, true)
+		dir := t.TempDir()
+		cloneAt := func(ref string) error {
+			return NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: remote, Ref: ref, Dir: dir, Depth: 1,
+			})(t.Context())
+		}
+
+		require.NoError(t, cloneAt(unadvertisedSHA))
+		assert.FileExists(t, shallowMarker(dir))
+		assert.Equal(t, 1, gitRevCount(t, dir))
+		assert.Equal(t, unadvertisedSHA, gitRevParse(t, dir, "HEAD"))
+
+		olderSHA := gitRevParse(t, workDir, "HEAD~2")
+		require.NoError(t, cloneAt(olderSHA))
+		assert.Equal(t, olderSHA, gitRevParse(t, dir, "HEAD"))
+
+		require.NoError(t, os.RemoveAll(remote))
+		require.NoError(t, cloneAt(olderSHA))
+		assert.Equal(t, olderSHA, gitRevParse(t, dir, "HEAD"))
+	})
+
+	t.Run("moving hexadecimal-named branch updates while staying shallow", func(t *testing.T) {
+		require.NoError(t, gitCmd("-C", workDir, "push", "origin", "main:deadbeef"))
+		dir := t.TempDir()
+		clone := NewGitCloneExecutor(NewGitCloneExecutorInput{
+			URL: remoteDir, Ref: "deadbeef", Dir: dir, Depth: 1,
+		})
+		require.NoError(t, clone(t.Context()))
+		require.Equal(t, "c3", gitHeadSubject(t, dir))
+
+		require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "c4"))
+		require.NoError(t, gitCmd("-C", workDir, "push", "origin", "main:deadbeef"))
+
+		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 := t.TempDir()
+	require.NoError(t, gitCmd("init", "--bare", "--initial-branch=main", remoteDir))
+	workDir := t.TempDir()
+	require.NoError(t, gitCmd("clone", remoteDir, workDir))
+	require.NoError(t, gitCmd("-C", workDir, "checkout", "-b", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "pinned"))
+	pinned := gitRevParse(t, workDir, "HEAD")
+	require.NoError(t, gitCmd("-C", workDir, "commit", "--allow-empty", "-m", "decoy"))
+	require.NoError(t, gitCmd("-C", workDir, "tag", pinned))
+	require.NoError(t, gitCmd("-C", workDir, "push", "-u", "origin", "main"))
+	require.NoError(t, gitCmd("-C", workDir, "push", "origin", pinned))
+
+	for name, depth := range map[string]int{"shallow": 1, "full clone": 0} {
+		t.Run(name, func(t *testing.T) {
+			dir := t.TempDir()
+			require.NoError(t, NewGitCloneExecutor(NewGitCloneExecutorInput{
+				URL: remoteDir, Ref: pinned, Dir: dir, Depth: depth,
+			})(t.Context()))
+			assert.Equal(t, pinned, gitRevParse(t, dir, "HEAD"))
+		})
+	}
+}
+
+func gitRevParse(t *testing.T, dir, rev string) string {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "rev-parse", rev).Output()
+	require.NoError(t, err)
+	return strings.TrimSpace(string(out))
+}
+
+func gitRevCount(t *testing.T, dir string) int {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "rev-list", "--count", "HEAD").Output()
+	require.NoError(t, err)
+	n, err := strconv.Atoi(strings.TrimSpace(string(out)))
+	require.NoError(t, err)
+	return n
+}
+
+func gitHeadSubject(t *testing.T, dir string) string {
+	t.Helper()
+	out, err := exec.Command("git", "-C", dir, "log", "-1", "--format=%s").Output()
+	require.NoError(t, err)
+	return strings.TrimSpace(string(out))
 }
 
 func gitCmd(args ...string) error {
 	cmd := exec.Command("git", args...)
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr
+	// Inject a deterministic identity and ignore the host's global/system config so commits
+	// succeed regardless of the host having no user.name/user.email (e.g. CI, GITHUB_ACTIONS
+	// unset) or a global commit.gpgsign, and without mutating the developer's ~/.gitconfig.
+	cmd.Env = append(os.Environ(),
+		"GIT_AUTHOR_NAME=Unit Test",
+		"GIT_AUTHOR_EMAIL=test@test.com",
+		"GIT_COMMITTER_NAME=Unit Test",
+		"GIT_COMMITTER_EMAIL=test@test.com",
+		"GIT_CONFIG_GLOBAL=/dev/null",
+		"GIT_CONFIG_SYSTEM=/dev/null",
+	)
 
 	err := cmd.Run()
 	if exitError, ok := err.(*exec.ExitError); ok {
@@ -355,14 +614,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()
 		}()
@@ -386,12 +673,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)
 		}()
@@ -402,12 +693,51 @@ func TestAcquireCloneLock(t *testing.T) {
 			t.Fatal("acquire on a different directory must not block")
 		}
 	})
-
-	t.Run("same directory reuses the same mutex", func(t *testing.T) {
-		dir := t.TempDir()
-
-		v1, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
-		v2, _ := cloneLocks.LoadOrStore(dir, &sync.Mutex{})
-		require.Same(t, v1, v2)
-	})
+}
+
+// An unresponsive remote must not pin a job: the refresh has to be interruptible.
+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 <-time.After(10 * time.Second):
+		t.Fatal("the executor never reached the remote")
+	}
+	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

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

act/common/line_writer.go

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

act/common/line_writer_test.go

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

act/common/logger.go

@@ -7,46 +7,53 @@ 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
-		}
+// 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 {
+	if h, ok := ctx.Value(loggerHandlerKeyVal).(logging.Handler); ok {
+		return h
 	}
 	return nil
 }
 
-// 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,287 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package logging
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"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 := make([]string, 0, len(data))
+	for k := range data {
+		keys = append(keys, k)
+	}
+	slices.Sort(keys)
+
+	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,85 @@
+// 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 Tracef(format string, args ...any) { Default().logf(LevelTrace, format, args) }
+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 Trace(args ...any)                 { Default().log(LevelTrace, 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,106 @@
+// 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) Tracef(format string, args ...any) { l.logf(LevelTrace, format, args) }
+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,149 @@
+// 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)
+	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) // fmt.Sprint spacing
+	bad, _ := recs[2].Attr("!BADKEY")
+	assert.Equal(t, 7, bad)
+
+	h.Reset()
+	assert.Nil(t, h.LastRecord())
+}
+
+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
+	slogger := slog.New(slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug}))
+	l := logging.New(logging.NewSlogHandler(slogger.Handler())).With("job", "j1")
+
+	l.Tracef("dropped")
+	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,89 @@
+// 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
+}
+
+func (h *Handler) Reset() {
+	h.store.mu.Lock()
+	defer h.store.mu.Unlock()
+	h.store.records = nil
+}
+
+// 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/outbound_ip.go

@@ -10,6 +10,11 @@ import (
 	"strings"
 )
 
+type interfaceIP struct {
+	net.IP
+	net.Interface
+}
+
 // GetOutboundIP returns an outbound IP address of this machine.
 // It tries to access the internet and returns the local IP address of the connection.
 // If the machine cannot access the internet, it returns a preferred IP address from network interfaces.
@@ -19,16 +24,14 @@ func GetOutboundIP() net.IP {
 	conn, err := net.Dial("udp", "8.8.8.8:80")
 	if err == nil {
 		defer conn.Close()
-		return conn.LocalAddr().(*net.UDPAddr).IP
+		if addr, ok := conn.LocalAddr().(*net.UDPAddr); ok {
+			return addr.IP
+		}
 	}
 
 	// So the machine cannot access the internet. Pick an IP address from network interfaces.
 	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 {
@@ -40,40 +43,45 @@ func GetOutboundIP() net.IP {
 						ip = v.IP
 					}
 					if ip.IsGlobalUnicast() {
-						ips = append(ips, IP{ip, i})
+						ips = append(ips, interfaceIP{ip, i})
 					}
 				}
 			}
 		}
-		if len(ips) > 1 {
-			sort.Slice(ips, func(i, j int) bool {
-				ifi := ips[i].Interface
-				ifj := ips[j].Interface
-
-				// ethernet is preferred
-				if vi, vj := strings.HasPrefix(ifi.Name, "e"), strings.HasPrefix(ifj.Name, "e"); vi != vj {
-					return vi
-				}
-
-				ipi := ips[i].IP
-				ipj := ips[j].IP
-
-				// IPv4 is preferred
-				if vi, vj := ipi.To4() != nil, ipj.To4() != nil; vi != vj {
-					return vi
-				}
-
-				// en0 is preferred to en1
-				if ifi.Name != ifj.Name {
-					return ifi.Name < ifj.Name
-				}
-
-				// fallback
-				return ipi.String() < ipj.String()
-			})
-			return ips[0].IP
-		}
+		return preferredIP(ips)
 	}
 
 	return nil
 }
+
+func preferredIP(ips []interfaceIP) net.IP {
+	if len(ips) == 0 {
+		return nil
+	}
+	sort.Slice(ips, func(i, j int) bool {
+		ifi := ips[i].Interface
+		ifj := ips[j].Interface
+
+		// ethernet is preferred
+		if vi, vj := strings.HasPrefix(ifi.Name, "e"), strings.HasPrefix(ifj.Name, "e"); vi != vj {
+			return vi
+		}
+
+		ipi := ips[i].IP
+		ipj := ips[j].IP
+
+		// IPv4 is preferred
+		if vi, vj := ipi.To4() != nil, ipj.To4() != nil; vi != vj {
+			return vi
+		}
+
+		// en0 is preferred to en1
+		if ifi.Name != ifj.Name {
+			return ifi.Name < ifj.Name
+		}
+
+		// fallback
+		return ipi.String() < ipj.String()
+	})
+	return ips[0].IP
+}

act/common/outbound_ip_test.go

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

act/container/container_types.go

@@ -6,12 +6,18 @@ package container
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
+	"path"
+	"strings"
+	"sync"
+	"sync/atomic"
 
 	"gitea.com/gitea/runner/act/common"
 
 	"github.com/docker/go-connections/nat"
+	"github.com/moby/moby/api/types/container"
 )
 
 // ExitCodeError reports a non-zero process exit code from a container command.
@@ -23,26 +29,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 +64,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
@@ -82,6 +147,14 @@ type NewDockerBuildExecutorInput struct {
 	BuildContext io.Reader
 	ImageTag     string
 	Platform     string
+	BuildArgs    map[string]*string
+}
+
+// NewDockerNetworkCreateExecutorInput the input for the NewDockerNetworkCreateExecutor function
+type NewDockerNetworkCreateExecutorInput struct {
+	EnableIPv4 *bool
+	EnableIPv6 *bool
+	RunnerUUID string
 }
 
 // NewDockerPullExecutorInput the input for the NewDockerPullExecutor function

act/container/docker_auth.go

@@ -7,29 +7,37 @@
 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/docker/cli/cli/config/credentials"
 	"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
 	}
-	if !cfg.ContainsAuth() {
-		cfg.CredentialsStore = credentials.DetectDefaultStore(cfg.CredentialsStore)
-	}
-
 	registryKey := registryAuthConfigKey("docker.io")
 	if image != "" {
 		if registryRef, refErr := reference.ParseNormalizedNamed(image); refErr != nil {
@@ -39,36 +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
 	}
-	if !cfg.ContainsAuth() {
-		cfg.CredentialsStore = credentials.DetectDefaultStore(cfg.CredentialsStore)
-	}
-
-	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
 }
 
@@ -78,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))
+
+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

@@ -7,15 +7,18 @@
 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"
@@ -49,6 +52,7 @@ func NewDockerBuildExecutor(input NewDockerBuildExecutorInput) common.Executor {
 			Remove:      true,
 			AuthConfigs: LoadDockerAuthConfigs(ctx),
 			Dockerfile:  input.Dockerfile,
+			BuildArgs:   input.BuildArgs,
 		}
 		platform, err := parsePlatform(input.Platform)
 		if err != nil {
@@ -114,14 +118,140 @@ 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 {
+	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
+		root := strings.TrimSuffix(contextDir, string(filepath.Separator)) + string(filepath.Separator) + include // unlike filepath.Join, follows a symlinked context dir as docker build does
+		err := filepath.WalkDir(root, 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}, 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,49 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+
+package container
+
+import (
+	"archive/tar"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+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+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)
+
+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)
+
+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

@@ -4,8 +4,12 @@
 
 //go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
 
-// This file is exact copy of https://github.com/docker/cli/blob/9a471180cb7d39c236d090399a9d362c3f5a8ebd/cli/command/container/opts.go
-// appended with license information.
+// This file is exact copy of https://github.com/docker/cli/blob/4a63305d74332de5ceba7fcbccbc3cbb7412f5ba/cli/command/container/opts.go with:
+// * appended with license information
+// * regexp and 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 the callers in docker_run.go
 //
 // docker/cli is licensed under the Apache License, Version 2.0.
 // See DOCKER_LICENSE for the full license text.
@@ -15,8 +19,7 @@
 package container
 
 import (
-	"bytes"
-	"encoding/json"
+	"encoding/json/jsontext"
 	"errors"
 	"fmt"
 	"net"
@@ -30,14 +33,13 @@ import (
 	"strings"
 	"time"
 
-	"github.com/docker/cli/cli/compose/loader"
+	cerrdefs "github.com/containerd/errdefs"
 	"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 (
@@ -150,6 +152,7 @@ type containerOptions struct {
 	runtime             string
 	autoRemove          bool
 	init                bool
+	umask               opts.UmaskOpt
 	annotations         *opts.MapOpts
 
 	Image string
@@ -324,6 +327,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"})
@@ -348,7 +354,7 @@ type containerConfig struct {
 // parse parses the args for the specified command and generates a Config,
 // a HostConfig and returns them with the specified command.
 // If the specified args are not valid, it will return an error.
-func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*containerConfig, error) { //nolint:gocyclo // verbatim copy from docker/cli
+func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*containerConfig, error) { //nolint:gocyclo,unparam // verbatim copy from docker/cli
 	var (
 		attachStdin  = copts.attach.Get("stdin")
 		attachStdout = copts.attach.Get("stdout")
@@ -380,8 +386,8 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 	var binds []string
 	volumes := copts.volumes.GetMap()
 	// add any bind targets to the list of container volumes
-	for bind := range copts.volumes.GetMap() {
-		parsed, err := loader.ParseVolume(bind)
+	for bind := range volumes {
+		parsed, err := ParseVolume(bind)
 		if err != nil {
 			return nil, err
 		}
@@ -389,7 +395,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 {
@@ -497,7 +503,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
 		}
@@ -515,13 +521,13 @@ func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*con
 	// collect all the environment variables for the container
 	envVariables, err := opts.ReadKVEnvStrings(copts.envFile.GetSlice(), copts.env.GetSlice())
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("--env-file: %w", err)
 	}
 
 	// collect all the labels for the container
 	labels, err := opts.ReadKVStrings(copts.labelsFile.GetSlice(), copts.labels.GetSlice())
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("--label-file: %w", err)
 	}
 
 	pidMode := container.PidMode(copts.pidMode)
@@ -719,6 +725,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() {
@@ -956,11 +963,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)
 			}
 		}
 	}
@@ -1164,16 +1171,17 @@ func toNetipAddrSlice(ips []string) []netip.Addr {
 }
 
 // invalidParameter wraps an error to indicate it was caused by invalid input.
-// This is a local replacement for docker/docker/errdefs.InvalidParameter.
-type invalidParameterError struct{ error }
+// This is a copy of docker/cli's cli/command/container/errors.go, which is not importable.
+type invalidParameterErr struct{ error }
 
-func (e invalidParameterError) InvalidParameter() {}
+func (invalidParameterErr) InvalidParameter() {}
+func (e invalidParameterErr) Unwrap() error   { return e.error }
 
 func invalidParameter(err error) error {
-	if err == nil {
-		return nil
+	if err == nil || cerrdefs.IsInvalidArgument(err) {
+		return err
 	}
-	return invalidParameterError{err}
+	return invalidParameterErr{err}
 }
 
 func convertPortSet(ports nat.PortSet) (network.PortSet, error) {
@@ -1188,6 +1196,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_create_flags.go

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

act/container/docker_create_flags_test.go

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

act/container/docker_images.go

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

act/container/docker_images_test.go

@@ -5,67 +5,65 @@
 package container
 
 import (
-	"context"
-	"io"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
 	"testing"
 
-	"github.com/moby/moby/client"
-	specs "github.com/opencontainers/image-spec/specs-go/v1"
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
+
 	"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 {
+	t.Helper()
+	tag := fmt.Sprintf("act-test-exists-%s:latest", strings.TrimPrefix(platform, "linux/"))
+	cmd := exec.Command("docker", "build", "--platform", platform, "-t", tag, "-")
+	cmd.Stdin = strings.NewReader("FROM scratch\nLABEL act-test=1\n")
+	// Force BuildKit: it records the requested architecture in the image config for a
+	// FROM-scratch build, whereas the classic builder ignores --platform and tags it with the
+	// host arch, which would break the per-platform existence assertions below.
+	cmd.Env = append(os.Environ(), "DOCKER_BUILDKIT=1")
+	out, err := cmd.CombinedOutput()
+	require.NoError(t, err, string(out))
+	t.Cleanup(func() { _ = exec.Command("docker", "rmi", "-f", tag).Run() })
+	return tag
 }
 
 func TestImageExistsLocally(t *testing.T) {
-	if testing.Short() {
-		t.Skip("skipping integration test")
-	}
-	ctx := context.Background()
-	// to help make this test reliable and not flaky, we need to have
-	// an image that will exist, and onew that won't exist
+	requireDocker(t)
+	ctx := t.Context()
 
-	// Test if image exists with specific tag
-	invalidImageTag, err := ImageExistsLocally(ctx, "library/alpine:this-random-tag-will-never-exist", "linux/amd64")
+	// 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, invalidImageTag)
+	assert.False(t, missing)
 
-	// Test if image exists with specific architecture (image platform)
-	invalidImagePlatform, err := ImageExistsLocally(ctx, "alpine:latest", "windows/amd64")
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.False(t, invalidImagePlatform)
+	// 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")
 
-	// pull an image
-	cli, err := client.New(client.FromEnv)
+	amd64Exists, err := ImageExistsLocally(ctx, amd64Ref, "linux/amd64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	defer cli.Close()
+	assert.True(t, amd64Exists)
 
-	// Chose alpine latest because it's so small
-	// maybe we should build an image instead so that tests aren't reliable on dockerhub
-	readerDefault, err := cli.ImagePull(ctx, "node:24-bookworm-slim", client.ImagePullOptions{
-		Platforms: []specs.Platform{{OS: "linux", Architecture: "amd64"}},
-	})
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	defer readerDefault.Close()
-	_, err = io.ReadAll(readerDefault)
+	// 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)
 
-	imageDefaultArchExists, err := ImageExistsLocally(ctx, "node:24-bookworm-slim", "linux/amd64")
+	// a present image is reported absent for a different platform
+	wrongPlatform, err := ImageExistsLocally(ctx, amd64Ref, "linux/arm64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.True(t, imageDefaultArchExists)
-
-	// Validate if another architecture platform can be pulled
-	readerArm64, err := cli.ImagePull(ctx, "node:24-bookworm-slim", client.ImagePullOptions{
-		Platforms: []specs.Platform{{OS: "linux", Architecture: "arm64"}},
-	})
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	defer readerArm64.Close()
-	_, err = io.ReadAll(readerArm64)
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-
-	imageArm64Exists, err := ImageExistsLocally(ctx, "node:24-bookworm-slim", "linux/arm64")
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.True(t, imageArm64Exists)
+	assert.False(t, wrongPlatform)
 }

act/container/docker_logger.go

@@ -8,11 +8,11 @@ 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,13 +20,13 @@ 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
 	}
@@ -57,18 +57,19 @@ func logDockerResponse(logger logrus.FieldLogger, dockerResponse io.ReadCloser,
 
 		if msg.ErrorDetail.Message != "" {
 			writeLog(logger, isError, "%s", msg.ErrorDetail.Message)
-			return errors.New(msg.Error)
+			return errors.New(msg.ErrorDetail.Message)
 		}
 
-		if msg.Status != "" {
+		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))
 		}
 	}
@@ -76,7 +77,7 @@ func logDockerResponse(logger logrus.FieldLogger, dockerResponse io.ReadCloser,
 	return nil
 }
 
-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

@@ -8,46 +8,198 @@ package container
 
 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"
 )
 
-func NewDockerNetworkCreateExecutor(name string) common.Executor {
+const (
+	networkCreateAttempts   = 3
+	networkCreateRetryDelay = time.Second
+)
+
+// RemoveOrphanNetworks removes the networks this runner created for jobs whose teardown did
+// not get to them: the runner died with the job, the teardown timed out, or the network still
+// had an endpoint on it at the time. Each one holds a subnet of the daemon's address pool
+// until it is removed. Networks created after createdBefore are left alone, so a job starting
+// while this runs cannot lose the network it has created but not yet attached a container to.
+func RemoveOrphanNetworks(ctx context.Context, runnerUUID, 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, detach, createdBefore)
+}
+
+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),
+	})
+	if err != nil {
+		return err
+	}
+
+	var errs []error
+networks:
+	for _, n := range networks.Items {
+		result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
+		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) > 1 || result.Network.Created.After(createdBefore) {
+			continue
+		}
+		for containerID := range result.Network.Containers {
+			if detach == "" || !strings.HasPrefix(containerID, detach) {
+				continue networks
+			}
+			if err := disconnectNetwork(ctx, cli, n.ID, containerID); err != nil {
+				errs = append(errs, fmt.Errorf("failed to disconnect container from network %s: %w", n.Name, err))
+				continue networks
+			}
+		}
+		if _, err := cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); cerrdefs.IsNotFound(err) {
+			continue
+		} else if err != nil {
+			errs = append(errs, fmt.Errorf("failed to remove network %s: %w", n.Name, err))
+			continue
+		}
+		common.Logger(ctx).Infof("removed docker network %s left behind by an earlier job", n.Name)
+	}
+	return errors.Join(errs...)
+}
+
+func NewDockerNetworkCreateExecutor(name string, opts NewDockerNetworkCreateExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
 		cli, err := GetDockerClient(ctx)
 		if err != nil {
 			return err
 		}
 		defer cli.Close()
+		return createDockerNetwork(ctx, cli, name, opts)
+	}
+}
 
-		// Only create the network if it doesn't exist
-		networks, err := cli.NetworkList(ctx, client.NetworkListOptions{})
-		if err != nil {
-			return err
+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
 		}
-		// 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
+		}
+	}
+	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)
+}
 
-		_, err = cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{
-			Driver: "bridge",
-			Scope:  "local",
-		})
+func runnerLabels(runnerUUID string) map[string]string {
+	if runnerUUID == "" {
+		return nil
+	}
+	return map[string]string{runnerUUIDLabel: runnerUUID}
+}
+
+// The daemon reports this as a plain invalid-parameter error, the same kind it uses for every
+// malformed request, so the message is the only discriminator.
+func isAddressPoolExhausted(err error) bool {
+	msg := err.Error()
+	return strings.Contains(msg, "all predefined address pools have been fully subnetted") ||
+		strings.Contains(msg, "could not find an available, non-overlapping IPv4 address pool among the defaults") // docker 24 and older
+}
+
+func NewDockerNetworkConnectExecutor(networkName, container string) common.Executor {
+	return func(ctx context.Context) error {
+		cli, err := GetDockerClient(ctx)
 		if err != nil {
 			return err
 		}
-
+		defer cli.Close()
+		if err := connectNetwork(ctx, cli, networkName, container); err != nil {
+			common.Logger(ctx).Warnf("cannot connect %s to network %s, so jobs on it cannot reach the cache: %v", container, networkName, err)
+		}
 		return nil
 	}
 }
 
+func connectNetwork(ctx context.Context, cli client.APIClient, networkName, container string) error {
+	_, err := cli.NetworkConnect(ctx, networkName, client.NetworkConnectOptions{
+		Container:      container,
+		EndpointConfig: &network.EndpointSettings{Aliases: []string{container}},
+	})
+	if err != nil && (strings.Contains(err.Error(), "already exists in network") || strings.Contains(err.Error(), "already connected")) {
+		return nil
+	}
+	return err
+}
+
+func NewDockerNetworkDisconnectExecutor(networkName, container string) common.Executor {
+	return func(ctx context.Context) error {
+		cli, err := GetDockerClient(ctx)
+		if err != nil {
+			return err
+		}
+		defer cli.Close()
+		return disconnectNetwork(ctx, cli, networkName, container)
+	}
+}
+
+func disconnectNetwork(ctx context.Context, cli client.APIClient, networkName, container string) error {
+	_, err := cli.NetworkDisconnect(ctx, networkName, client.NetworkDisconnectOptions{Container: container, Force: true})
+	if cerrdefs.IsNotFound(err) || (err != nil && strings.Contains(err.Error(), "is not connected")) {
+		return nil
+	}
+	return err
+}
+
 func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 	return func(ctx context.Context) error {
 		cli, err := GetDockerClient(ctx)
@@ -55,32 +207,79 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 			return err
 		}
 		defer cli.Close()
-
-		// 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{})
-		if err != nil {
-			return err
-		}
-		// For Gitea, reduce log noise
-		// common.Logger(ctx).Debugf("%v", networks)
-		for _, n := range networks.Items {
-			if n.Name == name {
-				result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
-				if err != nil {
-					return err
-				}
-
-				if len(result.Network.Containers) == 0 {
-					if _, err = cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); err != nil {
-						common.Logger(ctx).Debugf("%v", err)
-					}
-				} else {
-					common.Logger(ctx).Debugf("Refusing to remove network %v because it still has active endpoints", name)
-				}
-			}
-		}
-
-		return err
+		return removeNetwork(ctx, cli, name)
 	}
 }
+
+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]
+			}
+		}
+	}
+	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

@@ -0,0 +1,171 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+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")))
+}
+
+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{
+		{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).Twice()
+	client.On("NetworkInspect", ctx, "busy", mobyclient.NetworkInspectOptions{}).
+		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)},
+			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).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", "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_test.go

@@ -61,3 +61,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,587 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+
+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
+)
+
+var (
+	createPath    = regexp.MustCompile(`^(/v[0-9.]+)?/(containers|networks|volumes)/create$`)
+	rawStreamPath = regexp.MustCompile(`^(/v[0-9.]+)?/(containers/[^/]+/attach|exec/[^/]+/start)$`)
+)
+
+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 := GetDockerClient(probeCtx)
+	if err != nil {
+		return nil
+	}
+	defer cli.Close()
+	daemonSocket, ok := strings.CutPrefix(cli.DaemonHost(), "unix://")
+	if !ok {
+		return nil
+	}
+	if info, err := os.Stat(daemonSocket); err != nil || info.Mode()&os.ModeSocket == 0 {
+		return nil
+	}
+	dir, daemonDir := runnerContainerWorkdir(probeCtx, cli)
+	seen := daemonDir != ""
+	if !seen {
+		if dir, err = filepath.Abs(os.TempDir()); err == nil {
+			daemonDir = dir
+			seen, err = daemonSeesDir(probeCtx, cli, dir, daemonDir)
+		}
+	}
+	if err != nil {
+		common.Logger(ctx).Infof("docker proxy probe failed, jobs get the daemon socket directly: %v", err)
+		return nil
+	}
+	if !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, dir, job)
+	if err != nil {
+		common.Logger(ctx).Warnf("docker proxy not started, the job gets the daemon socket directly: %v", err)
+		return nil
+	}
+	proxy.Socket = daemonDir + strings.TrimPrefix(proxy.Socket, dir)
+	return proxy
+}
+
+// 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")
+	}
+	created, err := cli.ContainerCreate(ctx, client.ContainerCreateOptions{
+		Config: &container.Config{Image: images.Items[0].ID, Cmd: []string{"true"}},
+		HostConfig: &container.HostConfig{Mounts: []mount.Mount{
+			{Type: mount.TypeBind, Source: daemonDir, Target: "/gitea-runner-probe", ReadOnly: true}, // not the marker itself, podman creates a missing bind source where docker rejects it
+		}},
+	})
+	if cerrdefs.IsInvalidArgument(err) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	seen, err := containerSeesMarker(ctx, cli, dir, created.ID, "/gitea-runner-probe")
+	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
+}
+
+// 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,546 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+
+package container
+
+import (
+	"archive/tar"
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"testing"
+	"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)
+	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 r.URL.RawQuery == "wait" {
+				close(createStarted)
+				<-releaseCreate
+			}
+			bodies <- body
+			w.WriteHeader(http.StatusCreated)
+		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("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)
+	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(mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error)
+	remove func(context.Context, string, mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error)
+	stat   func(string) error
+	mounts []container.MountPoint
+}
+
+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: "probe-image"}}}, nil
+}
+
+func (c *probeClient) ContainerCreate(_ context.Context, opts mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error) {
+	return c.create(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 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
+			cli := &probeClient{
+				create: func(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)
+					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, 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) {
+	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)
+
+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

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

act/container/docker_pull_test.go

@@ -5,16 +5,19 @@
 package container
 
 import (
-	"context"
+	"io"
+	"strings"
 	"testing"
 
-	"github.com/docker/cli/cli/config"
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/act/common/logging/logtest"
+
 	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) {
@@ -32,15 +35,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()
 
-	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
@@ -54,7 +57,7 @@ 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",
@@ -62,3 +65,21 @@ func TestGetImagePullOptions(t *testing.T) {
 	assert.NoError(t, err, "Failed to create ImagePullOptions") //nolint:testifylint // pre-existing issue from nektos/act
 	assert.Equal(t, "eyJ1c2VybmFtZSI6InVzZXJuYW1lIiwicGFzc3dvcmQiOiJwYXNzd29yZFxuIiwic2VydmVyYWRkcmVzcyI6Imh0dHBzOi8vaW5kZXguZG9ja2VyLmlvL3YxLyJ9", options.RegistryAuth, "RegistryAuth should be taken from local docker config")
 }
+
+// A digest-pinned image is immutable, so its local copy is always current.
+func TestIsPinnedImage(t *testing.T) {
+	assert.True(t, isPinnedImage("alpine@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b"))
+	assert.False(t, isPinnedImage("alpine:latest"))
+}
+
+// The pull path reports a failure the daemon sent mid-stream, so it must carry the reason
+// whichever of the two shapes the daemon used.
+func TestLogDockerResponseError(t *testing.T) {
+	logger := 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"}`))
+}

act/container/docker_run_test.go

@@ -5,9 +5,11 @@
 package container
 
 import (
+	"archive/tar"
 	"bufio"
 	"bytes"
 	"context"
+	"encoding/binary"
 	"errors"
 	"io"
 	"net"
@@ -15,60 +17,44 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
-	"time"
 
 	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/act/common/logging/logtest"
 
+	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/pkg/stdcopy"
 	"github.com/moby/moby/api/types/container"
+	"github.com/moby/moby/api/types/mount"
+	"github.com/moby/moby/api/types/network"
 	mobyclient "github.com/moby/moby/client"
-	"github.com/sirupsen/logrus/hooks/test"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
 	"github.com/stretchr/testify/require"
 )
 
-func TestDocker(t *testing.T) {
-	if testing.Short() {
-		t.Skip("skipping integration test")
-	}
-	ctx := context.Background()
-	client, err := GetDockerClient(ctx)
-	if err != nil {
-		t.Skipf("skipping integration test: %v", err)
-	}
-	defer client.Close()
-
-	dockerBuild := NewDockerBuildExecutor(NewDockerBuildExecutorInput{
-		ContextDir: "testdata",
-		ImageTag:   "envmergetest",
-	})
-
-	err = dockerBuild(ctx)
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
-
-	cr := &containerReference{
-		cli: client,
-		input: &NewContainerInput{
-			Image: "envmergetest",
-		},
-	}
+func TestDockerEnvironmentUsesContainerPath(t *testing.T) {
+	client := &mockDockerClient{}
+	client.On("ContainerInspect", mock.Anything, "amd64-job", mobyclient.ContainerInspectOptions{}).
+		Return(mobyclient.ContainerInspectResult{Container: container.InspectResponse{Config: &container.Config{Env: []string{
+			"PATH=/opt/node/x64/bin:/usr/bin:/bin", "CONFLICT_VAR=container-value", "SOME_RANDOM_VAR=",
+			"ANOTHER_ONE=old-value", "ANOTHER_ONE=BUT_I_HAVE_VALUE", "LITERAL='quoted'=$HOME\nsecond line",
+		}}}}, nil)
 	env := map[string]string{
-		"PATH":         "/usr/local/bin:/usr/bin:/usr/sbin:/bin:/sbin",
+		"PATH":         "/custom/bin",
 		"RANDOM_VAR":   "WITH_VALUE",
 		"ANOTHER_VAR":  "",
-		"CONFLICT_VAR": "I_EXIST_IN_MULTIPLE_PLACES",
+		"CONFLICT_VAR": "step-value",
 	}
-
-	envExecutor := cr.extractFromImageEnv(&env)
-	err = envExecutor(ctx)
-	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
+	require.NoError(t, (&containerReference{cli: client, id: "amd64-job"}).UpdateFromImageEnv(&env)(t.Context()))
 	assert.Equal(t, map[string]string{
-		"PATH":            "/usr/local/bin:/usr/bin:/usr/sbin:/bin:/sbin:/this/path/does/not/exists/anywhere:/this/either",
+		"PATH":            "/custom/bin:/opt/node/x64/bin:/usr/bin:/bin",
 		"RANDOM_VAR":      "WITH_VALUE",
 		"ANOTHER_VAR":     "",
 		"SOME_RANDOM_VAR": "",
 		"ANOTHER_ONE":     "BUT_I_HAVE_VALUE",
-		"CONFLICT_VAR":    "I_EXIST_IN_MULTIPLE_PLACES",
+		"CONFLICT_VAR":    "step-value",
+		"LITERAL":         "'quoted'=$HOME\nsecond line",
 	}, env)
 }
 
@@ -77,6 +63,11 @@ type mockDockerClient struct {
 	mock.Mock
 }
 
+func (m *mockDockerClient) ServerVersion(ctx context.Context, opts mobyclient.ServerVersionOptions) (mobyclient.ServerVersionResult, error) {
+	args := m.Called(ctx, opts)
+	return args.Get(0).(mobyclient.ServerVersionResult), args.Error(1)
+}
+
 func (m *mockDockerClient) ExecCreate(ctx context.Context, id string, opts mobyclient.ExecCreateOptions) (mobyclient.ExecCreateResult, error) {
 	args := m.Called(ctx, id, opts)
 	return args.Get(0).(mobyclient.ExecCreateResult), args.Error(1)
@@ -92,6 +83,11 @@ func (m *mockDockerClient) ExecInspect(ctx context.Context, execID string, opts
 	return args.Get(0).(mobyclient.ExecInspectResult), args.Error(1)
 }
 
+func (m *mockDockerClient) ContainerAttach(ctx context.Context, containerID string, opts mobyclient.ContainerAttachOptions) (mobyclient.ContainerAttachResult, error) {
+	args := m.Called(ctx, containerID, opts)
+	return args.Get(0).(mobyclient.ContainerAttachResult), args.Error(1)
+}
+
 func (m *mockDockerClient) ContainerWait(ctx context.Context, containerID string, opts mobyclient.ContainerWaitOptions) mobyclient.ContainerWaitResult {
 	args := m.Called(ctx, containerID, opts)
 	return args.Get(0).(mobyclient.ContainerWaitResult)
@@ -102,12 +98,57 @@ func (m *mockDockerClient) CopyToContainer(ctx context.Context, id string, optio
 	return args.Get(0).(mobyclient.CopyToContainerResult), args.Error(1)
 }
 
-type endlessReader struct {
-	io.Reader
+func (m *mockDockerClient) ContainerInspect(ctx context.Context, id string, opts mobyclient.ContainerInspectOptions) (mobyclient.ContainerInspectResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.ContainerInspectResult), args.Error(1)
 }
 
-func (r endlessReader) Read(_ []byte) (n int, err error) {
-	return 1, nil
+func (m *mockDockerClient) ContainerList(ctx context.Context, opts mobyclient.ContainerListOptions) (mobyclient.ContainerListResult, error) {
+	args := m.Called(ctx, opts)
+	return args.Get(0).(mobyclient.ContainerListResult), args.Error(1)
+}
+
+func (m *mockDockerClient) ContainerRemove(ctx context.Context, id string, opts mobyclient.ContainerRemoveOptions) (mobyclient.ContainerRemoveResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.ContainerRemoveResult), args.Error(1)
+}
+
+func (m *mockDockerClient) ContainerKill(ctx context.Context, id string, opts mobyclient.ContainerKillOptions) (mobyclient.ContainerKillResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.ContainerKillResult), args.Error(1)
+}
+
+func (m *mockDockerClient) NetworkList(ctx context.Context, opts mobyclient.NetworkListOptions) (mobyclient.NetworkListResult, error) {
+	args := m.Called(ctx, opts)
+	return args.Get(0).(mobyclient.NetworkListResult), args.Error(1)
+}
+
+func (m *mockDockerClient) NetworkCreate(ctx context.Context, name string, opts mobyclient.NetworkCreateOptions) (mobyclient.NetworkCreateResult, error) {
+	args := m.Called(ctx, name, opts)
+	return args.Get(0).(mobyclient.NetworkCreateResult), args.Error(1)
+}
+
+func (m *mockDockerClient) NetworkInspect(ctx context.Context, id string, opts mobyclient.NetworkInspectOptions) (mobyclient.NetworkInspectResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.NetworkInspectResult), args.Error(1)
+}
+
+func (m *mockDockerClient) NetworkRemove(ctx context.Context, id string, opts mobyclient.NetworkRemoveOptions) (mobyclient.NetworkRemoveResult, error) {
+	args := m.Called(ctx, id, opts)
+	return args.Get(0).(mobyclient.NetworkRemoveResult), args.Error(1)
+}
+
+type interruptReader struct {
+	started     chan struct{}
+	interrupted chan struct{}
+	stopped     chan struct{}
+}
+
+func (r *interruptReader) Read(_ []byte) (int, error) {
+	close(r.started)
+	<-r.interrupted
+	close(r.stopped)
+	return 0, io.EOF
 }
 
 type mockConn struct {
@@ -125,18 +166,19 @@ func (m *mockConn) Close() (err error) {
 }
 
 func TestDockerExecAbort(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
+	ctx, cancel := context.WithCancel(t.Context())
 
+	reader := &interruptReader{started: make(chan struct{}), interrupted: make(chan struct{}), stopped: make(chan struct{})}
 	conn := &mockConn{}
-	conn.On("Write", mock.AnythingOfType("[]uint8")).Return(1, nil)
+	conn.On("Write", []byte{3}).
+		Run(func(mock.Arguments) { close(reader.interrupted) }).
+		Return(1, nil)
 
 	client := &mockDockerClient{}
 	client.On("ExecCreate", ctx, "123", mock.AnythingOfType("client.ExecCreateOptions")).Return(mobyclient.ExecCreateResult{ID: "id"}, nil)
 	client.On("ExecAttach", ctx, "id", mock.AnythingOfType("client.ExecAttachOptions")).Return(mobyclient.ExecAttachResult{
-		HijackedResponse: mobyclient.HijackedResponse{
-			Conn:   conn,
-			Reader: bufio.NewReader(endlessReader{}),
-		},
+		Conn:   conn,
+		Reader: bufio.NewReader(reader),
 	}, nil)
 
 	cr := &containerReference{
@@ -153,11 +195,11 @@ func TestDockerExecAbort(t *testing.T) {
 		channel <- cr.exec([]string{""}, map[string]string{}, "user", "workdir")(ctx)
 	}()
 
-	time.Sleep(500 * time.Millisecond)
-
+	<-reader.started
 	cancel()
 
 	err := <-channel
+	<-reader.stopped
 	assert.ErrorIs(t, err, context.Canceled) //nolint:testifylint // pre-existing issue from nektos/act
 
 	conn.AssertExpectations(t)
@@ -165,17 +207,15 @@ func TestDockerExecAbort(t *testing.T) {
 }
 
 func TestDockerExecFailure(t *testing.T) {
-	ctx := context.Background()
+	ctx := t.Context()
 
 	conn := &mockConn{}
 
 	client := &mockDockerClient{}
 	client.On("ExecCreate", ctx, "123", mock.AnythingOfType("client.ExecCreateOptions")).Return(mobyclient.ExecCreateResult{ID: "id"}, nil)
 	client.On("ExecAttach", ctx, "id", mock.AnythingOfType("client.ExecAttachOptions")).Return(mobyclient.ExecAttachResult{
-		HijackedResponse: mobyclient.HijackedResponse{
-			Conn:   conn,
-			Reader: bufio.NewReader(strings.NewReader("output")),
-		},
+		Conn:   conn,
+		Reader: bufio.NewReader(strings.NewReader("output")),
 	}, nil)
 	client.On("ExecInspect", ctx, "id", mobyclient.ExecInspectOptions{}).Return(mobyclient.ExecInspectResult{
 		ExitCode: 1,
@@ -199,8 +239,71 @@ func TestDockerExecFailure(t *testing.T) {
 	client.AssertExpectations(t)
 }
 
+// stdcopyFrame wraps payload in a single Docker multiplexed-stream frame, the
+// format StdCopy expects: an 8-byte header (stream type + 4-byte big-endian
+// length) followed by the payload.
+func stdcopyFrame(stream stdcopy.StdType, payload string) []byte {
+	b := make([]byte, 8+len(payload))
+	b[0] = byte(stream)
+	binary.BigEndian.PutUint32(b[4:8], uint32(len(payload)))
+	copy(b[8:], payload)
+	return b
+}
+
+// TestDockerAttachFlushesTrailingLine verifies that wait() blocks until the
+// attach() streaming goroutine has drained and flushed the container's output,
+// so a final line without a trailing newline is not lost.
+func TestDockerAttachFlushesTrailingLine(t *testing.T) {
+	ctx := t.Context()
+
+	framed := bytes.NewBuffer(stdcopyFrame(stdcopy.Stdout, "line one\nlast line without newline"))
+
+	var lines []string
+	logWriter := common.NewLineWriter(func(s string) bool {
+		lines = append(lines, s)
+		return true
+	})
+
+	client := &mockDockerClient{}
+	client.On("ContainerAttach", ctx, "123", mock.AnythingOfType("client.ContainerAttachOptions")).
+		Return(mobyclient.ContainerAttachResult{
+			Conn:   &mockConn{},
+			Reader: bufio.NewReader(framed),
+		}, nil)
+
+	statusCh := make(chan container.WaitResponse, 1)
+	statusCh <- container.WaitResponse{StatusCode: 0}
+	errCh := make(chan error, 1)
+	client.On("ContainerWait", ctx, "123", mobyclient.ContainerWaitOptions{Condition: container.WaitConditionNotRunning}).
+		Return(mobyclient.ContainerWaitResult{
+			Result: (<-chan container.WaitResponse)(statusCh),
+			Error:  (<-chan error)(errCh),
+		})
+
+	cr := &containerReference{
+		id:  "123",
+		cli: client,
+		input: &NewContainerInput{
+			Image:  "image",
+			Stdout: logWriter,
+			Stderr: logWriter,
+		},
+	}
+
+	require.NoError(t, cr.attach()(ctx))
+	require.NoError(t, cr.wait()(ctx))
+
+	// wait() must have blocked until the goroutine drained AND flushed; the
+	// trailing, non-newline-terminated line must therefore be present. Reading
+	// lines here is race-free because wait() synchronizes on attachDone, which
+	// the goroutine closes after the final append.
+	assert.Equal(t, []string{"line one\n", "last line without newline"}, lines)
+
+	client.AssertExpectations(t)
+}
+
 func TestDockerWaitFailure(t *testing.T) {
-	ctx := context.Background()
+	ctx := t.Context()
 
 	statusCh := make(chan container.WaitResponse, 1)
 	statusCh <- container.WaitResponse{StatusCode: 2}
@@ -230,76 +333,196 @@ func TestDockerWaitFailure(t *testing.T) {
 	client.AssertExpectations(t)
 }
 
-func TestDockerCopyTarStream(t *testing.T) {
-	ctx := context.Background()
+// A remove that raced the daemon's AutoRemove teardown is not a failure and must not
+// be logged as one.
+func TestRemoveIgnoresAutoRemoveRace(t *testing.T) {
+	removeFailure := errors.New("driver failed to remove root filesystem")
+	removeOpts := mobyclient.ContainerRemoveOptions{RemoveVolumes: true, Force: true}
+	killOpts := mobyclient.ContainerKillOptions{Signal: "SIGKILL"}
+	for _, tc := range []struct {
+		name     string
+		err      error
+		wantWait bool
+		waitErr  error
+		wantErr  error
+	}{
+		{name: "removal in progress", err: cerrdefs.ErrConflict.WithMessage("removal of container abc is already in progress"), wantWait: true},
+		{name: "wait canceled", err: cerrdefs.ErrConflict, wantWait: true, waitErr: context.Canceled, wantErr: context.Canceled},
+		{name: "removed during wait", err: cerrdefs.ErrConflict, wantWait: true, waitErr: cerrdefs.ErrNotFound},
+		{name: "already removed", err: cerrdefs.ErrNotFound.WithMessage("No such container: abc")},
+		{name: "removed cleanly", err: nil},
+		{name: "real failure", err: removeFailure, wantErr: removeFailure},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			logger, hook := logtest.NewLogger()
+			ctx := common.WithLogger(t.Context(), logger)
+			client := &mockDockerClient{}
+			client.On("ContainerKill", ctx, "abc", killOpts).Return(mobyclient.ContainerKillResult{}, nil)
+			client.On("ContainerRemove", ctx, "abc", removeOpts).Return(mobyclient.ContainerRemoveResult{}, tc.err)
+			if tc.wantWait {
+				removed := make(chan container.WaitResponse, 1)
+				waitErrors := make(chan error, 1)
+				if tc.waitErr == nil {
+					removed <- container.WaitResponse{}
+				} else {
+					waitErrors <- tc.waitErr
+				}
+				client.On("ContainerWait", mock.Anything, "abc", mobyclient.ContainerWaitOptions{Condition: container.WaitConditionRemoved}).
+					Return(mobyclient.ContainerWaitResult{Result: removed, Error: waitErrors})
+			}
+			cr := &containerReference{id: "abc", cli: client}
 
-	client := &mockDockerClient{}
-	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/" && opts.Content != nil
-	})).Return(mobyclient.CopyToContainerResult{}, nil)
-	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/var/run/act" && opts.Content != nil
-	})).Return(mobyclient.CopyToContainerResult{}, nil)
-	cr := &containerReference{
-		id:  "123",
-		cli: client,
-		input: &NewContainerInput{
-			Image: "image",
-		},
+			require.ErrorIs(t, cr.remove()(ctx), tc.wantErr)
+			if tc.wantErr != nil {
+				assert.Equal(t, "abc", cr.id)
+			} else {
+				assert.Empty(t, cr.id)
+			}
+			assert.Empty(t, hook.AllRecords())
+			client.AssertExpectations(t)
+		})
 	}
+}
 
-	_ = cr.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{})
+// A container whose id was never learned, because find() could not reach the daemon or
+// create() lost its reply, must still be removed rather than leaking with its network. It
+// was never started here, so it is not worth a kill of its own.
+func TestRemoveWithoutIDUsesName(t *testing.T) {
+	ctx := t.Context()
+	client := &mockDockerClient{}
+	client.On("ContainerRemove", ctx, "job-1", mobyclient.ContainerRemoveOptions{RemoveVolumes: true, Force: true}).
+		Return(mobyclient.ContainerRemoveResult{}, nil)
+	cr := &containerReference{cli: client, input: &NewContainerInput{Name: "job-1"}}
 
+	require.NoError(t, cr.remove()(ctx))
 	client.AssertExpectations(t)
 }
 
-func TestDockerCopyTarStreamErrorInCopyFiles(t *testing.T) {
-	ctx := context.Background()
-
-	merr := errors.New("Failure")
-
-	client := &mockDockerClient{}
-	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/" && opts.Content != nil
-	})).Return(mobyclient.CopyToContainerResult{}, merr)
-	cr := &containerReference{
-		id:  "123",
-		cli: client,
-		input: &NewContainerInput{
-			Image: "image",
-		},
+// find() must drop a stale cached id so later Copy/Exec don't hit the
+// daemon with a torn-down container.
+func TestFindRevalidatesStaleID(t *testing.T) {
+	ctx := t.Context()
+	notFound := cerrdefs.ErrNotFound.WithMessage("No such container")
+	boom := errors.New("daemon unreachable")
+	newCR := func(id string) (*containerReference, *mockDockerClient) {
+		client := &mockDockerClient{}
+		return &containerReference{id: id, cli: client, input: &NewContainerInput{Name: "job-1"}}, client
 	}
+	listOpts := mobyclient.ContainerListOptions{All: true}
+	inspectOpts := mobyclient.ContainerInspectOptions{}
 
-	err := cr.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{})
-	assert.ErrorIs(t, err, merr) //nolint:testifylint // pre-existing issue from nektos/act
+	t.Run("stale id cleared, name lookup empty", func(t *testing.T) {
+		cr, client := newCR("stale")
+		client.On("ContainerInspect", ctx, "stale", inspectOpts).Return(mobyclient.ContainerInspectResult{}, notFound)
+		client.On("ContainerList", ctx, listOpts).Return(mobyclient.ContainerListResult{}, nil)
+		require.NoError(t, cr.find()(ctx))
+		assert.Empty(t, cr.id)
+		client.AssertExpectations(t)
+	})
 
-	client.AssertExpectations(t)
+	t.Run("stale id cleared, name lookup repopulates", func(t *testing.T) {
+		cr, client := newCR("stale")
+		client.On("ContainerInspect", ctx, "stale", inspectOpts).Return(mobyclient.ContainerInspectResult{}, notFound)
+		client.On("ContainerList", ctx, listOpts).Return(mobyclient.ContainerListResult{Items: []container.Summary{
+			{ID: "other", Names: []string{"/somebody-else"}},
+			{ID: "fresh", Names: []string{"/job-1"}},
+		}}, nil)
+		require.NoError(t, cr.find()(ctx))
+		assert.Equal(t, "fresh", cr.id)
+		client.AssertExpectations(t)
+	})
+
+	t.Run("live id kept", func(t *testing.T) {
+		cr, client := newCR("live")
+		client.On("ContainerInspect", ctx, "live", inspectOpts).Return(mobyclient.ContainerInspectResult{}, nil)
+		require.NoError(t, cr.find()(ctx))
+		assert.Equal(t, "live", cr.id)
+		client.AssertExpectations(t)
+	})
+
+	t.Run("transient inspect error trusts cache", func(t *testing.T) {
+		cr, client := newCR("live")
+		client.On("ContainerInspect", ctx, "live", inspectOpts).Return(mobyclient.ContainerInspectResult{}, boom)
+		require.NoError(t, cr.find()(ctx))
+		assert.Equal(t, "live", cr.id)
+		client.AssertExpectations(t)
+	})
+
+	t.Run("list error propagates", func(t *testing.T) {
+		cr, client := newCR("")
+		client.On("ContainerList", ctx, listOpts).Return(mobyclient.ContainerListResult{}, boom)
+		require.ErrorIs(t, cr.find()(ctx), boom)
+		client.AssertExpectations(t)
+	})
 }
 
-func TestDockerCopyTarStreamErrorInMkdir(t *testing.T) {
-	ctx := context.Background()
-
-	merr := errors.New("Failure")
-
+// Every daemon entry point fails fast with a clear, container-named
+// error when no live cr.id is known.
+func TestRejectsMissingContainer(t *testing.T) {
+	ctx := t.Context()
 	client := &mockDockerClient{}
-	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/" && opts.Content != nil
-	})).Return(mobyclient.CopyToContainerResult{}, nil)
-	client.On("CopyToContainer", ctx, "123", mock.MatchedBy(func(opts mobyclient.CopyToContainerOptions) bool {
-		return opts.DestinationPath == "/var/run/act" && opts.Content != nil
-	})).Return(mobyclient.CopyToContainerResult{}, merr)
-	cr := &containerReference{
-		id:  "123",
-		cli: client,
-		input: &NewContainerInput{
-			Image: "image",
-		},
+	client.On("ContainerList", ctx, mobyclient.ContainerListOptions{All: true}).Return(mobyclient.ContainerListResult{}, nil)
+	cr := &containerReference{cli: client, input: &NewContainerInput{Name: "job-1"}}
+	check := func(op string, err error) {
+		t.Helper()
+		require.ErrorIs(t, err, ErrContainerNotFound, op)
+		assert.Contains(t, err.Error(), `container "job-1" does not exist`, op)
 	}
+	check("copyContent", cr.copyContent("/var/run/act", &FileEntry{Name: "x", Mode: 0o644})(ctx))
+	check("copyDir", cr.copyDir("/var/run/act", "/src", false, false)(ctx))
+	check("exec", cr.exec([]string{"echo"}, nil, "", "")(ctx))
+	_, err := cr.GetContainerArchive(ctx, "/var/run/act/x")
+	check("GetContainerArchive", err)
+	_, err = cr.Inspect(ctx)
+	check("Inspect", err)
 
-	err := cr.CopyTarStream(ctx, "/var/run/act", &bytes.Buffer{})
-	assert.ErrorIs(t, err, merr) //nolint:testifylint // pre-existing issue from nektos/act
+	// a known id the daemon has since dropped
+	client.On("ContainerInspect", ctx, "gone", mobyclient.ContainerInspectOptions{}).
+		Return(mobyclient.ContainerInspectResult{}, cerrdefs.ErrNotFound)
+	removed := &containerReference{id: "gone", cli: client, input: &NewContainerInput{Name: "job-1"}}
+	_, err = removed.Inspect(ctx)
+	check("Inspect after removal", err)
+}
 
-	client.AssertExpectations(t)
+func TestPublicCopyPipelineHandlesStaleID(t *testing.T) {
+	for _, testcase := range []struct {
+		name, destination, extractionRoot, entry string
+		directory                                bool
+	}{
+		{name: "files", destination: "/var/run/act", extractionRoot: "/var/run/act", entry: "x"},
+		{name: "action below act volume", directory: true, destination: "/var/run/act/actions/checkout/", extractionRoot: "/var/run/act", entry: "actions/checkout/x"},
+		{name: "sibling prefix", directory: true, destination: "/var/run/actor/action", extractionRoot: "/", entry: "var/run/actor/action/x"},
+	} {
+		t.Run(testcase.name, func(t *testing.T) {
+			ctx := t.Context()
+			client := &mockDockerClient{}
+			client.On("ContainerInspect", ctx, "stale", mobyclient.ContainerInspectOptions{}).
+				Return(mobyclient.ContainerInspectResult{}, cerrdefs.ErrNotFound.WithMessage("gone"))
+			client.On("ContainerList", ctx, mobyclient.ContainerListOptions{All: true}).
+				Return(mobyclient.ContainerListResult{Items: []container.Summary{
+					{ID: "fresh", Names: []string{"/job-1"}},
+				}}, nil)
+			client.On("CopyToContainer", ctx, "fresh", mock.Anything).
+				Run(func(args mock.Arguments) {
+					opts := args.Get(2).(mobyclient.CopyToContainerOptions)
+					assert.Equal(t, testcase.extractionRoot, opts.DestinationPath)
+					header, err := tar.NewReader(opts.Content).Next()
+					require.NoError(t, err)
+					assert.Equal(t, testcase.entry, header.Name)
+				}).Return(mobyclient.CopyToContainerResult{}, nil).Once()
+
+			cr := &containerReference{id: "stale", cli: client, input: &NewContainerInput{Name: "job-1"}}
+			if testcase.directory {
+				source := t.TempDir()
+				require.NoError(t, os.WriteFile(filepath.Join(source, "x"), nil, 0o644))
+				require.NoError(t, cr.CopyDir(testcase.destination, source+string(filepath.Separator), false, true)(ctx))
+			} else {
+				require.NoError(t, cr.Copy(testcase.destination, &FileEntry{Name: "x", Mode: 0o644})(ctx))
+			}
+			assert.Equal(t, "fresh", cr.id)
+			client.AssertExpectations(t)
+		})
+	}
 }
 
 // Type assert containerReference implements ExecutionsEnvironment
@@ -307,10 +530,12 @@ var _ ExecutionsEnvironment = &containerReference{}
 
 func TestCheckVolumes(t *testing.T) {
 	testCases := []struct {
-		desc          string
-		validVolumes  []string
-		binds         []string
-		expectedBinds []string
+		desc           string
+		validVolumes   []string
+		binds          []string
+		expectedBinds  []string
+		mounts         []mount.Mount
+		expectedMounts []mount.Mount
 	}{
 		{
 			desc:         "match all volumes",
@@ -348,11 +573,14 @@ func TestCheckVolumes(t *testing.T) {
 				"shared_volume",
 				"/home/test/data",
 				"/etc/conf.d/*.json",
+				"/opt/**",
 			},
 			binds: []string{
 				"shared_volume:/shared_volume",
 				"/home/test/data:/test_data",
 				"/etc/conf.d/base.json:/config/base.json",
+				"/etc/conf.d/sub/nested.json:/config/nested.json",
+				"/opt/app/cache:/cache",
 				"sql_data:/sql_data",
 				"/secrets/keys:/keys",
 			},
@@ -360,27 +588,186 @@ func TestCheckVolumes(t *testing.T) {
 				"shared_volume:/shared_volume",
 				"/home/test/data:/test_data",
 				"/etc/conf.d/base.json:/config/base.json",
+				"/opt/app/cache:/cache",
 			},
 		},
+		{
+			desc:          "read-only rules allow only read-only mounts and copy nothing into volumes",
+			validVolumes:  []string{"/etc/ssl:ro", "data:ro", "shared"},
+			binds:         []string{"/etc/ssl:/ssl:ro", "/etc/ssl:/ssl", "data:/data:ro", "data:/data", "shared:/shared:ro"},
+			expectedBinds: []string{"/etc/ssl:/ssl:ro", "data:/data:ro,nocopy", "shared:/shared:ro"},
+			mounts: []mount.Mount{
+				{Type: mount.TypeBind, Source: "/etc/ssl", Target: "/ssl", ReadOnly: true},
+				{Type: mount.TypeBind, Source: "/etc/ssl", Target: "/ssl", ReadOnly: true, BindOptions: &mount.BindOptions{ReadOnlyNonRecursive: true}},
+				{Type: mount.TypeVolume, Source: "data", Target: "/data", ReadOnly: true},
+			},
+			expectedMounts: []mount.Mount{
+				{Type: mount.TypeBind, Source: "/etc/ssl", Target: "/ssl", ReadOnly: true},
+				{Type: mount.TypeVolume, Source: "data", Target: "/data", ReadOnly: true, VolumeOptions: &mount.VolumeOptions{NoCopy: true}},
+			},
+		},
+		{
+			desc:          "read-only wildcard keeps writable rules writable",
+			validVolumes:  []string{"**:ro", "shared"},
+			binds:         []string{"/etc/ssl:/ssl:ro", "data:/data", "shared:/shared"},
+			expectedBinds: []string{"/etc/ssl:/ssl:ro", "shared:/shared"},
+		},
 	}
 	for _, tc := range testCases {
 		t.Run(tc.desc, func(t *testing.T) {
-			logger, _ := test.NewNullLogger()
-			ctx := common.WithLogger(context.Background(), logger)
+			logger, hook := logtest.NewLogger()
+			ctx := common.WithLogger(t.Context(), logger)
 			cr := &containerReference{
 				input: &NewContainerInput{
 					ValidVolumes: tc.validVolumes,
 				},
 			}
-			_, hostConf := cr.sanitizeConfig(ctx, &container.Config{}, &container.HostConfig{Binds: tc.binds})
+			_, hostConf := cr.sanitizeConfig(ctx, &container.Config{}, &container.HostConfig{Binds: tc.binds, Mounts: tc.mounts})
 			assert.Equal(t, tc.expectedBinds, hostConf.Binds)
+			assert.ElementsMatch(t, tc.expectedMounts, hostConf.Mounts)
+			assert.Len(t, hook.AllRecords(), len(tc.binds)+len(tc.mounts)-len(tc.expectedBinds)-len(tc.expectedMounts)) // every drop is warned about
 		})
 	}
 }
 
+// A volume driver decides for itself what it mounts, e.g. the local driver with device= binds
+// any host path, which valid_volumes never gets to see.
+func TestMergeContainerConfigsDropsVolumeDriversFromWorkflows(t *testing.T) {
+	const escape = "--mount type=volume,src=job-escape,dst=/host,volume-driver=local,volume-opt=type=none,volume-opt=o=bind,volume-opt=device=/"
+
+	hostConfig, _ := mergeOptions(t, "", escape+" --mount type=volume,src=job-plain,dst=/cache", false)
+	require.Len(t, hostConfig.Mounts, 1)
+	assert.Equal(t, "job-plain", hostConfig.Mounts[0].Source)
+
+	// the same mount from the runner's own options is the administrator's to make
+	hostConfig, _ = mergeOptions(t, escape, "", false)
+	require.Len(t, hostConfig.Mounts, 1)
+	assert.Equal(t, "job-escape", hostConfig.Mounts[0].Source)
+}
+
+// Both of these are read here, on the runner, so a workflow could read the runner's files
+// and environment with them.
+func TestMergeContainerConfigsKeepsTheRunnersFilesAndEnvToItself(t *testing.T) {
+	hostFile := filepath.Join(t.TempDir(), "host.env")
+	require.NoError(t, os.WriteFile(hostFile, []byte("STOLEN=from-the-host\n"), 0o600))
+	t.Setenv("RUNNER_SECRET", "s3cr3t")
+
+	for _, option := range []string{"--env-file " + hostFile, "--label-file " + hostFile} {
+		logger := logging.New(logtest.New())
+		cr := &containerReference{input: &NewContainerInput{NetworkMode: "bridge", WorkflowOptions: option}}
+
+		_, _, err := cr.mergeContainerConfigs(common.WithLogger(t.Context(), logger), &container.Config{}, &container.HostConfig{})
+		require.ErrorContains(t, err, "not allowed in a workflow")
+
+		// the runner reading its own files is what those options are for
+		cr = &containerReference{input: &NewContainerInput{NetworkMode: "bridge", RunnerOptions: option}}
+		_, _, err = cr.mergeContainerConfigs(common.WithLogger(t.Context(), logger), &container.Config{}, &container.HostConfig{})
+		require.NoError(t, err)
+	}
+
+	// a bare name is no longer resolved from the runner's environment, for either source
+	logger := logging.New(logtest.New())
+	cr := &containerReference{input: &NewContainerInput{
+		NetworkMode:     "bridge",
+		RunnerOptions:   "--env RUNNER_SECRET",
+		WorkflowOptions: "--env RUNNER_SECRET --env GIVEN=value",
+	}}
+
+	config, _, err := cr.mergeContainerConfigs(common.WithLogger(t.Context(), logger), &container.Config{}, &container.HostConfig{})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"RUNNER_SECRET", "RUNNER_SECRET", "GIVEN=value"}, config.Env)
+}
+
+func TestSanitizeOptionsHostConfig(t *testing.T) {
+	logger := logging.New(logtest.New())
+
+	// every field the sanitizer resets, so a reset dropped in a refactor fails here
+	hostConfig := &container.HostConfig{
+		PidMode:           "host",
+		IpcMode:           "host",
+		UTSMode:           "host",
+		CgroupnsMode:      "host",
+		UsernsMode:        "host",
+		CapAdd:            []string{"ALL"},
+		SecurityOpt:       []string{"seccomp=unconfined", "apparmor=unconfined"},
+		VolumesFrom:       []string{"other"},
+		Runtime:           "runc",
+		Isolation:         "process",
+		VolumeDriver:      "rogue",
+		MaskedPaths:       []string{},
+		ReadonlyPaths:     []string{},
+		CgroupParent:      "/custom",
+		Devices:           []container.DeviceMapping{{PathOnHost: "/dev/sda", PathInContainer: "/dev/sda", CgroupPermissions: "rwm"}},
+		DeviceCgroupRules: []string{"a *:* rwm"},
+		DeviceRequests:    []container.DeviceRequest{{Count: -1, Capabilities: [][]string{{"gpu"}}}},
+		Sysctls:           map[string]string{"net.ipv4.ip_forward": "1"},
+		LogConfig:         container.LogConfig{Type: "syslog", Config: map[string]string{"syslog-address": "tcp://169.254.169.254:514"}},
+		OomScoreAdj:       -1000,
+		OomKillDisable:    new(true),
+	}
+
+	sanitizeOptionsHostConfig(logger, hostConfig, &container.HostConfig{})
+
+	assert.Equal(t, &container.HostConfig{}, hostConfig)
+}
+
+// mergeOptions merges both option sources into a bare container, returning the result and its log.
+func mergeOptions(t *testing.T, runnerOptions, workflowOptions string, privileged bool) (*container.HostConfig, *logtest.Handler) {
+	t.Helper()
+	logger, hook := logtest.NewLogger()
+	cr := &containerReference{input: &NewContainerInput{
+		RunnerOptions:   runnerOptions,
+		WorkflowOptions: workflowOptions,
+		NetworkMode:     "bridge",
+		UsernsMode:      "private",
+		ValidVolumes:    []string{"**"},
+	}}
+
+	_, hostConfig, err := cr.mergeContainerConfigs(common.WithLogger(t.Context(), logger), &container.Config{}, &container.HostConfig{
+		Privileged:  privileged,
+		UsernsMode:  container.UsernsMode("private"),
+		NetworkMode: container.NetworkMode("bridge"),
+	})
+	require.NoError(t, err)
+	return hostConfig, hook
+}
+
+func TestMergeContainerConfigsStripsDangerousOptionsWhenUnprivileged(t *testing.T) {
+	// OS-independent options only, --device and --gpus need a linux/windows server OS
+	const dangerousOptions = "--pid=host --ipc=host --uts=host --cgroupns=host " +
+		"--userns=host --cap-add=ALL --security-opt seccomp=unconfined " +
+		"--security-opt apparmor=unconfined --volumes-from other --isolation process " +
+		"--runtime runc --cgroup-parent /custom --sysctl net.ipv4.ip_forward=1 " +
+		"--log-driver=syslog --log-opt syslog-address=tcp://169.254.169.254:514 " +
+		"--oom-score-adj=-1000 --oom-kill-disable"
+
+	// whatever the workflow adds, an unprivileged container comes out exactly as the runner's
+	// own options alone describe it, field for field
+	for _, runnerOptions := range []string{"--shm-size 1g", dangerousOptions, "--cap-add SYS_ADMIN --security-opt seccomp=unconfined"} {
+		runnerOnly, _ := mergeOptions(t, runnerOptions, "", false)
+		withWorkflow, _ := mergeOptions(t, runnerOptions, dangerousOptions, false)
+
+		assert.Equal(t, runnerOnly, withWorkflow, "runner options: %q", runnerOptions)
+	}
+
+	// the same options from the runner reach the daemon, even --userns, which no workflow may set
+	kept, _ := mergeOptions(t, dangerousOptions, "", false)
+	assert.Equal(t, "host", string(kept.PidMode))
+	assert.Equal(t, []string{"ALL"}, kept.CapAdd)
+	assert.Equal(t, "runc", kept.Runtime)
+	assert.Equal(t, "host", string(kept.UsernsMode))
+	assert.False(t, kept.Privileged)
+
+	// privileged is the administrator opting in, so the workflow's options are honored
+	privileged, _ := mergeOptions(t, "", dangerousOptions, true)
+	assert.Equal(t, "host", string(privileged.PidMode))
+	assert.Equal(t, []string{"ALL"}, privileged.CapAdd)
+	assert.Equal(t, []string{"seccomp=unconfined", "apparmor=unconfined"}, privileged.SecurityOpt)
+}
+
 func TestCheckVolumesRejectsEscapingHostPaths(t *testing.T) {
-	logger, _ := test.NewNullLogger()
-	ctx := common.WithLogger(context.Background(), logger)
+	logger := logging.New(logtest.New())
+	ctx := common.WithLogger(t.Context(), logger)
 
 	base := t.TempDir()
 	allowed := filepath.Join(base, "allowed")
@@ -414,3 +801,182 @@ func TestCheckVolumesRejectsEscapingHostPaths(t *testing.T) {
 	})
 	assert.Empty(t, hostConf.Binds)
 }
+
+func TestSanitizeConfigKeepsTmpfsMounts(t *testing.T) {
+	hostConfig, _ := mergeOptions(t, "", "--mount type=tmpfs,dst=/var/lib/mysql", false)
+	require.Len(t, hostConfig.Mounts, 1)
+
+	for _, validVolumes := range [][]string{nil, {"data"}, {"**:ro"}} {
+		logger, hook := logtest.NewLogger()
+		_, sanitized := (&containerReference{input: &NewContainerInput{ValidVolumes: validVolumes}}).sanitizeConfig(common.WithLogger(t.Context(), logger), &container.Config{}, &container.HostConfig{Mounts: []mount.Mount{
+			hostConfig.Mounts[0],
+			{Type: mount.TypeVolume, Target: "/anonymous"},
+			{Type: mount.TypeTmpfs, Source: "/etc", Target: "/etc-copy"},
+		}})
+		assert.Equal(t, hostConfig.Mounts, sanitized.Mounts)
+		assert.Len(t, hook.AllRecords(), 2)
+	}
+}
+
+func TestContainerInfoFromInspect(t *testing.T) {
+	t.Run("reports no healthcheck when the image declares none", func(t *testing.T) {
+		info := containerInfoFromInspect(container.InspectResponse{
+			ID:    "abc123",
+			State: &container.State{Status: "running", Running: true},
+		})
+
+		assert.Equal(t, "abc123", info.ID)
+		assert.Equal(t, "running", info.State)
+		assert.Equal(t, HealthNone, info.Health)
+		assert.Empty(t, info.Ports)
+	})
+
+	t.Run("reports the health status and the last probe output", func(t *testing.T) {
+		info := containerInfoFromInspect(container.InspectResponse{
+			State: &container.State{
+				Status: "running",
+				Health: &container.Health{
+					Status: container.Unhealthy,
+					Log: []*container.HealthcheckResult{
+						{Output: "first\n"},
+						{Output: "connection refused\n"},
+					},
+				},
+			},
+		})
+
+		assert.Equal(t, HealthUnhealthy, info.Health)
+		assert.Equal(t, "connection refused", info.HealthOutput)
+	})
+
+	t.Run("reports the published ports", func(t *testing.T) {
+		info := containerInfoFromInspect(container.InspectResponse{
+			State: &container.State{Status: "running"},
+			NetworkSettings: &container.NetworkSettings{
+				Ports: network.PortMap{
+					network.MustParsePort("5432/tcp"): []network.PortBinding{{HostPort: "49153"}},
+					network.MustParsePort("6379/tcp"): nil,
+				},
+			},
+		})
+
+		assert.Equal(t, map[string]string{"5432": "49153"}, info.Ports)
+	})
+
+	t.Run("tolerates a container without state", func(t *testing.T) {
+		info := containerInfoFromInspect(container.InspectResponse{ID: "abc123"})
+
+		assert.Equal(t, "abc123", info.ID)
+		assert.Equal(t, HealthNone, info.Health)
+	})
+
+	t.Run("reports the mount sources by container path", func(t *testing.T) {
+		info := containerInfoFromInspect(container.InspectResponse{
+			Mounts: []container.MountPoint{
+				{Type: mount.TypeVolume, Name: "job", Source: "/var/lib/docker/volumes/job/_data", Destination: "/workspace/owner/repo"},
+				{Type: mount.TypeBind, Source: "/var/run/docker.sock", Destination: "/var/run/docker.sock"},
+				{Type: mount.TypeVolume, Name: "cache", Source: "/var/lib/docker/volumes/cache/_data", Destination: "/cache"},
+				{Type: mount.TypeBind, Source: "/custom/resolv.conf", Destination: "/etc/resolv.conf"},
+			},
+			HostConfig: &container.HostConfig{
+				Tmpfs:  map[string]string{"/workspace/owner/repo//tmp/": "size=1m"},
+				Mounts: []mount.Mount{{Type: mount.TypeVolume, Source: "cache", Target: "/cache/", VolumeOptions: &mount.VolumeOptions{Subpath: "project"}}},
+			},
+		})
+
+		assert.Equal(t, map[string]string{
+			"/workspace/owner/repo":     "/var/lib/docker/volumes/job/_data",
+			"/workspace/owner/repo/tmp": "",
+			"/var/run/docker.sock":      "/var/run/docker.sock",
+			"/cache":                    "/var/lib/docker/volumes/cache/_data/project",
+			"/etc/resolv.conf":          "/custom/resolv.conf",
+			"/etc/hosts":                "",
+			"/etc/hostname":             "",
+		}, info.Mounts)
+	})
+}
+
+func TestMergeContainerConfigsVolumesReplaceRunnerMounts(t *testing.T) {
+	logger := logging.New(logtest.New())
+	ctx := common.WithLogger(t.Context(), logger)
+	cr := &containerReference{
+		input: &NewContainerInput{
+			NetworkMode:     "bridge",
+			RunnerOptions:   "--volume /host/tools:/opt/hostedtoolcache",
+			WorkflowOptions: "--volume /unapproved:/var/run/docker.sock",
+			ValidVolumes:    []string{"/host/tools"},
+		},
+	}
+
+	_, hostConf, err := cr.mergeContainerConfigs(ctx, &container.Config{}, &container.HostConfig{
+		Binds:  []string{"/var/run/docker.sock:/var/run/docker.sock"},
+		Mounts: []mount.Mount{{Type: mount.TypeVolume, Source: "act-toolcache", Target: "/opt/hostedtoolcache"}},
+	})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"/var/run/docker.sock:/var/run/docker.sock", "/host/tools:/opt/hostedtoolcache"}, hostConf.Binds)
+	assert.Empty(t, hostConf.Mounts)
+}
+
+func TestMergeContainerConfigsWarnsOnlyAboutOptionsThatWereGiven(t *testing.T) {
+	warnings := func(runnerOptions, workflowOptions string) int {
+		_, hook := mergeOptions(t, runnerOptions, workflowOptions, false)
+		return len(hook.AllRecords())
+	}
+
+	assert.Zero(t, warnings("--volume /host/tools:/opt/hostedtoolcache", ""))
+	assert.Zero(t, warnings("", "--shm-size 1g"))
+	assert.Equal(t, 1, warnings("--network host", ""))
+	assert.Equal(t, 1, warnings("", "--privileged"))
+}
+
+func TestDockerCreateKeepsInputEntrypoint(t *testing.T) {
+	for _, entrypoint := range [][]string{nil, {"sleep", "3600"}} {
+		for _, optionEntrypoint := range []string{"/sbin/dumb-init", ""} {
+			logger, hook := logtest.NewLogger()
+			cr := &containerReference{
+				input: &NewContainerInput{
+					NetworkMode:     "bridge",
+					Entrypoint:      entrypoint,
+					RunnerOptions:   "--entrypoint=runner-entrypoint",
+					WorkflowOptions: "--entrypoint=" + optionEntrypoint + " --init",
+				},
+				cli: &probeClient{create: func(opts mobyclient.ContainerCreateOptions) (mobyclient.ContainerCreateResult, error) {
+					if len(entrypoint) > 0 {
+						assert.Equal(t, entrypoint, opts.Config.Entrypoint)
+					} else {
+						assert.Equal(t, []string{optionEntrypoint}, opts.Config.Entrypoint)
+					}
+					require.NotNil(t, opts.HostConfig.Init)
+					assert.True(t, *opts.HostConfig.Init)
+					return mobyclient.ContainerCreateResult{ID: "created"}, nil
+				}},
+			}
+			require.NoError(t, cr.create(nil, nil)(common.WithLogger(t.Context(), logger)))
+			assert.Equal(t, "created", cr.id)
+			assert.Equal(t, len(entrypoint) > 0, len(hook.AllRecords()) == 1)
+		}
+	}
+}
+
+func TestMergeContainerConfigsKeepsNetworkAliasesFromOptions(t *testing.T) {
+	logger := logging.New(logtest.New())
+	cr := &containerReference{input: &NewContainerInput{
+		NetworkMode: "job-network", NetworkAliases: []string{"redis"}, WorkflowOptions: "--network-alias redis-primary",
+	}}
+
+	_, _, err := cr.mergeContainerConfigs(common.WithLogger(t.Context(), logger), &container.Config{}, &container.HostConfig{})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"redis", "redis-primary"}, cr.input.NetworkAliases)
+}
+
+// A dead daemon must fail the job, not panic through logrus and not silently
+// drop the requested platform.
+func TestSupportsContainerImagePlatformDaemonError(t *testing.T) {
+	cli := &mockDockerClient{}
+	cli.On("ServerVersion", mock.Anything, mock.Anything).
+		Return(mobyclient.ServerVersionResult{}, errors.New("cannot connect to the Docker daemon"))
+
+	supported, err := supportsContainerImagePlatform(t.Context(), cli)
+	require.ErrorContains(t, err, "cannot connect to the Docker daemon")
+	assert.False(t, supported)
+}

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,154 +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 TestGetSocketAndHostWithSocket(t *testing.T) {
-	// Arrange
-	CommonSocketLocations = originalCommonSocketLocations
-	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
-	socketURI := "/path/to/my.socket"
-	os.Unsetenv("DOCKER_HOST")
-	CommonSocketLocations = originalCommonSocketLocations
-	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
-	CommonSocketLocations = originalCommonSocketLocations
-	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
-	CommonSocketLocations = originalCommonSocketLocations
-	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
-	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
-	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
-	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))
+
+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,51 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+
+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) {
+	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)
+
+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

@@ -8,14 +8,20 @@ package container
 
 import (
 	"context"
+	"errors"
+	"net/netip"
 	"runtime"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
 	"github.com/moby/moby/api/types/system"
-	"github.com/pkg/errors"
 )
 
+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) {
@@ -28,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 {
@@ -61,7 +79,7 @@ func NewDockerVolumeRemoveExecutor(volume string, force bool) common.Executor {
 	}
 }
 
-func NewDockerNetworkCreateExecutor(name string) common.Executor {
+func NewDockerNetworkCreateExecutor(name string, opts NewDockerNetworkCreateExecutorInput) common.Executor {
 	return func(ctx context.Context) error {
 		return nil
 	}
@@ -72,3 +90,31 @@ func NewDockerNetworkRemoveExecutor(name string) common.Executor {
 		return nil
 	}
 }
+
+func NewDockerNetworkConnectExecutor(_, _ string) common.Executor {
+	return func(_ context.Context) error {
+		return nil
+	}
+}
+
+func NewDockerNetworkDisconnectExecutor(_, _ string) common.Executor {
+	return func(_ context.Context) error {
+		return nil
+	}
+}
+
+func RemoveOrphanNetworks(_ context.Context, _, _ string, _ time.Time) error {
+	return nil
+}
+
+func SanitizeBinds(_ context.Context, _, binds []string) []string {
+	return binds
+}
+
+func CreateJobVolumes(ctx context.Context, runnerUUID string, volumeNames []string) error {
+	return nil
+}
+
+func RemoveOrphanJobVolumes(ctx context.Context, runnerUUID string, createdBefore time.Time) error {
+	return nil
+}

act/container/docker_volume.go

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

act/container/helpers_test.go

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

act/container/host_environment.go

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

act/container/host_environment_test.go

@@ -15,10 +15,11 @@ import (
 	"runtime"
 	"strings"
 	"testing"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/common/logging"
 
-	"github.com/sirupsen/logrus"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -26,28 +27,42 @@ import (
 // Type assert HostEnvironment implements ExecutionsEnvironment
 var _ ExecutionsEnvironment = &HostEnvironment{}
 
+func TestActionPlatformNames(t *testing.T) {
+	assert.Equal(t, []string{"Linux", "macOS", "Windows"}, []string{goOsToActionOs("linux"), goOsToActionOs("darwin"), goOsToActionOs("windows")})
+	assert.Equal(t, []string{"X86", "X64", "ARM", "ARM64"}, []string{goArchToActionArch("386"), goArchToActionArch("amd64"), goArchToActionArch("arm"), goArchToActionArch("arm64")})
+}
+
 func TestCopyDir(t *testing.T) {
-	dir := t.TempDir()
-	ctx := context.Background()
-	e := &HostEnvironment{
-		Path:      filepath.Join(dir, "path"),
-		TmpDir:    filepath.Join(dir, "tmp"),
-		ToolCache: filepath.Join(dir, "tool_cache"),
-		ActPath:   filepath.Join(dir, "act_path"),
-		StdOut:    os.Stdout,
-		Workdir:   path.Join("testdata", "scratch"),
+	for _, test := range []struct {
+		name                     string
+		useGitIgnore, skipGitDir bool
+	}{
+		{name: "git dir kept for a workspace copy"},
+		{name: "git dir skipped for an action copy", skipGitDir: true},
+		{name: "unfiltered outside a git repository", useGitIgnore: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			src := filepath.Join(t.TempDir(), "action")
+			require.NoError(t, os.MkdirAll(filepath.Join(src, ".git", "objects"), 0o700))
+			require.NoError(t, os.WriteFile(filepath.Join(src, ".git", "objects", "pack"), []byte("x"), 0o600))
+			require.NoError(t, os.WriteFile(filepath.Join(src, "action.yml"), []byte("name: x\n"), 0o600))
+
+			dest := filepath.Join(t.TempDir(), "dest")
+			require.NoError(t, (&HostEnvironment{}).CopyDir(dest, src+string(filepath.Separator), test.useGitIgnore, test.skipGitDir)(t.Context()))
+
+			assert.FileExists(t, filepath.Join(dest, "action.yml"))
+			if test.skipGitDir {
+				assert.NoDirExists(t, filepath.Join(dest, ".git"))
+			} else {
+				assert.FileExists(t, filepath.Join(dest, ".git", "objects", "pack"))
+			}
+		})
 	}
-	_ = os.MkdirAll(e.Path, 0o700)
-	_ = os.MkdirAll(e.TmpDir, 0o700)
-	_ = os.MkdirAll(e.ToolCache, 0o700)
-	_ = os.MkdirAll(e.ActPath, 0o700)
-	err := e.CopyDir(e.Workdir, e.Path, true)(ctx)
-	assert.NoError(t, err)
 }
 
 func TestGetContainerArchive(t *testing.T) {
 	dir := t.TempDir()
-	ctx := context.Background()
+	ctx := t.Context()
 	e := &HostEnvironment{
 		Path:      filepath.Join(dir, "path"),
 		TmpDir:    filepath.Join(dir, "tmp"),
@@ -82,7 +97,7 @@ func TestHostEnvironmentExecExitCode(t *testing.T) {
 		t.Skip("uses POSIX shell")
 	}
 	dir := t.TempDir()
-	ctx := context.Background()
+	ctx := t.Context()
 	e := &HostEnvironment{
 		Path:      filepath.Join(dir, "path"),
 		TmpDir:    filepath.Join(dir, "tmp"),
@@ -133,7 +148,7 @@ func TestHostEnvironmentAllocatePTY(t *testing.T) {
 			err := e.Exec(
 				[]string{"sh", "-c", "[ -t 1 ] && printf TTY || printf NOTTY"},
 				map[string]string{"PATH": os.Getenv("PATH")}, "", "",
-			)(context.Background())
+			)(t.Context())
 			require.NoError(t, err)
 			got := strings.TrimSpace(strings.ReplaceAll(buf.String(), "\r", ""))
 			assert.Equal(t, tc.expect, got)
@@ -142,8 +157,7 @@ func TestHostEnvironmentAllocatePTY(t *testing.T) {
 }
 
 func TestHostEnvironmentRemovePreservesWorkdirByDefault(t *testing.T) {
-	logger := logrus.New()
-	ctx := common.WithLogger(context.Background(), logrus.NewEntry(logger))
+	ctx := common.WithLogger(t.Context(), logging.Default())
 	base := t.TempDir()
 	miscRoot := filepath.Join(base, "misc")
 	path := filepath.Join(miscRoot, "hostexecutor")
@@ -165,8 +179,7 @@ func TestHostEnvironmentRemovePreservesWorkdirByDefault(t *testing.T) {
 }
 
 func TestHostEnvironmentRemoveCleansWorkdirWhenOwned(t *testing.T) {
-	logger := logrus.New()
-	ctx := common.WithLogger(context.Background(), logrus.NewEntry(logger))
+	ctx := common.WithLogger(t.Context(), logging.Default())
 	base := t.TempDir()
 	miscRoot := filepath.Join(base, "misc")
 	path := filepath.Join(miscRoot, "hostexecutor")
@@ -187,3 +200,174 @@ func TestHostEnvironmentRemoveCleansWorkdirWhenOwned(t *testing.T) {
 	_, err := os.Stat(workdir)
 	assert.ErrorIs(t, err, os.ErrNotExist)
 }
+
+func TestRemoveAllWithContextDoesNotHangOnStuckDelete(t *testing.T) {
+	release := make(chan struct{})
+	stubDone := make(chan struct{})
+
+	orig := removeAll
+	removeAll = func(string) error {
+		defer close(stubDone)
+		<-release
+		return nil
+	}
+	// removeAllWithContext intentionally leaks the delete goroutine on timeout,
+	// and that goroutine still references removeAll. Unblock it and wait for it
+	// to return before restoring the var, so the restore can't race the read.
+	t.Cleanup(func() {
+		close(release)
+		<-stubDone
+		removeAll = orig
+	})
+
+	ctx, cancel := context.WithTimeout(t.Context(), 100*time.Millisecond)
+	defer cancel()
+
+	err := removeAllWithContext(ctx, t.TempDir())
+	require.ErrorIs(t, err, context.DeadlineExceeded)
+}
+
+// TestHostEnvironmentRemoveDoesNotHangOnStuckCleanUp guards against a stalled
+// CleanUp callback (e.g. an os.RemoveAll blocked by an AV/EDR filter driver or
+// an unresponsive mount) wedging the runner slot forever at "Cleaning up
+// container". Remove must time out the callback and complete job teardown.
+func TestHostEnvironmentRemoveDoesNotHangOnStuckCleanUp(t *testing.T) {
+	// Keep the suite fast: shrink the per-phase teardown timeout for this test.
+	orig := hostCleanupTimeout
+	hostCleanupTimeout = 100 * time.Millisecond
+	t.Cleanup(func() { hostCleanupTimeout = orig })
+
+	ctx := common.WithLogger(t.Context(), logging.Default())
+	base := t.TempDir()
+	path := filepath.Join(base, "misc", "hostexecutor")
+	require.NoError(t, os.MkdirAll(path, 0o700))
+
+	release := make(chan struct{})
+	t.Cleanup(func() { close(release) }) // unblock the leaked goroutine at test end
+
+	e := &HostEnvironment{
+		Path: path,
+		CleanUp: func() {
+			<-release // simulate a delete syscall stuck indefinitely
+		},
+		StdOut: os.Stdout,
+	}
+
+	done := make(chan error, 1)
+	go func() { done <- e.Remove()(ctx) }()
+
+	select {
+	case err := <-done:
+		require.NoError(t, err)
+	case <-time.After(10 * time.Second):
+		t.Fatal("Remove() hung on a stuck CleanUp callback")
+	}
+}
+
+// TestHostEnvironmentRemoveDoesNotHangOnStuckPathRemoval guards against a
+// stalled os.RemoveAll on the misc/workspace paths (same AV/EDR wedge as
+// #1023) wedging job completion after the CleanUp callback has already timed
+// out or finished.
+func TestHostEnvironmentRemoveDoesNotHangOnStuckPathRemoval(t *testing.T) {
+	origTimeout := hostCleanupTimeout
+	hostCleanupTimeout = 100 * time.Millisecond
+	t.Cleanup(func() { hostCleanupTimeout = origTimeout })
+
+	release := make(chan struct{})
+	stubDone := make(chan struct{})
+
+	origRemoveAll := removeAll
+	removeAll = func(string) error {
+		defer close(stubDone)
+		<-release
+		return nil
+	}
+	// The stuck delete goroutine outlives the timed-out Remove and still reads
+	// removeAll; unblock it and wait before restoring to avoid a restore/read race.
+	t.Cleanup(func() {
+		close(release)
+		<-stubDone
+		removeAll = origRemoveAll
+	})
+
+	ctx := common.WithLogger(t.Context(), logging.Default())
+	base := t.TempDir()
+	path := filepath.Join(base, "misc", "hostexecutor")
+	require.NoError(t, os.MkdirAll(path, 0o700))
+
+	e := &HostEnvironment{
+		Path:   path,
+		StdOut: os.Stdout,
+	}
+
+	done := make(chan error, 1)
+	go func() { done <- e.Remove()(ctx) }()
+
+	select {
+	case err := <-done:
+		require.NoError(t, err)
+	case <-time.After(10 * time.Second):
+		t.Fatal("Remove() hung on a stuck path removal")
+	}
+}
+
+func TestBuildWindowsWorkspaceKillScript(t *testing.T) {
+	t.Run("single dir", func(t *testing.T) {
+		s := buildWindowsWorkspaceKillScript([]string{`C:\workspace\job1`})
+		assert.Contains(t, s, `$paths = @('C:\workspace\job1')`)
+		// Self-PID guard is essential — without it the script could taskkill
+		// the PowerShell process running it.
+		assert.Contains(t, s, "$selfPid = $PID")
+		assert.Contains(t, s, "$_.ProcessId -eq $selfPid")
+		// Must match both ExecutablePath (binaries from the workspace) and
+		// CommandLine (system binaries invoked with workspace paths in args),
+		// both bounded by dir+separator so a name-prefix sibling is spared.
+		assert.Contains(t, s, `$prefix = $p + '\'`)
+		assert.Contains(t, s, "$_.ExecutablePath.StartsWith($prefix")
+		assert.Contains(t, s, "$_.CommandLine.IndexOf($prefix")
+		// Each matched PID must be tree-killed, not just stopped.
+		assert.Contains(t, s, "taskkill.exe /PID $_.ProcessId /T /F")
+	})
+
+	t.Run("multiple dirs comma-separated", func(t *testing.T) {
+		s := buildWindowsWorkspaceKillScript([]string{
+			`C:\work\path`,
+			`C:\work\workdir`,
+			`C:\Users\runner\AppData\Local\Temp\job-42`,
+		})
+		assert.Contains(t, s, `'C:\work\path'`)
+		assert.Contains(t, s, `'C:\work\workdir'`)
+		assert.Contains(t, s, `'C:\Users\runner\AppData\Local\Temp\job-42'`)
+		// Commas between entries — no trailing comma, no leading comma.
+		assert.Contains(t, s, `'C:\work\path','C:\work\workdir',`)
+	})
+
+	t.Run("path with single quote is escaped", func(t *testing.T) {
+		// In PowerShell single-quoted strings the only special char is the
+		// quote itself, escaped by doubling. A workspace path that ever
+		// contained `'` would inject a command into the script otherwise.
+		s := buildWindowsWorkspaceKillScript([]string{`C:\work\it's\path`})
+		assert.Contains(t, s, `'C:\work\it''s\path'`)
+		// And it must NOT appear unescaped — otherwise the quote would
+		// terminate the literal early.
+		assert.NotContains(t, s, `'C:\work\it's\path'`)
+	})
+
+	t.Run("path with wildcard metacharacters is matched literally", func(t *testing.T) {
+		// A path containing [ ] ? * must be embedded verbatim and matched with
+		// ordinal String methods, not -like, otherwise the metacharacters would
+		// be interpreted as wildcards and the leftover process could escape.
+		s := buildWindowsWorkspaceKillScript([]string{`C:\work\[job]?1`})
+		assert.Contains(t, s, `'C:\work\[job]?1'`)
+		assert.NotContains(t, s, "-like")
+		assert.Contains(t, s, "StartsWith")
+		assert.Contains(t, s, "IndexOf")
+	})
+
+	t.Run("empty dir list still produces a valid script", func(t *testing.T) {
+		s := buildWindowsWorkspaceKillScript(nil)
+		// Empty array literal — script runs, matches nothing, is a no-op.
+		assert.Contains(t, s, "$paths = @()")
+		assert.Contains(t, s, "Get-CimInstance Win32_Process")
+	})
+}

act/container/kubernetes.go

@@ -0,0 +1,589 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package container
+
+import (
+	"bufio"
+	"bytes"
+	"cmp"
+	"context"
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"io"
+	"maps"
+	"net/http"
+	"net/url"
+	"os"
+	"path"
+	"regexp"
+	"slices"
+	"strings"
+	"time"
+
+	"gitea.com/gitea/runner/act/common"
+
+	"github.com/kballard/go-shellquote"
+	"github.com/spf13/pflag"
+)
+
+// KubernetesOptions configures the pod a job runs in.
+type KubernetesOptions struct {
+	Kubeconfig   string
+	Namespace    string
+	PodTemplates []map[string]any // merged in order, a later one winning
+	MaxLifetime  time.Duration
+	ForcePull    bool
+	RunnerUUID   string
+}
+
+// KubernetesPod runs a job container and its service containers as one pod.
+type KubernetesPod struct {
+	options          KubernetesOptions
+	client           *kubeClient
+	name, secretName string
+	job              *kubernetesContainer
+	services         []*kubernetesContainer
+	arch, path       string
+}
+
+type kubernetesContainer struct {
+	LinuxContainerEnvironmentExtensions
+	pod   *KubernetesPod
+	id    string // the workflow's service id, name is its DNS label form
+	name  string
+	input *NewContainerInput
+	probe map[string]any
+}
+
+type containerStatus struct {
+	Name  string
+	Ready bool
+	State struct {
+		Waiting    *struct{ Reason, Message string }
+		Running    *struct{}
+		Terminated *struct {
+			ExitCode int
+			Message  string
+		}
+	}
+}
+
+type podStatus struct {
+	Spec   struct{ Containers []struct{} }
+	Status struct {
+		Phase, Reason, Message                   string
+		Conditions                               []struct{ Type, Status, Message string }
+		InitContainerStatuses, ContainerStatuses []containerStatus
+	}
+}
+
+func NewKubernetesPod(options KubernetesOptions) (*KubernetesPod, error) {
+	client, err := newKubeClient(options.Kubeconfig, options.Namespace)
+	if err != nil {
+		return nil, fmt.Errorf("connect to Kubernetes: %w", err)
+	}
+	return &KubernetesPod{options: options, client: client}, nil
+}
+
+// JobContainer returns the container of the pod the job's steps run in.
+func (p *KubernetesPod) JobContainer(input *NewContainerInput) ExecutionsEnvironment {
+	p.job = &kubernetesContainer{pod: p, name: "job", input: input}
+	return p.job
+}
+
+var (
+	invalidLabelChars = regexp.MustCompile(`[^a-z0-9-]+`)
+	dnsSubdomain      = regexp.MustCompile(`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`)
+)
+
+// kubernetesServiceName returns the container name of service id, made a DNS label as it must be.
+func kubernetesServiceName(id string) string {
+	name := strings.Trim(invalidLabelChars.ReplaceAllString(strings.ToLower(id), "-"), "-")
+	return strings.TrimRight(name[:min(63, len(name))], "-")
+}
+
+// KubernetesServiceHostnames returns the hostnames of service id, its container name and, where hostAliases accept it as a DNS subdomain, id lowercased.
+func KubernetesServiceHostnames(id string) []string {
+	name, host := kubernetesServiceName(id), strings.ToLower(id)
+	if host != name && len(host) <= 253 && dnsSubdomain.MatchString(host) { // https://github.com/kubernetes/apimachinery/blob/v0.35.1/pkg/util/validation/validation.go#L198-L207
+		return []string{name, host}
+	}
+	return []string{name}
+}
+
+// ServiceContainer returns a container of the pod the job reaches at KubernetesServiceHostnames(id).
+func (p *KubernetesPod) ServiceContainer(id string, input *NewContainerInput) ExecutionsEnvironment {
+	service := &kubernetesContainer{pod: p, id: id, name: kubernetesServiceName(id), input: input}
+	p.services = append(p.services, service)
+	return service
+}
+
+func (p *KubernetesPod) create(ctx context.Context) error {
+	prefix := strings.Trim(strings.ToLower(p.job.input.Name), "-")
+	prefix = cmp.Or(strings.TrimRight(prefix[:min(40, len(prefix))], "-"), "gitea-runner") + "-"
+	name := prefix + strings.ToLower(rand.Text()[:8]) // chosen here, so cleanup knows it even when a create response is lost
+	labels := map[string]any{"app.kubernetes.io/managed-by": "gitea-runner"}
+	if p.options.RunnerUUID != "" {
+		labels[runnerUUIDLabel] = p.options.RunnerUUID
+	}
+	metadata := map[string]any{"name": name, "labels": labels}
+	if hostname, err := os.Hostname(); p.client.inCluster && err == nil {
+		var runner struct{ Metadata struct{ Name, UID string } }
+		if err := p.client.do(ctx, http.MethodGet, p.client.path("pods/"+hostname), nil, &runner); err == nil {
+			metadata["ownerReferences"] = []any{map[string]any{"apiVersion": "v1", "kind": "Pod", "name": runner.Metadata.Name, "uid": runner.Metadata.UID}}
+		} else {
+			common.Logger(ctx).Debugf("The runner is not pod %s, job pods get no owner: %v", hostname, err)
+		}
+	}
+	secretData := map[string]string{}
+	manifest, err := p.manifest(name, secretData, metadata)
+	if err != nil {
+		return err
+	}
+	for _, service := range p.services {
+		if !slices.ContainsFunc(KubernetesServiceHostnames(service.id), func(hostname string) bool { return strings.EqualFold(hostname, service.id) }) { // glibc and Go match /etc/hosts case-insensitively
+			common.Logger(ctx).Warnf("Service %s is reachable as %s or localhost, as a Kubernetes hostname cannot be %q", service.id, service.name, service.id)
+		}
+	}
+	if len(secretData) > 0 {
+		p.secretName = name // named like the pod, RemoveOrphanKubernetesResources finds it by that
+		if err := p.client.do(ctx, http.MethodPost, p.client.path("secrets"), map[string]any{"metadata": metadata, "stringData": secretData}, nil); err != nil {
+			return fmt.Errorf("create secret: %w", err)
+		}
+	}
+	p.name = name
+	if err := p.client.do(ctx, http.MethodPost, p.client.path("pods"), manifest, nil); err != nil {
+		return fmt.Errorf("create pod: %w", err)
+	}
+	return nil
+}
+
+func (p *KubernetesPod) manifest(secret string, secretData map[string]string, metadata map[string]any) (any, error) {
+	template := map[string]any{"spec": map[string]any{
+		"automountServiceAccountToken":  false,
+		"enableServiceLinks":            false,
+		"terminationGracePeriodSeconds": 0, // the job container's tail ignores SIGTERM
+	}}
+	for _, layer := range p.options.PodTemplates {
+		template, _ = mergeManifest(template, layer, "").(map[string]any)
+	}
+	templateSpec, _ := template["spec"].(map[string]any)
+	templateContainers, _ := templateSpec["containers"].([]any)
+	templateVolumes, _ := templateSpec["volumes"].([]any)
+	var serviceTemplate any
+	if index := slices.IndexFunc(templateContainers, func(container any) bool { return manifestField(container, "name") == "$services" }); index >= 0 {
+		serviceTemplate = templateContainers[index]
+		templateSpec["containers"] = slices.Delete(slices.Clone(templateContainers), index, index+1)
+	}
+	var containers, volumes []any
+	var hostnames []string
+	names := map[string]bool{}
+	for _, container := range templateContainers {
+		names[manifestField(container, "name")] = true
+	}
+	for _, c := range append([]*kubernetesContainer{p.job}, p.services...) {
+		if c != p.job && (c.name == "" || names[c.name]) {
+			return nil, fmt.Errorf("service %s maps to container %q, which is empty or named like another container of the pod", c.id, c.name)
+		}
+		names[c.name] = true
+		spec, err := c.spec(secret, secretData)
+		if err != nil {
+			return nil, err
+		}
+		if c == p.job {
+			containers = append(containers, spec)
+			continue
+		}
+		containers = append(containers, mergeManifest(serviceTemplate, spec, ""))
+		hostnames = append(hostnames, KubernetesServiceHostnames(c.id)...)
+	}
+	for _, name := range []string{"workspace", "act"} {
+		if !slices.ContainsFunc(templateVolumes, func(volume any) bool { return manifestField(volume, "name") == name }) {
+			volumes = append(volumes, map[string]any{"name": name, "emptyDir": map[string]any{}})
+		}
+	}
+	spec := map[string]any{"restartPolicy": "Never", "containers": containers, "volumes": volumes}
+	if len(hostnames) > 0 {
+		spec["hostAliases"] = []any{map[string]any{"ip": "127.0.0.1", "hostnames": hostnames}}
+	}
+	if p.options.MaxLifetime > 0 {
+		spec["activeDeadlineSeconds"] = max(1, int64(p.options.MaxLifetime.Seconds()))
+	}
+	return mergeManifest(template, map[string]any{"apiVersion": "v1", "kind": "Pod", "metadata": metadata, "spec": spec}, ""), nil
+}
+
+// mergeManifest merges over onto base like a strategic merge patch: maps key by key, map list items by name or volumeMounts by mountPath, env entries, volumes and other values replaced.
+func mergeManifest(base, over any, field string) any {
+	switch over := over.(type) {
+	case map[string]any:
+		merged := map[string]any{}
+		if base, ok := base.(map[string]any); ok {
+			maps.Copy(merged, base)
+		}
+		for key, value := range over {
+			merged[key] = mergeManifest(merged[key], value, key)
+		}
+		return merged
+	case []any:
+		key := cmp.Or(map[string]string{"volumeMounts": "mountPath"}[field], "name")
+		baseList, _ := base.([]any)
+		merged := slices.Clone(baseList)
+		for _, item := range over {
+			if _, ok := item.(map[string]any); !ok {
+				return over
+			}
+			name := manifestField(item, key)
+			index := slices.IndexFunc(merged, func(existing any) bool { return name != "" && manifestField(existing, key) == name })
+			switch {
+			case index < 0:
+				merged = append(merged, item)
+			case field == "env" || field == "volumes": // each holds one source, merging two makes a pod the API rejects
+				merged[index] = item
+			default:
+				merged[index] = mergeManifest(merged[index], item, "")
+			}
+		}
+		return merged
+	}
+	return over
+}
+
+func manifestField(item any, key string) string {
+	fields, _ := item.(map[string]any)
+	value, _ := fields[key].(string)
+	return value
+}
+
+func (c *kubernetesContainer) spec(secret string, secretData map[string]string) (map[string]any, error) {
+	env := []any{}
+	for index, entry := range c.input.Env {
+		key, value, _ := strings.Cut(entry, "=")
+		if c == c.pod.job {
+			env = append(env, map[string]any{"name": key, "value": value})
+			continue
+		}
+		secretKey := fmt.Sprintf("%s.%d", c.name, index)
+		secretData[secretKey] = value
+		env = append(env, map[string]any{"name": key, "valueFrom": map[string]any{"secretKeyRef": map[string]any{"name": secret, "key": secretKey}}})
+	}
+	spec := map[string]any{
+		"name": c.name, "image": c.input.Image, "command": escapeExpansion(c.input.Entrypoint), "args": escapeExpansion(c.input.Cmd),
+		"workingDir": c.input.WorkingDir, "env": env,
+	}
+	if c.pod.options.ForcePull {
+		spec["imagePullPolicy"] = "Always"
+	}
+	if c == c.pod.job {
+		spec["volumeMounts"] = []any{
+			map[string]any{"name": "workspace", "mountPath": c.input.WorkingDir},
+			map[string]any{"name": "act", "mountPath": c.GetActPath()},
+		}
+	}
+	if err := c.parseOptions(); err != nil {
+		return nil, fmt.Errorf("service %s: %w", c.name, err)
+	}
+	if c.probe != nil {
+		spec["startupProbe"] = c.probe
+	}
+	return spec, nil
+}
+
+// escapeExpansion keeps kubelet from expanding $(VAR) and $$ in command and args, which docker passes as is.
+func escapeExpansion(args []string) []string {
+	args = slices.Clone(args)
+	for index := range args {
+		args[index] = strings.ReplaceAll(args[index], "$", "$$")
+	}
+	return args
+}
+
+// parseOptions turns docker health options, the only ones a pod supports, into a startup probe, which like docker gives up after the retries.
+func (c *kubernetesContainer) parseOptions() error {
+	args, err := shellquote.Split(c.input.WorkflowOptions)
+	if err != nil {
+		return err
+	}
+	flags := pflag.NewFlagSet("options", pflag.ContinueOnError)
+	flags.SetOutput(io.Discard)
+	command := flags.String("health-cmd", "", "")
+	interval := flags.Duration("health-interval", 0, "")
+	timeout := flags.Duration("health-timeout", 0, "")
+	retries := flags.Int("health-retries", 0, "")
+	startPeriod := flags.Duration("health-start-period", 0, "")
+	if err := flags.Parse(args); err != nil {
+		return fmt.Errorf("options %q: %w, only --health-* options are supported on Kubernetes", c.input.WorkflowOptions, err)
+	}
+	if *command == "" {
+		return nil
+	}
+	period := max(1, int(cmp.Or(*interval, 30*time.Second).Seconds()))
+	c.probe = map[string]any{
+		"exec":             map[string]any{"command": []string{"/bin/sh", "-c", *command}},
+		"periodSeconds":    period,
+		"timeoutSeconds":   max(1, int(cmp.Or(*timeout, 30*time.Second).Seconds())),
+		"failureThreshold": max(1, cmp.Or(*retries, 3)) + int(startPeriod.Seconds())/period, // docker does not count failures in the start period
+	}
+	return nil
+}
+
+func (p *KubernetesPod) get(ctx context.Context) (*podStatus, error) {
+	var pod podStatus
+	return &pod, p.client.do(ctx, http.MethodGet, p.client.path("pods/"+p.name), nil, &pod)
+}
+
+func (p *KubernetesPod) waitStarted(ctx context.Context) error {
+	var unscheduled string
+	for delay := 100 * time.Millisecond; ; delay = min(2*delay, time.Second) {
+		pod, err := p.get(ctx)
+		if err != nil {
+			return err
+		}
+		if pod.Status.Phase == "Failed" {
+			return fmt.Errorf("pod %s failed: %s", p.name, cmp.Or(pod.Status.Message, pod.Status.Reason))
+		}
+		started := len(pod.Status.ContainerStatuses) == len(pod.Spec.Containers)
+		for _, status := range append(pod.Status.InitContainerStatuses, pod.Status.ContainerStatuses...) {
+			if waiting := status.State.Waiting; waiting != nil {
+				switch waiting.Reason {
+				case "ErrImagePull", "ImagePullBackOff", "InvalidImageName", "ErrImageNeverPull", "CreateContainerConfigError", "CreateContainerError", "RunContainerError":
+					return fmt.Errorf("container %s of pod %s: %s: %s", status.Name, p.name, waiting.Reason, waiting.Message)
+				}
+				started = false
+			}
+		}
+		if started {
+			return nil
+		}
+		for _, condition := range pod.Status.Conditions {
+			if condition.Type == "PodScheduled" && condition.Status == "False" && condition.Message != unscheduled {
+				unscheduled = condition.Message
+				common.Logger(ctx).Infof("Waiting for pod %s to be scheduled: %s", p.name, unscheduled)
+			}
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(delay):
+		}
+	}
+}
+
+func (c *kubernetesContainer) Create(_, _ []string) common.Executor {
+	return func(ctx context.Context) error {
+		if c != c.pod.job {
+			return nil
+		}
+		return c.pod.create(ctx)
+	}
+}
+
+func (c *kubernetesContainer) Start(_ bool) common.Executor {
+	return func(ctx context.Context) error {
+		if c != c.pod.job {
+			return nil
+		}
+		if err := c.pod.waitStarted(ctx); err != nil {
+			return err
+		}
+		var stdout bytes.Buffer
+		if err := c.pod.client.exec(ctx, c.pod.name, c.name, []string{"sh", "-c", `printf '%s\n%s' "$(uname -m)" "$PATH"`}, nil, &stdout, io.Discard); err != nil {
+			return err
+		}
+		machine, path, _ := strings.Cut(stdout.String(), "\n")
+		c.pod.arch, c.pod.path = goArchToActionArch(machine), path
+		return nil
+	}
+}
+
+func (*kubernetesContainer) Pull(bool) common.Executor {
+	return func(context.Context) error { return nil }
+}
+
+var (
+	shellName    = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+	bashReadonly = []string{"BASHOPTS", "BASH_VERSINFO", "EUID", "PPID", "SHELLOPTS", "UID"} // bash as sh cannot export these
+)
+
+// Exec feeds the command to sh on stdin, which exports the env so it stays out of the request URL and, where sh can export a name, out of process arguments.
+func (c *kubernetesContainer) Exec(command []string, env map[string]string, _, workdir string) common.Executor {
+	return func(ctx context.Context) error {
+		script, args := "", []string{"env", "--"}
+		for name, value := range env {
+			if shellName.MatchString(name) && !slices.Contains(bashReadonly, name) {
+				script += "command export " + shellquote.Join(name+"="+value) + "\n"
+			} else {
+				args = append(args, name+"="+value)
+			}
+		}
+		script += "exec " + shellquote.Join(append(args, command...)...)
+		if workdir != "" {
+			script = "cd " + shellquote.Join(workdir) + " || exit\n" + script
+		}
+		defer common.FlushWriter(c.input.Stdout)
+		defer common.FlushWriter(c.input.Stderr)
+		return c.pod.client.exec(ctx, c.pod.name, c.name, []string{"sh"}, strings.NewReader(script), c.input.Stdout, c.input.Stderr)
+	}
+}
+
+func (c *kubernetesContainer) extract(ctx context.Context, destPath string, write func(io.Writer) error) error {
+	reader, writer := io.Pipe()
+	defer reader.Close()
+	go func() { writer.CloseWithError(write(writer)) }()
+	var stderr bytes.Buffer
+	if err := c.pod.client.exec(ctx, c.pod.name, c.name, []string{"sh", "-c", `mkdir -p "$1" && tar -xf - -C "$1"`, "sh", destPath}, reader, io.Discard, &stderr); err != nil {
+		return fmt.Errorf("extract to %s: %w: %s", destPath, err, strings.TrimSpace(stderr.String()))
+	}
+	return nil
+}
+
+func (c *kubernetesContainer) Copy(destPath string, files ...*FileEntry) common.Executor {
+	return func(ctx context.Context) error {
+		return c.extract(ctx, destPath, func(writer io.Writer) error { return writeFilesTar(ctx, writer, 0, 0, files...) })
+	}
+}
+
+func (c *kubernetesContainer) CopyDir(destPath, srcPath string, useGitIgnore, skipGitDir bool) common.Executor {
+	return func(ctx context.Context) error {
+		return c.extract(ctx, destPath, func(writer io.Writer) error {
+			return writeDirTar(ctx, writer, "/", srcPath, useGitIgnore, skipGitDir, 0, 0)
+		})
+	}
+}
+
+// GetContainerArchive streams the archive, checking the path first as tar writes an empty archive for a missing one.
+func (c *kubernetesContainer) GetContainerArchive(ctx context.Context, srcPath string) (io.ReadCloser, error) {
+	reader, writer := io.Pipe()
+	go func() {
+		var stderr bytes.Buffer
+		err := c.pod.client.exec(ctx, c.pod.name, c.name, []string{"sh", "-c", `test -e "$1" -o -L "$1" && exec tar -cf - -C "$2" "$3"`, "sh", srcPath, path.Dir(srcPath), path.Base(srcPath)}, nil, writer, &stderr)
+		if err != nil {
+			err = fmt.Errorf("archive %s: %w: %s", srcPath, err, strings.TrimSpace(stderr.String()))
+		}
+		writer.CloseWithError(err)
+	}()
+	buffered := bufio.NewReader(reader)
+	if _, err := buffered.Peek(1); err != nil {
+		reader.Close()
+		return nil, err
+	}
+	return struct {
+		io.Reader
+		io.Closer
+	}{buffered, reader}, nil
+}
+
+func (c *kubernetesContainer) UpdateFromEnv(srcPath string, env *map[string]string) common.Executor {
+	return parseEnvFile(c, srcPath, env)
+}
+
+func (c *kubernetesContainer) UpdateFromImageEnv(env *map[string]string) common.Executor {
+	return func(context.Context) error {
+		(*env)["PATH"] = cmp.Or((*env)["PATH"], c.pod.path)
+		return nil
+	}
+}
+
+func (c *kubernetesContainer) Inspect(ctx context.Context) (*Info, error) {
+	if c.pod.name == "" {
+		return nil, fmt.Errorf("container %s %w", c.name, ErrContainerNotFound)
+	}
+	pod, err := c.pod.get(ctx)
+	if isNotFound(err) {
+		return nil, fmt.Errorf("pod %s %w", c.pod.name, ErrContainerNotFound)
+	} else if err != nil {
+		return nil, err
+	}
+	info := &Info{ID: c.pod.name + "/" + c.name, State: "created", Health: HealthNone, Ports: map[string]string{}}
+	for port := range c.input.ExposedPorts {
+		info.Ports[port.Port()] = port.Port() // services share the pod's network
+	}
+	for _, status := range pod.Status.ContainerStatuses {
+		if status.Name != c.name {
+			continue
+		}
+		if status.State.Running != nil {
+			info.State = StateRunning
+		} else if terminated := status.State.Terminated; terminated != nil {
+			info.State, info.ExitCode, info.HealthOutput = "exited", terminated.ExitCode, terminated.Message
+		}
+		if c.probe != nil {
+			switch {
+			case status.Ready:
+				info.Health = HealthHealthy
+			case info.State == "exited":
+				info.Health = HealthUnhealthy
+			default:
+				info.Health = HealthStarting
+			}
+		}
+	}
+	return info, nil
+}
+
+func (c *kubernetesContainer) DumpLogs(ctx context.Context) error {
+	if c.pod.name == "" {
+		return fmt.Errorf("container %s %w", c.name, ErrContainerNotFound)
+	}
+	defer common.FlushWriter(c.input.Stdout)
+	return c.pod.client.do(ctx, http.MethodGet, c.pod.client.path("pods/"+c.pod.name+"/log?container="+c.name), nil, c.input.Stdout)
+}
+
+func (c *kubernetesContainer) Remove() common.Executor {
+	return func(ctx context.Context) error {
+		if c != c.pod.job {
+			return nil
+		}
+		return errors.Join(c.pod.client.delete(ctx, "pods", c.pod.name), c.pod.client.delete(ctx, "secrets", c.pod.secretName))
+	}
+}
+
+// RemoveOrphanKubernetesResources removes this runner's job pods created before createdBefore and the Secrets named like them, as listing Secrets would reveal all of the namespace's.
+func RemoveOrphanKubernetesResources(ctx context.Context, options KubernetesOptions, createdBefore time.Time) error {
+	client, err := newKubeClient(options.Kubeconfig, options.Namespace)
+	if err != nil {
+		return fmt.Errorf("connect to Kubernetes: %w", err)
+	}
+	defer client.http.CloseIdleConnections()
+	var pods struct {
+		Items []struct {
+			Metadata struct {
+				Name              string
+				CreationTimestamp time.Time
+			}
+		}
+	}
+	if err := client.do(ctx, http.MethodGet, client.path("pods?labelSelector="+url.QueryEscape(runnerUUIDLabel+"="+options.RunnerUUID)), nil, &pods); err != nil {
+		return fmt.Errorf("list pods: %w", err)
+	}
+	var errs []error
+	for _, item := range pods.Items {
+		if !item.Metadata.CreationTimestamp.Before(createdBefore) {
+			continue
+		}
+		if err := client.delete(ctx, "secrets", item.Metadata.Name); err != nil {
+			errs = append(errs, err) // leave the pod for the next cleanup, it is the only way back to its Secret
+			continue
+		}
+		errs = append(errs, client.delete(ctx, "pods", item.Metadata.Name))
+	}
+	return errors.Join(errs...)
+}
+
+func (c *kubernetesContainer) Close() common.Executor {
+	return func(context.Context) error {
+		c.pod.client.http.CloseIdleConnections()
+		return nil
+	}
+}
+
+func (c *kubernetesContainer) ReplaceLogWriter(stdout, stderr io.Writer) (io.Writer, io.Writer) {
+	oldStdout, oldStderr := c.input.Stdout, c.input.Stderr
+	c.input.Stdout, c.input.Stderr = stdout, stderr
+	return oldStdout, oldStderr
+}
+
+func (c *kubernetesContainer) GetRunnerContext(_ context.Context) map[string]any {
+	return map[string]any{"os": "Linux", "arch": c.pod.arch, "temp": "/tmp", "tool_cache": DefaultToolCache}
+}

act/container/kubernetes_client.go

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

act/container/kubernetes_test.go

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

act/container/linux_container_environment_extensions.go

@@ -11,7 +11,7 @@ import (
 	"runtime"
 	"strings"
 
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
 )
 
 type LinuxContainerEnvironmentExtensions struct{}
@@ -21,13 +21,13 @@ type LinuxContainerEnvironmentExtensions struct{}
 // For use in docker volumes and binds
 func (*LinuxContainerEnvironmentExtensions) ToContainerPath(path string) string {
 	if runtime.GOOS == "windows" && strings.Contains(path, "/") {
-		log.Error("You cannot specify linux style local paths (/mnt/etc) on Windows as it does not understand them.")
+		logging.Error("You cannot specify linux style local paths (/mnt/etc) on Windows as it does not understand them.")
 		return ""
 	}
 
 	abspath, err := filepath.Abs(path)
 	if err != nil {
-		log.Error(err)
+		logging.Error(err)
 		return ""
 	}
 
@@ -66,12 +66,15 @@ func (*LinuxContainerEnvironmentExtensions) JoinPathVariable(paths ...string) st
 	return strings.Join(paths, ":")
 }
 
+// DefaultToolCache is where the runner mounts the tool cache inside job containers.
+const DefaultToolCache = "/opt/hostedtoolcache"
+
 func (*LinuxContainerEnvironmentExtensions) GetRunnerContext(ctx context.Context) map[string]any {
 	return map[string]any{
 		"os":         "Linux",
 		"arch":       RunnerArch(ctx),
 		"temp":       "/tmp",
-		"tool_cache": "/opt/hostedtoolcache",
+		"tool_cache": DefaultToolCache,
 	}
 }
 

act/container/linux_container_environment_extensions_test.go

@@ -11,7 +11,8 @@ import (
 	"strings"
 	"testing"
 
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common/logging"
+
 	"github.com/stretchr/testify/assert"
 )
 
@@ -27,7 +28,7 @@ func TestContainerPath(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		cwd, err := os.Getwd()
 		if err != nil {
-			log.Error(err)
+			logging.Error(err)
 		}
 
 		rootDrive := os.Getenv("SystemDrive")
@@ -49,7 +50,7 @@ func TestContainerPath(t *testing.T) {
 	} else {
 		cwd, err := os.Getwd()
 		if err != nil {
-			log.Error(err)
+			logging.Error(err)
 		}
 		for _, v := range []containerPathJob{
 			{"/home/act/go/src/github.com/nektos/act", "/home/act/go/src/github.com/nektos/act", ""},

act/container/parse_env_file.go

@@ -13,6 +13,9 @@ import (
 	"strings"
 
 	"gitea.com/gitea/runner/act/common"
+
+	"golang.org/x/text/encoding/unicode"
+	"golang.org/x/text/transform"
 )
 
 func parseEnvFile(e Container, srcPath string, env *map[string]string) common.Executor {
@@ -28,17 +31,26 @@ func parseEnvFile(e Container, srcPath string, env *map[string]string) common.Ex
 		if err != nil && err != io.EOF {
 			return err
 		}
-		s := bufio.NewScanner(reader)
+		// Decode by BOM: Windows PowerShell 5.1 redirection writes UTF-16, and some
+		// tools emit a UTF-8 BOM. Without a BOM the file is read as UTF-8, as before.
+		decoded := transform.NewReader(reader, unicode.BOMOverride(unicode.UTF8.NewDecoder()))
+
+		s := bufio.NewScanner(decoded)
 		// Default 64 KiB max token size is too small for realistic env-file lines; allow up to 16 MiB.
 		s.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
 		for s.Scan() {
 			line := s.Text()
+			// GitHub's runner ignores blank lines
+			if strings.TrimSpace(line) == "" {
+				continue
+			}
 			singleLineEnv := strings.Index(line, "=")
 			multiLineEnv := strings.Index(line, "<<")
-			if singleLineEnv != -1 && (multiLineEnv == -1 || singleLineEnv < multiLineEnv) {
+			switch {
+			case singleLineEnv != -1 && (multiLineEnv == -1 || singleLineEnv < multiLineEnv):
 				localEnv[line[:singleLineEnv]] = line[singleLineEnv+1:]
-			} else if multiLineEnv != -1 {
-				multiLineEnvContent := ""
+			case multiLineEnv != -1:
+				var multiLineEnvContent []string
 				multiLineEnvDelimiter := line[multiLineEnv+2:]
 				delimiterFound := false
 				for s.Scan() {
@@ -47,10 +59,7 @@ func parseEnvFile(e Container, srcPath string, env *map[string]string) common.Ex
 						delimiterFound = true
 						break
 					}
-					if multiLineEnvContent != "" {
-						multiLineEnvContent += "\n"
-					}
-					multiLineEnvContent += content
+					multiLineEnvContent = append(multiLineEnvContent, content)
 				}
 				if err := s.Err(); err != nil {
 					return fmt.Errorf("reading env file: %w", err)
@@ -58,8 +67,8 @@ func parseEnvFile(e Container, srcPath string, env *map[string]string) common.Ex
 				if !delimiterFound {
 					return fmt.Errorf("invalid format delimiter '%v' not found before end of file", multiLineEnvDelimiter)
 				}
-				localEnv[line[:multiLineEnv]] = multiLineEnvContent
-			} else {
+				localEnv[line[:multiLineEnv]] = strings.Join(multiLineEnvContent, "\n")
+			default:
 				return fmt.Errorf("invalid format '%v', expected a line with '=' or '<<'", line)
 			}
 		}

act/container/parse_env_file_test.go

@@ -5,7 +5,6 @@ package container
 
 import (
 	"bufio"
-	"context"
 	"os"
 	"path/filepath"
 	"strings"
@@ -13,6 +12,8 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"golang.org/x/text/encoding"
+	"golang.org/x/text/encoding/unicode"
 )
 
 func newTestHostEnv(t *testing.T) (*HostEnvironment, string) {
@@ -26,7 +27,7 @@ func TestParseEnvFileSingleLine(t *testing.T) {
 	require.NoError(t, os.WriteFile(envPath, []byte("FOO=bar\nBAZ=qux\n"), 0o600))
 
 	env := map[string]string{}
-	require.NoError(t, parseEnvFile(e, envPath, &env)(context.Background()))
+	require.NoError(t, parseEnvFile(e, envPath, &env)(t.Context()))
 	assert.Equal(t, "bar", env["FOO"])
 	assert.Equal(t, "qux", env["BAZ"])
 }
@@ -37,7 +38,7 @@ func TestParseEnvFileMultiLine(t *testing.T) {
 	require.NoError(t, os.WriteFile(envPath, []byte(content), 0o600))
 
 	env := map[string]string{}
-	require.NoError(t, parseEnvFile(e, envPath, &env)(context.Background()))
+	require.NoError(t, parseEnvFile(e, envPath, &env)(t.Context()))
 	assert.Equal(t, "line1\nline2", env["FOO"])
 }
 
@@ -48,7 +49,7 @@ func TestParseEnvFileLargeValueWithinLimit(t *testing.T) {
 	require.NoError(t, os.WriteFile(envPath, []byte(content), 0o600))
 
 	env := map[string]string{}
-	require.NoError(t, parseEnvFile(e, envPath, &env)(context.Background()))
+	require.NoError(t, parseEnvFile(e, envPath, &env)(t.Context()))
 	assert.Equal(t, big, env["FOO"])
 }
 
@@ -59,17 +60,79 @@ func TestParseEnvFileLineExceedsBufferReportsScannerError(t *testing.T) {
 	require.NoError(t, os.WriteFile(envPath, []byte(content), 0o600))
 
 	env := map[string]string{}
-	err := parseEnvFile(e, envPath, &env)(context.Background())
+	err := parseEnvFile(e, envPath, &env)(t.Context())
 	require.ErrorIs(t, err, bufio.ErrTooLong)
 	assert.Contains(t, err.Error(), "reading env file")
 }
 
+// Regression test: a blank line used to fail the job at "Complete Job", after
+// every step had already been recorded as successful.
+func TestParseEnvFileBlankLines(t *testing.T) {
+	e, envPath := newTestHostEnv(t)
+	require.NoError(t, os.WriteFile(envPath, []byte("\nFOO=bar\n\n   \nBAZ=qux\n\n"), 0o600))
+
+	env := map[string]string{}
+	require.NoError(t, parseEnvFile(e, envPath, &env)(t.Context()))
+	assert.Equal(t, "bar", env["FOO"])
+	assert.Equal(t, "qux", env["BAZ"])
+}
+
+// blank lines inside a heredoc value are content, not separators
+func TestParseEnvFileMultiLineKeepsBlankLines(t *testing.T) {
+	e, envPath := newTestHostEnv(t)
+	require.NoError(t, os.WriteFile(envPath, []byte("FOO<<EOF\nline1\n\nline2\nEOF\n"), 0o600))
+
+	env := map[string]string{}
+	require.NoError(t, parseEnvFile(e, envPath, &env)(t.Context()))
+	assert.Equal(t, "line1\n\nline2", env["FOO"])
+
+	require.NoError(t, os.WriteFile(envPath, []byte("FOO<<EOF\n\nline2\nEOF\n"), 0o600))
+	env = map[string]string{}
+	require.NoError(t, parseEnvFile(e, envPath, &env)(t.Context()))
+	assert.Equal(t, "\nline2", env["FOO"])
+}
+
+func TestParseEnvFileUTF8BOM(t *testing.T) {
+	e, envPath := newTestHostEnv(t)
+	content := append([]byte{0xEF, 0xBB, 0xBF}, []byte("FOO=bar\n")...)
+	require.NoError(t, os.WriteFile(envPath, content, 0o600))
+
+	env := map[string]string{}
+	require.NoError(t, parseEnvFile(e, envPath, &env)(t.Context()))
+	assert.Equal(t, "bar", env["FOO"])
+}
+
+// Windows host mode: PowerShell 5.1 redirection writes UTF-16, which used to be
+// unrecognisable as KEY=VALUE, so the writes were silently ignored.
+func TestParseEnvFileUTF16(t *testing.T) {
+	tests := []struct {
+		name    string
+		encoder *encoding.Encoder
+	}{
+		{"little endian", unicode.UTF16(unicode.LittleEndian, unicode.UseBOM).NewEncoder()},
+		{"big endian", unicode.UTF16(unicode.BigEndian, unicode.UseBOM).NewEncoder()},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e, envPath := newTestHostEnv(t)
+			content, err := tt.encoder.Bytes([]byte("FOO=bar\r\nMULTI<<EOF\r\nline1\r\nEOF\r\n"))
+			require.NoError(t, err)
+			require.NoError(t, os.WriteFile(envPath, content, 0o600))
+
+			env := map[string]string{}
+			require.NoError(t, parseEnvFile(e, envPath, &env)(t.Context()))
+			assert.Equal(t, "bar", env["FOO"])
+			assert.Equal(t, "line1", env["MULTI"])
+		})
+	}
+}
+
 func TestParseEnvFileMissingDelimiter(t *testing.T) {
 	e, envPath := newTestHostEnv(t)
 	require.NoError(t, os.WriteFile(envPath, []byte("FOO<<EOF\nline1\nline2\n"), 0o600))
 
 	env := map[string]string{}
-	err := parseEnvFile(e, envPath, &env)(context.Background())
+	err := parseEnvFile(e, envPath, &env)(t.Context())
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "delimiter")
 }