docs(gitea): complete DNS fix — act_runner host + job-container both

Adds dns: [8.8.8.8, 1.1.1.1] to the act_runner compose service itself.
The existing container.options --dns setting only covers job sub-
containers; act_runner's own process also clones actions/checkout and
was still using 127.0.0.11. Troubleshooting section rewritten to
explain both clone paths and give copy-paste fixes + verification.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitea/gitea_compose_qnap_all_in_one.md

@@ -86,6 +86,17 @@ services:
     restart: unless-stopped
     depends_on:
       - gitea
+    # WICHTIG: dns am act_runner-Container selbst setzen, NICHT nur in
+    # container.options (das wirkt nur auf Job-Sub-Container). act_runner
+    # clont `actions/checkout` etc. aus seinem eigenen Prozess heraus nach
+    # /data/workflows — dafür zählt seine eigene /etc/resolv.conf. Ohne
+    # diese Zeilen steht dort 127.0.0.11 (Dockers embedded DNS im
+    # gitea_gitea-Netz), was auf QNAP unzuverlässig forwarded ("server
+    # misbehaving") und jedes action-Clone killt.
+    dns:
+      - 8.8.8.8
+      - 1.1.1.1
+    dns_search: []
     environment:
       - GITEA_INSTANCE_URL=http://gitea:3000
       - GITEA_RUNNER_REGISTRATION_TOKEN=218iFl8s3a6uJxntyoobzu24pQJBGGVIWmdtJbXh
@@ -235,37 +246,70 @@ Zusätzlich: QNAP **Storage & Snapshots** → Volume-Snapshots für `/share/Cont
 - Fehler `docker: command not found` → Job-Container hat kein Docker-CLI. Runner-Label muss ein Image verwenden, das `docker` mitbringt (z.B. `catthehacker/ubuntu:act-latest`). `node:*`-Images reichen nicht, weil dort nur Node installiert ist
 - Fehler `Get "https://github.com/..." ... dial tcp: lookup github.com on 127.0.0.11:53: server misbehaving` → Docker-interner DNS im `gitea_gitea`-Netz forwarded unzuverlässig. Fix: `container.options: "--dns 8.8.8.8 --dns 1.1.1.1"` in der Runner-Config setzen, damit Job-Container externen DNS direkt nutzen
 
-**DNS-Timeouts / hängende `git clone` ohne Fehlermeldung:**
+**DNS-Timeouts / `server misbehaving` beim `actions/checkout`-Clone — komplette Lösung:**
 
-Symptom: Job steht minutenlang bei `cloning https://github.com/actions/checkout` bzw. `actions/setup-node` ohne weiteren Output; kein `server misbehaving`, kein Timeout. Gleichzeitig scheitern parallele Jobs im selben Run sporadisch sofort mit `lookup github.com on 127.0.0.11:53: server misbehaving`.
+Symptom: Jobs scheitern mit
 
-Ursachen (mehrere verketten sich):
+```text
+Get "https://github.com/actions/checkout/info/refs?service=git-upload-pack":
+dial tcp: lookup github.com on 127.0.0.11:53: server misbehaving
+```
 
-1. `127.0.0.11` ist Dockers embedded DNS-Resolver. Er forwarded an die Upstream-Resolver der Docker-Daemon-Config. Auf QNAP ist dieser Upstream häufig ein (langsamer/überlasteter) ISP-DNS oder fehlschlagender Provider-Resolver.
+oder hängen minutenlang bei `cloning https://github.com/actions/checkout`.
-2. `--dns 8.8.8.8 --dns 1.1.1.1` in `container.options` injiziert die DNS-Server in `/etc/resolv.conf` **innerhalb** des Job-Containers — das behebt `server misbehaving`, aber nur wenn der Daemon die Option korrekt anwendet (`act_runner` ≥ 0.2.11).
-3. Parallele Job-Starts erzeugen kurzzeitig 5–10 gleichzeitige DNS-Lookups → Upstream drosselt → hängende TCP-Connects ohne sauberes Fail.
 
-**Dauerhafter Fix:**
+### Die Fallstricke (wichtig zum Verstehen, warum es ZWEI Fixes braucht)
+
+`act_runner` führt beim Start eines Jobs **zwei unabhängige** Clone-Operationen aus:
+
+1. **Im act_runner-Prozess selbst** (vor Job-Container-Start): clont Actions nach `/data/workflows/...`, benutzt seine eigene `/etc/resolv.conf`.
+2. **Im Job-Sub-Container** (während Job-Run): benutzt seine eigene `/etc/resolv.conf`.
+
+**Beides** zeigt per Default auf `127.0.0.11` (Dockers embedded DNS im `gitea_gitea`-Netz), das wiederum an den QNAP-Host-Upstream forwarded. Dieser Upstream ist auf QNAP oft unzuverlässig → `server misbehaving`.
+
+Der `container.options: "--dns ..."`-Eintrag in der Runner-`config.yaml` betrifft **nur Fall 2** (Job-Sub-Container). Fall 1 (act_runner selbst) braucht einen separaten Fix am Compose-Service.
+
+### Copy-Paste-Lösung (beide Ebenen gleichzeitig)
+
+**1) Am `act_runner`-Service in der compose — setzt seine eigene `/etc/resolv.conf` auf Upstream-DNS** (in der obigen compose.yml schon eingebaut):
+
+```yaml
+act_runner:
+  image: gitea/act_runner:latest
+  # ... restliche Config ...
+  dns:
+    - 8.8.8.8
+    - 1.1.1.1
+  dns_search: []
+```
+
+**2) In der inline-generierten `/config.yaml` — setzt Upstream-DNS in jedem Job-Sub-Container** (ebenfalls schon eingebaut):
 
 ```yaml
-# config.yaml des act_runner
 container:
   network: gitea_gitea
   options: "--dns 8.8.8.8 --dns 1.1.1.1 --dns-search ."
   # `--dns-search .` entfernt jede geerbte Search-Domain → keine verirrten NXDOMAIN-Retries
 ```
 
-**Alternative 1 — Host-Network:**
+Nach dem Ändern: Stack neu deployen, damit der act_runner-Container mit der neuen DNS-Config startet.
 
-```yaml
+### Verifikation nach dem Deploy
-container:
+
-  network: host
+```bash
-  # options: "" entfernen, --dns ist dann irrelevant
+# 1. DNS aus Sicht des act_runner-Containers selbst — muss sofort eine IP liefern
+docker exec gitea-act-runner sh -c 'cat /etc/resolv.conf && nslookup github.com'
+# Erwartet: nameserver 8.8.8.8 / 1.1.1.1, nicht 127.0.0.11
+#           Name: github.com, Address: 140.82.x.x
+
+# 2. DNS aus Sicht eines Job-Sub-Containers
+docker run --rm --network gitea_gitea --dns 8.8.8.8 alpine:3 \
+  sh -c 'apk add --no-cache bind-tools >/dev/null && dig +short github.com'
+# Erwartet: sofortige IP-Antwort
 ```
 
-Nachteil: Jobs können auf Host-Ports zugreifen (Security-Impact bei Multi-Tenant).
+Hängen oder `server misbehaving` → siehe Alternativen unten.
 
-**Alternative 2 — Dockerd default-dns fixieren (macht auch andere Container robuster):**
+### Alternative A — Docker-Daemon global fixen (robuster, wirkt auf ALLE Container)
 
 In `/etc/docker/daemon.json` auf dem QNAP:
 
@@ -276,34 +320,51 @@ In `/etc/docker/daemon.json` auf dem QNAP:
 }
 ```
 
-Dann Docker-Daemon restart (Container Station → Advanced → Restart Docker). Wirkt auf alle Container, auch ohne `--dns`-Option pro Job.
+Dann Docker-Daemon restart (Container Station → Advanced → Restart Docker). Macht die compose-seitigen `dns:`-Einträge überflüssig, hilft aber auch jedem anderen Container.
 
-**Alternative 3 — Pre-warm der Action-Repos (umgeht den Clone):**
+### Alternative B — Pre-warm der Action-Repos (umgeht den Clone komplett)
 
 `act_runner` cached bereits geklonte Action-Repos unter `/data/cache/actions`. Einmal manuell anstoßen:
 
 ```bash
-docker exec -it act_runner sh -c '
+docker exec gitea-act-runner sh -c '
   mkdir -p /data/cache/actions/github.com/actions &&
   cd /data/cache/actions/github.com/actions &&
-  git clone --depth 1 --branch v4 https://github.com/actions/checkout &&
+  for repo in checkout setup-node cache upload-artifact download-artifact; do
-  git clone --depth 1 --branch v4.0.4 https://github.com/actions/setup-node &&
+    [ -d "$repo" ] || git clone --depth 1 "https://github.com/actions/$repo"
-  git clone --depth 1 --branch v4 https://github.com/actions/cache &&
+  done
-  git clone --depth 1 --branch v4 https://github.com/actions/upload-artifact
 '
 ```
 
-Danach laufen Jobs ohne DNS-Dependency zu github.com durch (solange der Cache nicht gelöscht wird).
+Danach laufen Jobs ohne DNS-Dependency zu github.com durch, solange der Cache nicht gelöscht wird.
 
-**Debug-Check:**
+### Alternative C — Host-Network für Job-Container
 
-```bash
+```yaml
-# DNS aus Job-Container-Sicht verifizieren
+container:
-docker run --rm --network gitea_gitea --dns 8.8.8.8 alpine:3 \
+  network: host
-  sh -c 'apk add --no-cache bind-tools && dig +short github.com'
+  # options ohne --dns
 ```
 
-Liefert das sofort eine IP, ist DNS OK. Hängt es → DNS-Upstream-Problem (Alternative 2 oder 3 nötig).
+Nachteil: Jobs sehen Host-Ports (Security-Impact bei Multi-Tenant). Nur als Notnagel.
+
+### Parallele-Job-Drosselung
+
+Parallele Job-Starts erzeugen kurzzeitig 5–10 gleichzeitige DNS-Lookups; wenn dein Upstream-DNS drosselt, hängen Connects ohne sauberes Fail. Dann in der Runner-`config.yaml`:
+
+```yaml
+runner:
+  capacity: 2 # statt 4 — reduziert parallele Starts
+```
+
+**Debug-Snippet — wer resolved gerade was:**
+
+```bash
+# Alle Container mit ihrer resolv.conf-Config
+for c in $(docker ps --format '{{.Names}}'); do
+  echo "=== $c ==="; docker exec "$c" cat /etc/resolv.conf 2>/dev/null
+done
+```
 
 **`uses: actions/checkout@v4` schlägt fehl:**