docs: runner relabeled to fedora (gitea-runner v3.5.0, site-wide); bump rpm-sources template to Fedora 44

RUNBOOK.md

@@ -13,31 +13,50 @@ Cookbook for operating the Phyllome OS factory on `git.phyllo.me`.
 ## 1. Register a runner (one-time)
 
 The runner connects **out** to `git.phyllo.me`, so it never needs an inbound
-rule. Registration needs a token from the Gitea UI:
+rule. Registration needs a one-time registration token.
 
-1. **Get a registration token** (admin/owner action — cannot be done with the
-   API token):
-   Log in to `git.phyllo.me` → **Settings → Actions → Runners** →
-   *New runner* → copy the token. Leave the window open; the token is
-   one-time-use.
+> **Scope gotcha (2026-09-19).** Registration tokens are scope-specific and
+> one-time-use. Where you click to create the token determines which repos the
+> runner will serve:
+>
+> | Where you click | Scope | Serves |
+> |---|---|---|
+> | **Settings → Actions → Runners** | user | only *that user's* repos |
+> | **Org Settings → Actions → Runners** | org | that org's repos |
+> | **Site Administration → Actions → Runners** | site-wide | every repo |
+>
+> A user-scope runner will happily *register* and show **online** but will
+> **never pick up jobs** from org repos — jobs sit `queued` with `runner_id: 0`
+> (symptom: Gitea logs show only `Declare`/`Register`, no `FetchTask`). For the
+> factory (org + repo-wide jobs) you must use a **site-wide** token. Tokens are
+> one-time and admin/owner only — cannot be minted with the API token.
+
+1. **Get a registration token**: Log in to `git.phyllo.me` → **Site
+   Administration → Actions → Runners** → *New runner* → copy the token. Leave
+   the window open; the token is one-time-use.
 2. **Deploy the runner VM** on the phyllome Cloudron host. Two supported
    routes:
    - *Ansible* (existing playbook): `devops/ansible-gitea-runner` — set
      `registration_token` in `roles/runner_setup.yml`, point
      `inventory.ini` at the VM, then `ansible-playbook main.yml`.
-   - *Manual*: install `act_runner` v0.2.13 on a Fedora VM, then:
+   - *Manual*: install `gitea-runner` v3.5.0 on a Fedora 44 VM, then:
 
      ```console
-     $ sudo -u act_runner act_runner register --no-interactive \
+     $ sudo -u act_runner gitea-runner register --no-interactive \
          --instance https://git.phyllo.me --token <TOKEN> \
-         --name fedora-0 --labels fedora
+         --name fedora-0 --labels fedora:host
      ```
 
-     Then run `act_runner daemon` under systemd (see
+     Then run `gitea-runner daemon` under systemd (see
      `devops/ansible-gitea-runner/roles/runner_setup.yml` for the unit).
-3. **Verify**: Gitea UI → **Settings → Actions → Runners** shows the runner
-   **online**, label `fedora`.
+3. **Verify**: Gitea UI → **Site Administration → Actions → Runners** shows the
+   runner **online**, label `fedora`.
 
+> Runner label syntax is `name:executor` (e.g. `fedora:host`). The **label name
+> is `fedora`** — jobs must `runs-on: fedora`. The Fedora version (44) is
+> carried in the container image tag (e.g. `fedora-runner-image:44`), not in the
+> label (a bare `fedora:44` would be parsed as an invalid executor).
+>
 > The old runner labels `fedora-cloud-42` were renamed to `fedora`
 > (2026-09-15) — all workflows must use `runs-on: fedora`.
 
@@ -89,9 +108,13 @@ chroots).
 ## 5. Troubleshooting
 
 - **Runner never comes online**: re-check the registration token (one-time use)
-  and that `act_runner daemon` is running (`systemctl status act_runner`).
-- **Job stuck in `queued`/`waiting for runner`**: label mismatch — the job's
-  `runs-on` must exactly match a label the runner registers (`fedora`).
+  and that `gitea-runner daemon` is running (`systemctl status act_runner`).
+- **Runner online but jobs never start (stuck `queued` / `waiting for runner`,
+  `runner_id: 0`)**: registration **scope** mismatch — a user/org-scope runner
+  can't serve jobs from repos outside that scope. Re-register with a **site-wide**
+  token (Site Administration → Actions → Runners). See §1.
+- **Job stuck in `queued`/`waiting for runner`, runner_id set**: label mismatch —
+  the job's `runs-on` must exactly match a label the runner registers (`fedora`).
 - **Container job can't pull the image**: runner needs network to
   `git.phyllo.me` package registry; check `docker pull
   git.phyllo.me/devops/fedora-runner-image:latest` on the VM; verify the token

docs/architecture.md

@@ -19,7 +19,7 @@ flowchart LR
     end
 
     subgraph runbox["runner VM (on the phyllome Cloudron host)"]
-        r1[act_runner daemon]
+        r1[gitea-runner daemon]
         host[HOST labels: run-on-host jobs<br>mock / livemedia-creator / pykickstart]
         img[CONTAINER labels:<br>docker://git.phyllo.me/devops/fedora-runner-image]
     end
@@ -72,9 +72,10 @@ flowchart LR
 
 - **Self-contained actions**: all `uses:` point at `git.phyllo.me/...` mirrors —
   no third-party action code, no github.com calls.
-- **Runner host**: dedicated VM on the phyllome Cloudron host; `act_runner`
-  runs as unprivileged `act_runner` system user; Docker access for container
-  jobs only.
+- **Runner host**: dedicated VM on the phyllome Cloudron host; `gitea-runner`
+  v3.5.0 runs as unprivileged `act_runner` system user; Docker access for container
+  jobs only. Registered site-wide with label `fedora` (runs-on: fedora); the VM
+  runs Fedora 44.
 - **Secrets**: CI secrets live in Gitea (repo/org) — never in the runner config.
   Registration token is UI-generated and consumed once.
 - **Read-only infra automation**: the `automation` repo's MCP servers scope

docs/server-phyllome-cloudron.md

@@ -50,14 +50,17 @@ documents what the factory depends on.
   - `devops/fedora-oci`, `devops/qemu-libvirt-oci-image` — builder images
   - `roots/fedora-iso-creation:42` — devcontainer referenced by test-actions
 - **Gitea Actions** is enabled on the product repos.
-- **Runners**: none registered yet → see `RUNBOOK.md`. Expected label: `fedora`.
+- **Runner**: one site-wide runner (`fedora-nuc`, id 56) on the dedicated runner
+  VM on this host, label `fedora` (Fedora 44). See `RUNBOOK.md` §1 for
+  registration/scope.
 
 ## Access model
 
 - `git.phyllo.me` user `lukas` (id 4, **not** Gitea admin) — used by the read and
   write API tokens.
 - Runner registration requires a **runner registration token** from the Gitea UI
-  (Settings → Actions → Runners) — admin/owner action, see RUNBOOK.
+  (**Site Administration → Actions → Runners** for site-wide) — admin/owner
+  action, see RUNBOOK.
 - Cloudron ownership is via an OIDC/owner account `superuser@phyllo.me`; API
   tokens (`tower-read`, `tower`, …) are created/deleted via the Cloudron UI
   (visible in the event log).

templates/rpm-sources.smoke.yml

@@ -17,17 +17,17 @@ jobs:
         with:
           fetch-depth: 0
       - name: Initialize mock root
-        run: mock -r fedora-43-x86_64 --init
+        run: mock -r fedora-44-x86_64 --init
       - name: Install build deps
         run: |
-          mock -r fedora-43-x86_64 --install git make gcc
+          mock -r fedora-44-x86_64 --install git make gcc
       - name: Smoke build
         run: |
-          mock -r fedora-43-x86_64 --copyin . /builddir/src
-          mock -r fedora-43-x86_64 --shell --enable-network --isolation=simple << 'EOF'
+          mock -r fedora-44-x86_64 --copyin . /builddir/src
+          mock -r fedora-44-x86_64 --shell --enable-network --isolation=simple << 'EOF'
           cd /builddir/src
           make || true
           EOF
       - name: Cleanup
         if: always()
-        run: mock -r fedora-43-x86_64 --clean
+        run: mock -r fedora-44-x86_64 --clean