devops/software-factory
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Lukas Greve
2026-09-19 12:05:33 +02:00
parent cde9b21e42
commit 81a78faf42
4 changed files with 53 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
RUNBOOK.md
+38 -15
View File
@@ -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