ci: the runner is docker-mode, and a guide for setting one up

`runs-on: ubuntu-latest` stays what it is everywhere else — a disposable
container — and `docker-compose.ci.yml` is now what makes that true: the label
maps to `catthehacker/ubuntu:act-24.04`, job containers share the runner's
network so the cache server is reachable at all, and the host's docker socket is
passed through (`docker_host: automount`) so the image workflow can build.

The failure this is replacing is worth naming, because the symptom does not
point at it: with a **host**-mode runner answering the same label, every job runs
directly on the server as the runner's own user, so the workflows' `apt-get
install` steps fail on permissions — and had they succeeded, CI would have been
installing packages on a host. A workflow cannot tell which kind of runner it
got; only the label map can say.

`docs/gitea-runner.md` is the separate guide: why docker mode, the prerequisites
including Gitea's two `app.ini` settings, the install, how to remove a host-mode
runner (and what to check before you do, since a runner is shared), how to
verify a job really is in a container, why labels cannot be changed without
re-registering, and a table of the failures with their causes.

Also `workflow_dispatch` on the test workflow, so a fresh runner can be proved
from the UI without inventing a commit.

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

deploy/act-runner.yaml

@@ -1,26 +1,48 @@
-# act_runner's own configuration. See docker-compose.ci.yml for what it is for.
+# act_runner's own configuration, mounted into the container as
+# /config/config.yaml. See docker-compose.ci.yml and docs/gitea-runner.md.
 log:
   level: info
 
 runner:
+  # Two jobs at a time. The test workflow has four, so a push runs them in two
+  # waves on an 8-core box — raise it if the box is idle anyway.
   capacity: 2
   timeout: 1h
-  # Jobs pull their own tooling; nothing here needs to be fetched per job.
-  fetch_timeout: 10s
-  fetch_interval: 5s
+  shutdown_timeout: 3h
+  insecure: false
+  fetch_timeout: 5s
+  fetch_interval: 2s
+  # Deliberately empty: the labels come from GITEA_RUNNER_LABELS at registration
+  # and live in .runner afterwards. Setting them in both places is how they end
+  # up disagreeing.
+  labels: []
 
 cache:
-  # Gitea's built-in cache server is what makes actions/cache@v4 work, and the
-  # Android SDK download is worth caching: it is most of that job's wall clock.
+  # What makes `actions/cache@v4` work — the Android SDK download and the gradle
+  # caches are most of the APK job's wall clock. The server is run by the runner
+  # itself, inside the container, and reached by job containers over the shared
+  # `gitea-runner` network, so there is no port to publish or firewall.
   enabled: true
+  dir: ""
+  host: ""
+  port: 0
 
 container:
-  network: bridge
+  # The same network the runner is on. Not `bridge`: on the default bridge the
+  # job containers cannot reach the runner's cache server.
+  network: gitea-runner
   privileged: false
-  # The host's docker daemon, for the image build. Both lines are needed: the
-  # mount itself, and the allow-list that permits it.
-  options: -v /var/run/docker.sock:/var/run/docker.sock
+  options:
+  workdir_parent: workspace
+  # Mount the host's docker socket into job containers that ask for docker, so
+  # `docker.yml` can build and push. `valid_volumes` is the allow-list that
+  # makes any such mount legal at all.
+  docker_host: automount
   valid_volumes:
     - /var/run/docker.sock
-  # Let the job's own `docker` CLI find it.
-  docker_host: unix:///var/run/docker.sock
+  force_pull: false
+  force_rebuild: false
+
+host:
+  # Only used by `:host` labels, which this runner deliberately does not offer.
+  workdir_parent: /tmp/act_runner