runner: reproducible nix-built job image + compose-based act_runner

runner/README.md

@@ -0,0 +1,71 @@
+# cargoxx-pkgs runner
+
+Self-hosted Gitea Actions runner that validates package PRs.
+
+## Architecture
+
+```
++----------------+        +-------------------+        +--------------------+
+| Gitea instance | <----> |  act_runner       | -----> | job container      |
+| (queues jobs)  |   poll | (this docker-     |  docker| cargoxx-runner-    |
+|                |        |  compose service) |  spawn | job:latest         |
++----------------+        +-------------------+        +--------------------+
+```
+
+- `compose.yml` runs the official `gitea/act_runner:nightly` image,
+  which polls Gitea for jobs and spawns one container per workflow
+  run via the host's Docker socket.
+- `flake.nix` builds the **job container image** — reproducible,
+  declarative, ships `nix`, `git`, `curl`, `jq`, `tea`, and a
+  single-user `NIX_CONFIG`. This image runs the actual workflow
+  steps; act_runner just orchestrates it.
+- `config.yaml` maps `runs-on: self-hosted` (from
+  `.gitea/workflows/*.yml`) to the job image.
+
+## One-time setup
+
+1. **Build + load the job image** into the host's Docker daemon:
+
+   ```sh
+   cd runner
+   nix run --extra-experimental-features 'nix-command flakes' .#load-image
+   ```
+
+   Re-run whenever you bump nixpkgs or change the tool list.
+
+2. **Mint a runner registration token** in the Gitea UI:
+   `Site Administration → Actions → Runners → Create new Runner`.
+   Copy the token.
+
+3. **Provision the `.env`** alongside `compose.yml`:
+
+   ```env
+   GITEA_INSTANCE_URL=https://git.amadey.xyz
+   GITEA_RUNNER_REGISTRATION_TOKEN=<paste here>
+   GITEA_RUNNER_NAME=cargoxx-pkgs-runner
+   GITEA_RUNNER_LABELS=self-hosted
+   ```
+
+4. **Start the runner**:
+
+   ```sh
+   docker compose up -d
+   docker compose logs -f runner
+   ```
+
+   First boot registers the runner with Gitea; subsequent boots reuse
+   the persisted token in `./data/.runner`.
+
+## Updating
+
+- Change a workflow step's tools → edit `flake.nix`, rerun
+  `nix run .#load-image`.
+- Bump nixpkgs → `nix flake update` in this dir, rebuild the image.
+- act_runner itself updates by `docker compose pull && docker compose up -d`.
+
+## Why not host mode?
+
+Host mode (act_runner running workflows directly on the host) would
+save the Docker indirection but tightly couples the runner host to
+the toolchain. Docker mode lets us treat the job image as a
+deployable artifact — same image on every runner, no drift.