ci: run the Windows tests on a runner with KVM (#1369)

Run the Windows tests on `ubuntu-latest-kvm` as a PR job, with the installed Windows cached, minutes instead of ~1h40m. Aligned with https://gitea.com/gitea/gitea-mcp/pulls/321 and https://gitea.com/gitea/cli/pulls/79.

Co-authored-by: silverwind <me@silverwind.io>
Reviewed-on: https://gitea.com/gitea/runner/pulls/1369
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
Co-authored-by: Zettat123 <zettat123@gmail.com>

.dockerignore

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

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

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

.gitea/workflows/cache-seeder.yml

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

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

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

.gitea/workflows/release-nightly.yml

@@ -11,7 +11,6 @@ on:
 
 env:
   DOCKER_ORG: gitea
-  DOCKER_LATEST: nightly
 
 jobs:
   goreleaser:
@@ -20,11 +19,10 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
-      # Custom publishers (the R2 mirror below) run as the very last
+      # Custom publishers (the R2 upload below) run as the very last
       # step of goreleaser's publish pipeline, after the Gitea release
-      # has already been created and every artifact already uploaded
-      # to S3. Fail here instead, before anything is built or
-      # published, if the R2 secrets are missing.
+      # has already been created. Fail here instead, before anything
+      # is built or published, if the R2 secrets are missing.
       - name: check R2 configuration
         run: sh scripts/upload-r2.sh --check-config
         env:
@@ -35,18 +33,14 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: "go.mod"
+          check-latest: true
       - name: goreleaser
-        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
+        uses: goreleaser/goreleaser-action@a4f02ab5355a589de60d917a659ce617ed19b3de # v7
         with:
           distribution: goreleaser-pro
           args: release --nightly
         env:
           GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}
-          AWS_REGION: ${{ secrets.AWS_REGION }}
-          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          S3_REGION: ${{ secrets.AWS_REGION }}
-          S3_BUCKET: ${{ secrets.AWS_BUCKET }}
           R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
           R2_BUCKET: ${{ secrets.R2_BUCKET }}
           R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
@@ -79,13 +73,13 @@ jobs:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to DockerHub
-        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
@@ -99,7 +93,7 @@ jobs:
           echo REPO_VERSION=$(git describe --tags --always | sed 's/-/+/' | sed 's/^v//') >> $GITHUB_OUTPUT
 
       - name: Build and push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: ./Dockerfile

.gitea/workflows/release-tag.yml

@@ -12,11 +12,10 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0 # all history for all branches and tags
-      # Custom publishers (the R2 mirror below) run as the very last
+      # Custom publishers (the R2 upload below) run as the very last
       # step of goreleaser's publish pipeline, after the Gitea release
-      # has already been created and every artifact already uploaded
-      # to S3. Fail here instead, before anything is built or
-      # published, if the R2 secrets are missing.
+      # has already been created. Fail here instead, before anything
+      # is built or published, if the R2 secrets are missing.
       - name: check R2 configuration
         run: sh scripts/upload-r2.sh --check-config
         env:
@@ -27,6 +26,7 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version-file: "go.mod"
+          check-latest: true
       - name: Import GPG key
         id: import_gpg
         uses: crazy-max/ghaction-import-gpg@2dc316deee8e90f13e1a351ab510b4d5bc0c82cd # v7
@@ -35,17 +35,12 @@ jobs:
           passphrase: ${{ secrets.PASSPHRASE }}
           fingerprint: CC64B1DB67ABBEECAB24B6455FC346329753F4B0
       - name: goreleaser
-        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
+        uses: goreleaser/goreleaser-action@a4f02ab5355a589de60d917a659ce617ed19b3de # v7
         with:
           distribution: goreleaser-pro
           args: release
         env:
           GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}
-          AWS_REGION: ${{ secrets.AWS_REGION }}
-          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          S3_REGION: ${{ secrets.AWS_REGION }}
-          S3_BUCKET: ${{ secrets.AWS_BUCKET }}
           R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
           R2_BUCKET: ${{ secrets.R2_BUCKET }}
           R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
@@ -74,7 +69,6 @@ jobs:
       image: catthehacker/ubuntu:act-latest
     env:
       DOCKER_ORG: gitea
-      DOCKER_LATEST: latest
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -82,13 +76,13 @@ jobs:
           fetch-depth: 0 # all history for all branches and tags
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Login to DockerHub
-        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
@@ -108,7 +102,7 @@ jobs:
             suffix=${{ matrix.variant.tag_suffix }},onlatest=true
 
       - name: Build and push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           file: ./Dockerfile

.gitea/workflows/test.yml

@@ -1,38 +1,46 @@
 name: checks
 on:
-  push:
-    branches:
-      - main
   pull_request:
+  workflow_dispatch:
+
+env:
+  # The runner image ships a stale docker.io login; point docker at an empty config so
+  # image pulls go straight to anonymous instead of attempting (and failing) that auth
+  # first. The path must be a literal: the `runner` context is unavailable in workflow-level
+  # env, so `${{ runner.temp }}` would resolve to empty and config.Dir() would fall back
+  # to ~/.docker with the stale credentials.
+  DOCKER_CONFIG: /tmp/docker-noauth
 
 jobs:
   lint:
     name: check and test
     runs-on: ubuntu-latest
-    env:
-      # The runner image ships a stale docker.io login; point docker at an empty config so
-      # image pulls go straight to anonymous instead of attempting (and failing) that auth
-      # first. The path must be a literal: the `runner` context is unavailable in job-level
-      # env, so `${{ runner.temp }}` would resolve to empty and config.Dir() would fall back
-      # to ~/.docker with the stale credentials.
-      DOCKER_CONFIG: /tmp/docker-noauth
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
-        with:
-          go-version-file: 'go.mod'
+      - uses: ./.gitea/actions/go-setup
       - name: prepare anonymous docker config
         run: mkdir -p "$DOCKER_CONFIG" && echo '{}' > "$DOCKER_CONFIG/config.json"
       # Pre-pull act/runner's two largest base images so a slow pull can't dominate `make test`;
       # the rest (alpine/ubuntu) pull on demand, absorbed by the make-test -timeout. The host
-      # daemon retains them between runs, so this is usually a fast manifest re-check.
+      # daemon retains them between runs, and their digest pins skip the registry when it has them.
       - name: pre-pull test images
+        env:
+          TEST_JOB_IMAGE: node:26-bookworm-slim@sha256:bc0a2afd3b74ce12222fc8bab99271e66257f021078f5f4a5d687a77d280c1d9 # renovate: datasource=docker
+          TEST_SERVICE_IMAGE: nginx:alpine@sha256:a3554c0d0b48177b1413c26e01f695334428020d9df01243fbae3e11cfd17417 # renovate: datasource=docker
         run: |
-          for img in node:24-bookworm-slim nginx:alpine; do
-            for try in 1 2 3; do docker pull "$img" && break || sleep 5; done
+          for image in "$TEST_JOB_IMAGE" "$TEST_SERVICE_IMAGE"; do
+            if [ "$(docker image inspect --format '{{.Os}}/{{.Architecture}}' "$image" 2>/dev/null)" != linux/amd64 ]; then
+              for attempt in 1 2 3; do
+                docker pull "$image" && break
+                [ "$attempt" = 3 ] || sleep 5
+              done
+            fi
+            docker tag "$image" "${image%@*}"
           done
       - name: lint
         run: make lint
+      - name: checks
+        run: make checks
       - name: build
         run: make build
       - name: test
@@ -42,7 +50,48 @@ jobs:
       # after `make test` so the images it needs are already present on the host daemon.
       - name: test against dind image
         run: make test-dind
+      - name: test against podman
+        run: make test-dind TARGET=podman
       - name: coverage report
         run: |
           make coverage-report
-          cat .tmp/coverage.md >> "$GITHUB_STEP_SUMMARY"
+          cat .tmp/coverage.md >> "$GITHUB_STEP_SUMMARY"
+
+  windows:
+    name: test on windows
+    runs-on: ubuntu-latest-kvm
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: ./.gitea/actions/go-setup
+      - name: prepare anonymous docker config
+        run: mkdir -p "$DOCKER_CONFIG" && echo '{}' > "$DOCKER_CONFIG/config.json"
+      - uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/windows-vm
+          key: windows-vm
+      - name: test on windows
+        id: test-windows
+        run: WINDOWS_TEST_CACHE="$HOME/.cache/windows-vm" make test-windows
+        env:
+          WINDOWS_TEST_TIMEOUT: 45
+      - if: always() && steps.test-windows.outputs.save-cache == 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/windows-vm
+          key: windows-vm
+
+  e2e:
+    name: gitea compatibility (${{ matrix.gitea_image }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        gitea_image:
+          - gitea/gitea:latest
+          - gitea/gitea:main-nightly
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: ./.gitea/actions/go-setup
+      - name: prepare anonymous docker config
+        run: mkdir -p "$DOCKER_CONFIG" && echo '{}' > "$DOCKER_CONFIG/config.json"
+      - name: e2e compatibility
+        run: make test-e2e E2E_GITEA_IMAGE=${{ matrix.gitea_image }}

.gitignore

@@ -1,7 +1,9 @@
 /gitea-runner
+/gitea-runner.exe
 .env
 !/act/runner/testdata/secrets/.env
 .runner
+.runner.lock
 coverage.txt
 .tmp/
 /config.yaml

.golangci.yml

@@ -11,6 +11,7 @@ linters:
     - dupl
     - errcheck
     - forbidigo
+    - forcetypeassert
     - gocheckcompilerdirectives
     - gocritic
     - goheader
@@ -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

@@ -28,38 +28,16 @@ builds:
   ignore:
     - goos: darwin
       goarch: arm
-    - goos: darwin
-      goarch: ppc64le
     - goos: darwin
       goarch: s390x
-    - goos: windows
-      goarch: ppc64le
     - goos: windows
       goarch: s390x
     - goos: windows
       goarch: arm
-      goarm: "5"
-    - goos: windows
-      goarch: arm
-      goarm: "6"
-    - goos: windows
-      goarch: arm
-      goarm: "7"
-    - goos: windows
-      goarch: arm64
-    - goos: freebsd
-      goarch: ppc64le
     - goos: freebsd
       goarch: s390x
     - goos: freebsd
       goarch: arm
-      goarm: "5"
-    - goos: freebsd
-      goarch: arm
-      goarm: "6"
-    - goos: freebsd
-      goarch: arm
-      goarm: "7"
     - goos: freebsd
       goarch: arm64
   flags:
@@ -83,24 +61,12 @@ builds:
       - cmd: sh .goreleaser.checksum.sh {{ .Path }}
       - cmd: sh .goreleaser.checksum.sh {{ .Path }}.xz
 
-blobs:
-  -
-    provider: s3
-    bucket: "{{ .Env.S3_BUCKET }}"
-    region: "{{ .Env.S3_REGION }}"
-    directory: "gitea-runner/{{.Version}}"
-    extra_files:
-      - glob: ./**.xz
-      - glob: ./**.sha256
-
-# Mirrors the S3 `blobs:` upload above into Cloudflare R2 during the
-# parallel S3+R2 period (S3 will be removed once migration completes).
-# A second `blobs:` entry is impossible here since the blob pipe
-# authenticates from the global AWS_* env with no per-entry
-# credentials; `publishers:` supports per-entry `env:` instead, so
-# it's used to invoke scripts/upload-r2.sh once per artifact. Custom
-# publishers inherit almost nothing from the environment, hence the
-# explicit R2_* forwarding below.
+# Uploads every release artifact to Cloudflare R2. The `blobs:` pipe
+# isn't usable here since it authenticates from the global AWS_* env
+# with no per-entry credentials; `publishers:` supports per-entry
+# `env:` instead, so it's used to invoke scripts/upload-r2.sh once per
+# artifact. Custom publishers inherit almost nothing from the
+# environment, hence the explicit R2_* forwarding below.
 #
 # This publisher fires 109 times for 73 distinct keys because
 # goreleaser's release pipe already registers `release.extra_files`
@@ -125,7 +91,7 @@ publishers:
       - R2_SECRET_ACCESS_KEY={{ index .Env "R2_SECRET_ACCESS_KEY" }}
 
 archives:
-  - format: binary
+  - formats: [binary]
     name_template: "{{ .Binary }}"
     allow_different_binary_count: true
 

AGENTS.md

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

Dockerfile

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

Makefile

@@ -1,25 +1,25 @@
 DIST := dist
-EXECUTABLE := gitea-runner
-DIST_DIRS := $(DIST)/binaries $(DIST)/release
 GO ?= go
-SHASUM ?= shasum -a 256
+EXECUTABLE := gitea-runner$(shell $(GO) env GOEXE)
 HAS_GO = $(shell hash $(GO) > /dev/null 2>&1 && echo "GO" || echo "NOGO" )
-XGO_PACKAGE ?= src.techknowlogick.com/xgo@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:657378e5cfd898e36f820459c60ef8e69be8fcda9fd354e4381a8b654d091bbc # renovate: datasource=docker
+SERVICE_IMAGE ?= nginx:1.31.7-alpine@sha256:892bb2152464f0c5d8972593a5f5afaf8054552580b699d95f8ff4af08c2d33d # renovate: datasource=docker
+E2E_GITEA_IMAGE ?= gitea/gitea:main-nightly
+E2E_K3S_IMAGE ?= rancher/k3s:v1.37.1-k3s1@sha256:ca7f37d993d82ef0dcdcfecb2e0e2618ea541dbaffc620c8cedebe01a82acd0d # renovate: datasource=docker
+WINDOWS_TEST_IMAGE ?= dockurr/windows:6.06@sha256:16fd7c39a3e48bb946d29c59dc6015942e5b900a1fa5d7e5552053bfc48ee2ea # renovate: datasource=docker
+
 GOFILES := $(shell find . -type f -name "*.go" -o -name "go.mod" ! -name "generated.*")
 
 DOCKER_IMAGE ?= gitea/runner
 DOCKER_TAG ?= nightly
 DOCKER_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)
-DOCKER_ROOTLESS_REF := $(DOCKER_IMAGE):$(DOCKER_TAG)-dind-rootless
 
-GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
-GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.3.0
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 # renovate: datasource=go
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.9.0 # renovate: datasource=go
+
+GOTEST_FLAGS ?= -race -timeout 20m -parallel 8
 
 STATIC ?=
 EXTLDFLAGS ?=
@@ -30,22 +30,16 @@ endif
 ifeq ($(HAS_GO), GO)
 	GOPATH ?= $(shell $(GO) env GOPATH)
 	export PATH := $(GOPATH)/bin:$(PATH)
-
-	CGO_EXTRA_CFLAGS := -DSQLITE_MAX_VARIABLE_NUMBER=32766
-	CGO_CFLAGS ?= $(shell $(GO) env CGO_CFLAGS) $(CGO_EXTRA_CFLAGS)
 endif
 
 ifeq ($(OS), Windows_NT)
 	GOFLAGS := -v -buildmode=exe
-	EXECUTABLE ?= $(EXECUTABLE).exe
 	GO_ENV_WINDOWS := set GOOS=windows&&
 else ifeq ($(OS), Windows)
 	GOFLAGS := -v -buildmode=exe
-	EXECUTABLE ?= $(EXECUTABLE).exe
 	GO_ENV_WINDOWS := set GOOS=windows&&
 else
 	GOFLAGS := -v
-	EXECUTABLE ?= $(EXECUTABLE)
 	GO_ENV_WINDOWS := GOOS=windows
 endif
 
@@ -94,22 +88,18 @@ 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-go-windows ## lint everything
 
@@ -131,25 +121,25 @@ 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 (integration tests self-skip without docker/network)
-	@$(GO) test -race -timeout 20m -v -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
+test: ## test everything (integration tests self-skip without docker/network)
+	@$(GO) test $(GOTEST_FLAGS) -cover -coverprofile coverage.txt ./... && echo "\n==>\033[32m Ok\033[m\n" || exit 1
 
 .PHONY: coverage-report
 coverage-report: ## turn coverage.txt from `make test` into .tmp/coverage.md
@@ -158,8 +148,18 @@ coverage-report: ## turn coverage.txt from `make test` into .tmp/coverage.md
 	@echo "Wrote .tmp/coverage.md"
 
 .PHONY: test-dind
-test-dind: ## run the daemon-facing tests against the built dind image (TARGET=dind|dind-rootless)
-	@./scripts/test-dind.sh $(TARGET)
+test-dind: ## run the daemon-facing tests against the built dind image or podman (TARGET=dind|dind-rootless|podman)
+	@PODMAN_TEST_IMAGE=$(PODMAN_TEST_IMAGE) ./scripts/test-dind.sh $(TARGET)
+
+.PHONY: test-windows
+test-windows: ## run the tests on Windows Server Core in a QEMU VM on the docker host
+	@GO=$(GO) WINDOWS_TEST_IMAGE=$(WINDOWS_TEST_IMAGE) ./scripts/test-windows.sh
+
+E2E_CONCURRENCY ?= 8
+
+.PHONY: test-e2e
+test-e2e: ## run Gitea compatibility tests against E2E_GITEA_IMAGE
+	@E2E_CONCURRENCY=$(E2E_CONCURRENCY) E2E_GITEA_IMAGE=$(E2E_GITEA_IMAGE) E2E_K3S_IMAGE=$(E2E_K3S_IMAGE) E2E_JOB_IMAGE=$(E2E_JOB_IMAGE) GO=$(GO) SERVICE_IMAGE=$(SERVICE_IMAGE) ./tools/test-e2e.sh $(E2E_ARGS)
 
 .PHONY: install
 install: $(GOFILES) ## install the runner binary via `go install`
@@ -175,45 +175,6 @@ $(EXECUTABLE): $(GOFILES)
 deps-backend: ## install backend dependencies
 	$(GO) mod download
 
-.PHONY: release
-release: release-windows release-linux release-darwin release-copy release-compress release-check ## build release artifacts
-
-$(DIST_DIRS):
-	mkdir -p $(DIST_DIRS)
-
-.PHONY: release-windows
-release-windows: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -buildmode exe -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w -linkmode external -extldflags "-static" $(LDFLAGS)' -targets '$(WINDOWS_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
-ifeq ($(CI),true)
-	cp -r /build/* $(DIST)/binaries/
-endif
-
-.PHONY: release-linux
-release-linux: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w -linkmode external -extldflags "-static" $(LDFLAGS)' -targets '$(LINUX_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
-ifeq ($(CI),true)
-	cp -r /build/* $(DIST)/binaries/
-endif
-
-.PHONY: release-darwin
-release-darwin: | $(DIST_DIRS)
-	CGO_CFLAGS="$(CGO_CFLAGS)" $(GO) run $(XGO_PACKAGE) -go $(XGO_VERSION) -dest $(DIST)/binaries -tags 'netgo osusergo $(TAGS)' -ldflags '-s -w $(LDFLAGS)' -targets '$(DARWIN_ARCHS)' -out $(EXECUTABLE)-$(VERSION) .
-ifeq ($(CI),true)
-	cp -r /build/* $(DIST)/binaries/
-endif
-
-.PHONY: release-copy
-release-copy: | $(DIST_DIRS)
-	cd $(DIST); for file in `find . -type f -name "*"`; do cp $${file} ./release/; done;
-
-.PHONY: release-check
-release-check: | $(DIST_DIRS)
-	cd $(DIST)/release/; for file in `find . -type f -name "*"`; do echo "checksumming $${file}" && $(SHASUM) `echo $${file} | sed 's/^..//'` > $${file}.sha256; done;
-
-.PHONY: release-compress
-release-compress: | $(DIST_DIRS)
-	cd $(DIST)/release/; for file in `find . -type f -name "*"`; do echo "compressing $${file}" && $(GO) run $(GXZ_PACKAGE) -k -9 $${file}; done;
-
 .PHONY: docker
 docker: ## build the docker image
 	if ! docker buildx version >/dev/null 2>&1; then \

README.md

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

act/artifactcache/doc.go

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

act/artifactcache/handler_v2.go

@@ -0,0 +1,334 @@
+// 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, 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, req.Key, req.Version, false); err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	} else if pending != nil && pending.UsedAt > time.Now().Add(-uploadStallTimeout).Unix() {
+		if pending.Owner != owner {
+			h.twirpNotOK(w, r)
+			return
+		}
+		h.touch(db, pending)                                // still uploading, so it must not go stale under the sweep
+		h.responseJSON(w, r, http.StatusOK, map[string]any{ // this job retrying its own reservation
+			"ok":                true,
+			"signed_upload_url": h.signedURL(cred, blobPath, blobUploadPurpose, pending.ID, time.Now().Add(blobUploadURLTTL)),
+		})
+		return
+	}
+
+	now := time.Now()
+	cache := &Cache{
+		Repo:           cred.Repo,
+		Ref:            cred.Ref,
+		Key:            req.Key,
+		Version:        req.Version,
+		Owner:          owner,
+		Size:           -1, // the size is only known at finalize time
+		CreatedAt:      now.Unix(),
+		CreatedAtNanos: now.Nanosecond(),
+		UsedAt:         now.Unix(),
+	}
+	if err := 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, req.Key, req.Version, false)
+	if err == nil && cache != nil && cache.Owner != hashedToken(bearerToken(r)) {
+		cache = nil // not the reservation this job made, so not this job's to commit
+	}
+	if err == nil && cache == nil {
+		// A retry whose first response was lost finds the entry already committed.
+		cache, err = findExactCache(db, cred, req.Key, req.Version, true)
+	}
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	if cache == nil {
+		h.twirpNotOK(w, r)
+		return
+	}
+
+	if !cache.Complete {
+		db.Close() // commitCache needs the store closed
+		cache.Size = int64(cmp.Or(req.SizeBytes, req.SizeBytesCamel))
+		if err := h.commitCache(cache); err != nil {
+			h.logger.Errorf("finalize cache %d (%s): %v", cache.ID, cache.Key, err)
+			h.twirpNotOK(w, r)
+			return
+		}
+	}
+
+	h.responseJSON(w, r, http.StatusOK, map[string]any{
+		"ok": true,
+		// int64 fields travel as strings in the proto JSON mapping.
+		"entry_id": strconv.FormatUint(cache.ID, 10),
+	})
+}
+
+func (h *Handler) v2GetCacheEntryDownloadURL(w http.ResponseWriter, r *http.Request) {
+	cred := credFromContext(r.Context())
+	req, err := decodeTwirpRequest[v2DownloadRequest](r)
+	if err != nil {
+		h.twirpError(w, r, "malformed", err)
+		return
+	}
+
+	db, err := h.openDB()
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	defer db.Close()
+
+	cache, err := h.lookupCache(db, cred, req.keys(), req.Version)
+	if err != nil {
+		h.twirpError(w, r, twirpInternal, err)
+		return
+	}
+	if cache == nil {
+		h.twirpNotOK(w, r)
+		return
+	}
+
+	h.responseJSON(w, r, http.StatusOK, map[string]any{
+		"ok":                  true,
+		"signed_download_url": h.signedArtifactURL(cred, cache.ID, time.Now().Add(artifactURLTTL)),
+		"matched_key":         cache.Key,
+	})
+}
+
+// The archive arrives over the subset of the Azure blob API the toolkit uses: a small
+// cache is a single PUT, a large one is staged as blocks that a final block list puts
+// in order.
+func (h *Handler) v2UploadBlob(w http.ResponseWriter, r *http.Request) {
+	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,344 @@
+// 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"
+)
+
+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
+}
+
+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 {
+		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
+}
+
+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
+}
+
+func TestCacheServiceV2RoundTrip(t *testing.T) {
+	t.Parallel()
+	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"])
+
+	assert.Equal(t, http.StatusBadRequest, putBlob(t, uploadURL, []byte("poisoned")))
+	resp, err := http.Get(uploadURL)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	assert.Equal(t, http.StatusMethodNotAllowed, resp.StatusCode)
+
+	got := v2Call(t, handler, testClient, "GetCacheEntryDownloadURL", map[string]any{"key": "deps-v1", "version": "abc123"})
+	require.Equal(t, true, got["ok"])
+	assert.Equal(t, "deps-v1", got["matched_key"])
+	downloadURL, _ := got["signed_download_url"].(string)
+	require.NotEmpty(t, downloadURL)
+	assert.Equal(t, content, getURL(t, downloadURL))
+}
+
+func TestCacheServiceV2BlockUpload(t *testing.T) {
+	t.Parallel()
+	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)
+	}
+	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) {
+	t.Parallel()
+	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"])
+	})
+
+	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"])
+	})
+
+	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"])
+	})
+
+	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"])
+	})
+
+	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"])
+	})
+
+	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"])
+	})
+
+	t.Run("each ref saves and restores its own entry for the same key", func(t *testing.T) {
+		clients := map[string]*http.Client{"x": testClient}
+		for _, ref := range []string{"y", "z"} {
+			handler.RegisterJob(ref, JobCredential{Repo: testRepo, Ref: "refs/pull/" + ref + "/head"})
+			clients[ref] = &http.Client{Transport: &bearerTransport{token: ref}}
+			created := v2Call(t, handler, clients[ref], "CreateCacheEntry", map[string]any{"key": "deps-abc", "version": "v1"})
+			require.Equal(t, true, created["ok"])
+			require.Equal(t, http.StatusCreated, putBlob(t, created["signed_upload_url"].(string), []byte(ref)))
+		}
+		for _, ref := range []string{"y", "z"} {
+			require.Equal(t, true, v2Call(t, handler, clients[ref], "FinalizeCacheEntryUpload", map[string]any{"key": "deps-abc", "version": "v1", "size_bytes": 1})["ok"])
+		}
+		for content, client := range clients {
+			got := v2Call(t, handler, client, "GetCacheEntryDownloadURL", map[string]any{"key": "deps-abc", "version": "v1"})
+			assert.Equal(t, content, string(getURL(t, got["signed_download_url"].(string))))
+		}
+	})
+}
+
+func TestCacheServiceV2RefusalsAreTwirp(t *testing.T) {
+	t.Parallel()
+	handler := newTestHandler(t, Policy{})
+
+	tests := []struct {
+		name   string
+		token  string
+		body   string
+		status int
+		code   string
+	}{
+		{"no bearer at all", "", `{"key":"k","version":"v"}`, http.StatusUnauthorized, twirpUnauthenticated},
+		{"a bearer nobody registered", "not-a-job", `{"key":"k","version":"v"}`, http.StatusUnauthorized, twirpUnauthenticated},
+		{"a body that is not the request", testToken, `{`, http.StatusBadRequest, "malformed"},
+		{"a request missing its key", testToken, `{"version":"v"}`, http.StatusBadRequest, "invalid_argument"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req, err := http.NewRequestWithContext(t.Context(), http.MethodPost,
+				handler.ExternalURL()+cacheServiceV2Path+"/CreateCacheEntry", strings.NewReader(tt.body))
+			require.NoError(t, err)
+			if tt.token != "" {
+				req.Header.Set("Authorization", "Bearer "+tt.token)
+			}
+			resp, err := http.DefaultClient.Do(req)
+			require.NoError(t, err)
+			defer resp.Body.Close()
+
+			require.Equal(t, tt.status, resp.StatusCode)
+			got := map[string]string{}
+			require.NoError(t, json.UnmarshalRead(resp.Body, &got))
+			assert.Equal(t, tt.code, got["code"])
+			assert.NotEmpty(t, got["msg"])
+		})
+	}
+}
+
+func TestCacheServiceV2ConcurrentSaveAndRetries(t *testing.T) {
+	t.Parallel()
+	handler := newTestHandler(t, Policy{})
+	content := []byte("the cached archive")
+
+	const otherJob = "another-jobs-token"
+	defer handler.RegisterJob(otherJob, JobCredential{Repo: testRepo})()
+	reserve := func(client *http.Client) map[string]any {
+		return v2Call(t, handler, client, "CreateCacheEntry", map[string]any{"key": "shared", "version": "v1"})
+	}
+	first := reserve(testClient)
+	require.Equal(t, true, first["ok"])
+	retry := reserve(testClient)
+	assert.Equal(t, true, retry["ok"], "a job retrying its own reservation is not a conflict")
+	entryOf := func(reserved map[string]any) string {
+		parsed, err := url.Parse(reserved["signed_upload_url"].(string))
+		require.NoError(t, err)
+		return parsed.Path
+	}
+	assert.Equal(t, entryOf(first), entryOf(retry), "the same reservation, however freshly its URL is signed")
+	assert.Equal(t, false, reserve(&http.Client{Transport: &bearerTransport{token: otherJob}})["ok"],
+		"another job's reservation would be finalized against the first upload")
+
+	otherClient := &http.Client{Transport: &bearerTransport{token: otherJob}}
+	reserved := v2Call(t, handler, otherClient, "CreateCacheEntry", map[string]any{"key": "owned", "version": "v1"})
+	require.Equal(t, true, reserved["ok"])
+	require.Equal(t, http.StatusCreated, putBlob(t, reserved["signed_upload_url"].(string), content))
+	assert.Equal(t, false, v2Call(t, handler, testClient, "FinalizeCacheEntryUpload",
+		map[string]any{"key": "owned", "version": "v1", "size_bytes": strconv.Itoa(len(content))})["ok"],
+		"another job's upload is not this job's to finalize")
+
+	base := handler.ExternalURL() + apiPath
+	madeByV1 := reserveCache(t, testClient, base, "v1-made", "v1", int64(len(content)))
+	upload, err := http.NewRequestWithContext(t.Context(), http.MethodPatch,
+		fmt.Sprintf("%s/caches/%d", base, madeByV1), bytes.NewReader(content))
+	require.NoError(t, err)
+	upload.Header.Set("Content-Range", fmt.Sprintf("bytes 0-%d/*", len(content)-1))
+	resp, err := testClient.Do(upload)
+	require.NoError(t, err)
+	resp.Body.Close()
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+
+	assert.Equal(t, false, v2Call(t, handler, testClient, "FinalizeCacheEntryUpload",
+		map[string]any{"key": "v1-made", "version": "v1", "size_bytes": strconv.Itoa(len(content))})["ok"],
+		"a reservation this job did not make through v2 is not its to commit")
+
+	finalized, _ := saveV2(t, handler, "deps", "v1", content)
+	require.Equal(t, true, finalized["ok"])
+	again := v2Call(t, handler, testClient, "FinalizeCacheEntryUpload", map[string]any{
+		"key": "deps", "version": "v1", "size_bytes": strconv.Itoa(len(content)),
+	})
+	assert.Equal(t, true, again["ok"], "a retry whose first answer was lost must not report a failed save")
+	assert.Equal(t, finalized["entry_id"], again["entry_id"])
+}

act/artifactcache/model.go

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

act/artifactcache/results.go

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

act/artifactcache/results_test.go

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

act/artifactcache/s3_storage.go

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

act/artifactcache/s3_storage_test.go

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

act/artifactcache/storage.go

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

act/artifacts/server_test.go

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

act/artifacts/server_v4.go

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

act/artifacts/token.go

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

act/artifacts/twirp.go

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

act/common/cartesian.go

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

act/common/cartesian_test.go

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

act/common/context_helpers_test.go

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

act/common/dryrun.go

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

act/common/executor.go

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

act/common/executor_max_parallel_test.go

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

act/common/executor_parallel_advanced_test.go

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

act/common/executor_test.go

@@ -7,177 +7,119 @@ package common
 import (
 	"context"
 	"errors"
-	"reflect"
-	"strings"
+	"fmt"
+	"sync"
 	"sync/atomic"
 	"testing"
-	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 func TestNewWorkflow(t *testing.T) {
-	assert := assert.New(t)
+	ctx := t.Context()
+	require.NoError(t, NewPipelineExecutor()(ctx))
+	require.EqualError(t, NewErrorExecutor(errors.New("test error"))(ctx), "test error")
 
-	ctx := context.Background()
-
-	// empty
-	emptyWorkflow := NewPipelineExecutor()
-	assert.NoError(emptyWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
-
-	// error case
-	errorWorkflow := NewErrorExecutor(errors.New("test error"))
-	assert.Error(errorWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
-
-	// multiple success case
 	runcount := 0
-	successWorkflow := NewPipelineExecutor(
-		func(ctx context.Context) error {
-			runcount++
-			return nil
-		},
-		func(ctx context.Context) error {
-			runcount++
-			return nil
-		})
-	assert.NoError(successWorkflow(ctx)) //nolint:testifylint // pre-existing issue from nektos/act
-	assert.Equal(2, runcount)
+	increment := func(_ctx context.Context) error {
+		runcount++
+		return nil
+	}
+	require.NoError(t, NewPipelineExecutor(increment, increment)(ctx))
+	assert.Equal(t, 2, runcount)
 }
 
-func TestNewConditionalExecutor(t *testing.T) {
-	assert := assert.New(t)
+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)
-
-	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
-
-	// 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)
+func TestNewParallelExecutor(t *testing.T) {
+	for name, parallel := range map[string]int{"parallel": 2, "below minimum": 0} {
+		t.Run(name, func(t *testing.T) {
+			exec, count, maxActive := concurrencyProbe(int32(max(1, parallel)))
+			require.NoError(t, NewParallelExecutor(parallel, exec, exec, exec)(t.Context()))
+			assert.Equal(t, int32(3), count.Load())
+			assert.Equal(t, int32(max(1, parallel)), maxActive.Load())
+		})
+	}
 }
 
 func TestNewParallelExecutorEmpty(t *testing.T) {
 	assert := assert.New(t)
 
-	ctx := context.Background()
+	ctx := t.Context()
 	require.NoError(t, NewParallelExecutor(2)(ctx))
 
-	canceledCtx, cancel := context.WithCancel(context.Background())
+	canceledCtx, cancel := context.WithCancel(t.Context())
 	cancel()
 
 	err := NewParallelExecutor(2)(canceledCtx)
 	assert.ErrorIs(err, context.Canceled)
 }
 
-func TestNewParallelExecutorFailed(t *testing.T) {
-	assert := assert.New(t)
+func TestNewParallelExecutorRunsAllTasksAfterFailureOrCancellation(t *testing.T) {
+	for name, tc := range map[string]struct {
+		canceled        bool
+		parallel, tasks int
+	}{
+		"failure":              {false, 2, 5},
+		"canceled":             {true, 2, 5},
+		"canceled single task": {true, 1, 1},
+	} {
+		t.Run(name, func(t *testing.T) {
+			ctx, cancel := context.WithCancel(t.Context())
+			defer cancel()
+			if tc.canceled {
+				cancel()
+			}
+			var calls atomic.Int32
+			executors := make([]Executor, tc.tasks)
+			for i := range executors {
+				executors[i] = func(_ctx context.Context) error {
+					calls.Add(1)
+					if i == tc.tasks/2 {
+						return errors.New("fake error")
+					}
+					return nil
+				}
+			}
 
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	count := 0
-	errorWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
-		count++
-		return errors.New("fake error")
-	})
-	err := NewParallelExecutor(1, errorWorkflow)(ctx)
-	assert.Equal(1, count)
-	assert.ErrorIs(context.Canceled, err)
-}
-
-func TestNewParallelExecutorCanceled(t *testing.T) {
-	assert := assert.New(t)
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	errExpected := errors.New("fake error")
-
-	var count atomic.Int32
-	successWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
-		count.Add(1)
-		return nil
-	})
-	errorWorkflow := NewPipelineExecutor(func(ctx context.Context) error {
-		count.Add(1)
-		return errExpected
-	})
-	err := NewParallelExecutor(3, errorWorkflow, successWorkflow, successWorkflow)(ctx)
-	assert.Equal(int32(3), count.Load())
-	assert.Error(errExpected, err) //nolint:testifylint // pre-existing issue from nektos/act
+			err := NewParallelExecutor(tc.parallel, executors...)(ctx)
+			if tc.canceled {
+				require.ErrorIs(t, err, context.Canceled)
+			} else {
+				require.EqualError(t, err, "fake error")
+			}
+			assert.Equal(t, int32(tc.tasks), calls.Load())
+		})
+	}
 }
 
 func TestExecutorConditionalsAndFinally(t *testing.T) {
-	ctx := context.Background()
+	ctx := t.Context()
 	var calls []string
 	record := func(name string) Executor {
-		return func(ctx context.Context) error {
+		return func(_ctx context.Context) error {
 			calls = append(calls, name)
 			return nil
 		}
@@ -189,26 +131,17 @@ func TestExecutorConditionalsAndFinally(t *testing.T) {
 	require.NoError(t, record("if-bool").IfBool(true)(ctx))
 	require.NoError(t, record("main").Finally(record("finally"))(ctx))
 
-	want := []string{"if-true", "if-not", "if-bool", "main", "finally"}
-	if !reflect.DeepEqual(calls, want) {
-		t.Fatalf("calls = %v, want %v", calls, want)
-	}
+	assert.Equal(t, []string{"if-true", "if-not", "if-bool", "main", "finally"}, calls)
 }
 
 func TestExecutorFinallyReturnsFinallyErrorWithOriginal(t *testing.T) {
-	mainErr := errors.New("main failed")
 	finalErr := errors.New("cleanup failed")
-
-	err := NewErrorExecutor(mainErr).Finally(NewErrorExecutor(finalErr))(context.Background())
-	require.Error(t, err)
-	if !strings.Contains(err.Error(), "cleanup failed") || !strings.Contains(err.Error(), "main failed") {
-		t.Fatalf("finally error = %q, want both cleanup and original error", err)
-	}
-}
-
-func TestConditionalNot(t *testing.T) {
-	cond := Conditional(func(context.Context) bool { return false })
-	if !cond.Not()(context.Background()) {
-		t.Fatal("inverted conditional should be true")
+	for _, mainErr := range []error{context.Canceled, nil} {
+		err := NewErrorExecutor(mainErr).Finally(NewErrorExecutor(finalErr))(t.Context())
+		require.EqualError(t, err, fmt.Sprintf("error occurred running finally: cleanup failed (original error: %v)", mainErr))
+		require.ErrorIs(t, err, finalErr)
+		if mainErr != nil {
+			require.ErrorIs(t, err, mainErr)
+		}
 	}
 }

act/common/git/fetch_action.go

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

act/common/git/fetch_action_test.go

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

act/common/git/git.go

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

act/common/git/git_test.go

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

act/common/job_error.go

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

act/common/line_writer.go

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

act/common/line_writer_test.go

@@ -9,24 +9,24 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
-func TestLineWriter(t *testing.T) {
-	lines := make([]string, 0)
-	lineHandler := func(s string) bool {
+func TestLineWriterBuffersAndFlushesLines(t *testing.T) {
+	var lines []string
+	lineWriter := NewLineWriter(func(s string) bool {
 		lines = append(lines, s)
 		return true
-	}
-
-	lineWriter := NewLineWriter(lineHandler)
+	})
 
 	assert := assert.New(t)
 	write := func(s string) {
 		n, err := lineWriter.Write([]byte(s))
-		assert.NoError(err) //nolint:testifylint // pre-existing issue from nektos/act
+		require.NoError(t, err)
 		assert.Equal(len(s), n, s)
 	}
 
+	write("")
 	write("hello")
 	write(" ")
 	write("world!!\nextra")
@@ -34,39 +34,17 @@ func TestLineWriter(t *testing.T) {
 	write(" line\n")
 	write("no newline here...")
 
-	assert.Len(lines, 4)
-	assert.Equal("hello world!!\n", lines[0])
-	assert.Equal("extra line\n", lines[1])
-	assert.Equal(" and another\n", lines[2])
-	assert.Equal("last line\n", lines[3])
-}
+	expected := []string{"hello world!!\n", "extra line\n", " and another\n", "last line\n"}
+	assert.Equal(expected, lines)
 
-func TestLineWriterFlush(t *testing.T) {
-	lines := make([]string, 0)
-	lineHandler := func(s string) bool {
-		lines = append(lines, s)
-		return true
-	}
-
-	lineWriter := NewLineWriter(lineHandler)
-
-	assert := assert.New(t)
-	_, err := lineWriter.Write([]byte("complete line\npartial line without newline"))
-	assert.NoError(err) //nolint:testifylint // pre-existing pattern from nektos/act
-
-	// Only the newline-terminated line is emitted before flushing.
-	assert.Equal([]string{"complete line\n"}, lines)
-
-	// Flushing emits the buffered, not-yet-terminated trailing line.
 	FlushWriter(lineWriter)
-	assert.Equal([]string{"complete line\n", "partial line without newline"}, lines)
+	expected = append(expected, "no newline here...")
+	assert.Equal(expected, lines)
 
-	// Flushing again is a no-op: nothing is buffered.
 	FlushWriter(lineWriter)
-	assert.Len(lines, 2)
+	assert.Equal(expected, lines)
 }
 
 func TestFlushWriterIgnoresNonFlusher(t *testing.T) {
-	// FlushWriter must be a safe no-op for writers that do not buffer lines.
 	assert.NotPanics(t, func() { FlushWriter(io.Discard) })
 }

act/common/logger.go

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

act/common/logging/console.go

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

act/common/logging/console_test.go

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

act/common/logging/global.go

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

act/common/logging/handler.go

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

act/common/logging/level.go

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

act/common/logging/logger.go

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

act/common/logging/logging_test.go

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

act/common/logging/logtest/logtest.go

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

act/common/logging/slog.go

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

act/common/logging/terminal_other.go

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

act/common/logging/terminal_windows.go

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

act/common/lookup_fold.go

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

act/common/outbound_ip.go

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

act/common/outbound_ip_test.go

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

act/container/container_types.go

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

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

act/container/docker_auth_test.go

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

act/container/docker_build.go

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

act/container/docker_build_test.go

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

act/container/docker_build_unix.go

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

act/container/docker_build_unix_test.go

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

act/container/docker_build_windows.go

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

act/container/docker_cli.go

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

act/container/docker_create_flags.go

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

act/container/docker_create_flags_test.go

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

act/container/docker_images.go

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

act/container/docker_images_test.go

@@ -5,65 +5,74 @@
 package container
 
 import (
+	"bytes"
 	"context"
 	"fmt"
-	"os"
-	"os/exec"
 	"strings"
 	"testing"
+	"time"
 
-	log "github.com/sirupsen/logrus"
+	"gitea.com/gitea/runner/act/common"
+	"gitea.com/gitea/runner/act/common/logging"
+
+	mobyclient "github.com/moby/moby/client"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 func init() {
-	log.SetLevel(log.DebugLevel)
+	logging.SetLevel(logging.LevelDebug)
 }
 
-// buildScratchImage builds a tiny empty image for the given platform locally (FROM scratch, no
-// network or emulation since there is nothing to run) and returns its tag, removing it after
-// the test.
-func buildScratchImage(t *testing.T, platform string) string {
+func loadScratchImage(t *testing.T, platform string) string {
 	t.Helper()
-	tag := fmt.Sprintf("act-test-exists-%s:latest", strings.TrimPrefix(platform, "linux/"))
-	cmd := exec.Command("docker", "build", "--platform", platform, "-t", tag, "-")
-	cmd.Stdin = strings.NewReader("FROM scratch\nLABEL act-test=1\n")
-	// Force BuildKit: it records the requested architecture in the image config for a
-	// FROM-scratch build, whereas the classic builder ignores --platform and tags it with the
-	// host arch, which would break the per-platform existence assertions below.
-	cmd.Env = append(os.Environ(), "DOCKER_BUILDKIT=1")
-	out, err := cmd.CombinedOutput()
-	require.NoError(t, err, string(out))
-	t.Cleanup(func() { _ = exec.Command("docker", "rmi", "-f", tag).Run() })
+	tag := fmt.Sprintf("act-test-exists-%s-%d:latest", strings.TrimPrefix(platform, "linux/"), time.Now().UnixNano())
+	var archive bytes.Buffer
+	require.NoError(t, writeFilesTar(t.Context(), &archive, 0, 0,
+		&FileEntry{Name: "config.json", Mode: 0o600, Body: fmt.Sprintf(`{"architecture":%q,"os":"linux","rootfs":{"type":"layers","diff_ids":[]}}`, strings.TrimPrefix(platform, "linux/"))},
+		&FileEntry{Name: "manifest.json", Mode: 0o600, Body: fmt.Sprintf(`[{"Config":"config.json","RepoTags":[%q],"Layers":[]}]`, tag)},
+	))
+	cli, err := GetDockerClient(t.Context())
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = cli.Close() })
+	response, err := cli.ImageLoad(t.Context(), &archive)
+	require.NoError(t, err)
+	defer response.Close()
+	require.NoError(t, logDockerResponse(common.Logger(t.Context()), response, false))
+	t.Cleanup(func() {
+		_, _ = cli.ImageRemove(context.WithoutCancel(t.Context()), tag, mobyclient.ImageRemoveOptions{Force: true})
+	})
 	return tag
 }
 
 func TestImageExistsLocally(t *testing.T) {
+	t.Parallel()
 	requireDocker(t)
-	ctx := context.Background()
+	ctx := t.Context()
 
-	// a non-existent image is reported absent
 	missing, err := ImageExistsLocally(ctx, "library/alpine:this-random-tag-will-never-exist", "linux/amd64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 	assert.False(t, missing)
 
-	// Build tiny images for two architectures locally so per-platform existence can be checked
-	// offline (formerly pulled node:24-bookworm-slim for amd64 and arm64 over the network).
-	amd64Ref := buildScratchImage(t, "linux/amd64")
-	arm64Ref := buildScratchImage(t, "linux/arm64")
+	amd64Ref := loadScratchImage(t, "linux/amd64")
+	arm64Ref := loadScratchImage(t, "linux/arm64")
 
 	amd64Exists, err := ImageExistsLocally(ctx, amd64Ref, "linux/amd64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 	assert.True(t, amd64Exists)
 
-	// a non-host architecture image is detected for its own architecture
 	arm64Exists, err := ImageExistsLocally(ctx, arm64Ref, "linux/arm64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 	assert.True(t, arm64Exists)
 
-	// a present image is reported absent for a different platform
 	wrongPlatform, err := ImageExistsLocally(ctx, amd64Ref, "linux/arm64")
 	assert.NoError(t, err) //nolint:testifylint // pre-existing issue from nektos/act
 	assert.False(t, wrongPlatform)
+
+	removed, err := RemoveImage(ctx, amd64Ref, false, false)
+	require.NoError(t, err)
+	assert.True(t, removed)
+	removed, err = RemoveImage(ctx, amd64Ref, false, false)
+	require.NoError(t, err)
+	assert.False(t, removed)
 }

act/container/docker_logger.go

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

act/container/docker_network.go

@@ -2,87 +2,284 @@
 // Copyright 2023 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd))
+//go:build !(WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd))
 
 package container
 
 import (
 	"context"
+	"errors"
+	"fmt"
+	"net/netip"
+	"strings"
+	"time"
 
 	"gitea.com/gitea/runner/act/common"
 
+	cerrdefs "github.com/containerd/errdefs"
+	"github.com/moby/moby/api/types/network"
 	"github.com/moby/moby/client"
 )
 
+const (
+	networkCreateAttempts   = 3
+	networkCreateRetryDelay = time.Second
+)
+
+// 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 {
+	return common.Executor(func(ctx context.Context) error {
 		cli, err := GetDockerClient(ctx)
 		if err != nil {
 			return err
 		}
 		defer cli.Close()
+		return createDockerNetwork(ctx, cli, name, opts)
+	}).IfNot(common.Dryrun)
+}
 
-		// Only create the network if it doesn't exist
-		networks, err := cli.NetworkList(ctx, client.NetworkListOptions{})
-		if err != nil {
-			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):
 			}
 		}
-
-		_, err = cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{
+		if _, err = cli.NetworkCreate(ctx, name, client.NetworkCreateOptions{
 			Driver:     "bridge",
 			Scope:      "local",
 			EnableIPv4: opts.EnableIPv4,
 			EnableIPv6: opts.EnableIPv6,
-		})
-		if err != nil {
+			Options:    options,
+			Labels:     runnerLabels(opts.RunnerUUID),
+		}); err == nil {
+			return nil
+		}
+		if !isAddressPoolExhausted(err) {
 			return err
 		}
-
-		return nil
 	}
+	return fmt.Errorf("docker has no address pool left for this job's network, lower runner.capacity or widen default-address-pools in the docker daemon config: %w", err)
 }
 
-func NewDockerNetworkRemoveExecutor(name string) common.Executor {
-	return func(ctx context.Context) error {
+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 common.Executor(func(ctx context.Context) error {
 		cli, err := GetDockerClient(ctx)
 		if err != nil {
 			return err
 		}
 		defer cli.Close()
+		if err := connectNetwork(ctx, cli, networkName, container); err != nil {
+			common.Logger(ctx).Warnf("cannot connect %s to network %s, so jobs on it cannot reach the cache: %v", container, networkName, err)
+		}
+		return nil
+	}).IfNot(common.Dryrun)
+}
 
-		// Make sure that all network of the specified name are removed
-		// cli.NetworkRemove refuses to remove a network if there are duplicates
-		networks, err := cli.NetworkList(ctx, client.NetworkListOptions{})
+func connectNetwork(ctx context.Context, cli client.APIClient, networkName, container string) error {
+	_, err := cli.NetworkConnect(ctx, networkName, client.NetworkConnectOptions{
+		Container:      container,
+		EndpointConfig: &network.EndpointSettings{Aliases: []string{container}},
+	})
+	if err != nil && (strings.Contains(err.Error(), "already exists in network") || strings.Contains(err.Error(), "already connected")) {
+		return nil
+	}
+	return err
+}
+
+func NewDockerNetworkDisconnectExecutor(networkName, container string) common.Executor {
+	return common.Executor(func(ctx context.Context) error {
+		cli, err := GetDockerClient(ctx)
 		if err != nil {
 			return err
 		}
-		// For Gitea, reduce log noise
-		// common.Logger(ctx).Debugf("%v", networks)
-		for _, n := range networks.Items {
-			if n.Name == name {
-				result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
-				if err != nil {
-					return err
-				}
+		defer cli.Close()
+		return disconnectNetwork(ctx, cli, networkName, container)
+	}).IfNot(common.Dryrun)
+}
 
-				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)
-				}
-			}
+func disconnectNetwork(ctx context.Context, cli client.APIClient, networkName, container string) error {
+	_, err := cli.NetworkDisconnect(ctx, networkName, client.NetworkDisconnectOptions{Container: container, Force: true})
+	if cerrdefs.IsNotFound(err) || (err != nil && strings.Contains(err.Error(), "is not connected")) {
+		return nil
+	}
+	return err
+}
+
+func NewDockerNetworkRemoveExecutor(name string) common.Executor {
+	return common.Executor(func(ctx context.Context) error {
+		cli, err := GetDockerClient(ctx)
+		if err != nil {
+			return err
 		}
+		defer cli.Close()
+		return removeNetwork(ctx, cli, name)
+	}).IfNot(common.Dryrun)
+}
 
+func removeNetwork(ctx context.Context, cli client.APIClient, name string) error {
+	networks, err := cli.NetworkList(ctx, client.NetworkListOptions{}) // NetworkRemove by name refuses duplicates, so remove each by ID
+	if err != nil {
 		return err
 	}
+	var errs []error
+	for _, n := range networks.Items {
+		if n.Name != name {
+			continue
+		}
+		result, err := cli.NetworkInspect(ctx, n.ID, client.NetworkInspectOptions{})
+		if cerrdefs.IsNotFound(err) {
+			continue
+		} else if err != nil {
+			return err
+		}
+		if len(result.Network.Containers) != 0 {
+			common.Logger(ctx).Warnf("Refusing to remove network %s because it still has active endpoints, the orphan cleanup reclaims it once they are gone", name)
+			continue
+		}
+		if _, err = cli.NetworkRemove(ctx, n.ID, client.NetworkRemoveOptions{}); err != nil && !cerrdefs.IsNotFound(err) {
+			errs = append(errs, fmt.Errorf("failed to remove network %s: %w", name, err))
+		}
+	}
+	return errors.Join(errs...)
+}
+
+// IsolatedCacheContainer returns the container holding addr, when jobs on jobNetwork cannot reach it there.
+func IsolatedCacheContainer(ctx context.Context, addr netip.Addr, jobNetwork string) (string, error) {
+	cli, err := GetDockerClient(ctx)
+	if err != nil {
+		return "", err
+	}
+	defer cli.Close()
+	return isolatedCacheContainer(ctx, cli, addr, jobNetwork)
+}
+
+func isolatedCacheContainer(ctx context.Context, cli client.APIClient, addr netip.Addr, jobNetwork string) (string, error) {
+	if jobNetwork == "host" || strings.HasPrefix(jobNetwork, "container:") {
+		return "", nil
+	}
+	containers, err := cli.ContainerList(ctx, client.ContainerListOptions{})
+	if err != nil {
+		return "", err
+	}
+	var holderID, holderContainer string
+	for _, summary := range containers.Items {
+		if summary.NetworkSettings == nil {
+			continue
+		}
+		for _, endpoint := range summary.NetworkSettings.Networks {
+			if endpoint != nil && (endpoint.IPAddress == addr || endpoint.GlobalIPv6Address == addr) {
+				holderID = endpoint.NetworkID
+				holderContainer = summary.ID[:12]
+			}
+		}
+	}
+	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.go

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

act/container/docker_platform_test.go

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

act/container/docker_proxy.go

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

act/container/docker_proxy_test.go

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

act/container/docker_proxy_unix.go

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

act/container/docker_proxy_windows.go

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

act/container/docker_pull.go

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

act/container/docker_pull_test.go

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

act/container/docker_socket.go

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

act/container/docker_socket_test.go

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

act/container/docker_ssh.go

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

act/container/docker_ssh_linux.go

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

act/container/docker_ssh_test.go

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

act/container/docker_ssh_unix.go

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

act/container/docker_ssh_windows.go

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

act/container/docker_stub.go

@@ -2,20 +2,26 @@
 // Copyright 2023 The nektos/act Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-//go:build WITHOUT_DOCKER || !(linux || darwin || windows || netbsd)
+//go:build WITHOUT_DOCKER || !(linux || darwin || windows || netbsd || freebsd)
 
 package container
 
 import (
 	"context"
+	"errors"
+	"net/netip"
 	"runtime"
+	"time"
 
 	"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 {
@@ -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

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

act/container/executions_environment.go

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

act/container/helpers_test.go

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