4.1 KiB
Gitea act_runner Setup
Last Updated: 2026-03-27 (bootstrap script + ubuntu-latest labels)
Gitea: https://gitea.d-bis.org
Runner host: dev-vm (VMID 5700) at 192.168.11.59 (Gitea HTTP on that host: port 3000)
Which Proxmox node? VMID 5700 is not fixed to one server—confirm before pct exec:
ssh root@192.168.11.10 'pct list | grep 5700'
ssh root@192.168.11.11 'pct list | grep 5700'
ssh root@192.168.11.12 'pct list | grep 5700'
Use the node where 5700 is running (often r630-02 / 192.168.11.12).
Prerequisites
-
Registration token — Get from Gitea Admin → Actions → Runners:
-
Docker (optional but recommended) — For running jobs in isolated containers. Install on dev-vm if not present.
Install act_runner
Site-wide (admin API token, recommended)
From the proxmox repo root, with GITEA_TOKEN (admin) in root .env:
bash scripts/dev-vm/bootstrap-gitea-act-runner-site-wide.sh
This calls GET /api/v1/admin/runners/registration-token, registers act_runner on CT 5700 with label ubuntu-latest (daemon shows ubuntu-latest:host, which matches workflow runs-on: ubuntu-latest), installs systemd, and starts the service. To re-register (e.g. change labels), run with RUNNER_FORCE_REREGISTER=1.
Manual registration token
# From repo root; replace <proxmox> with the node that hosts 5700 (e.g. 192.168.11.12):
GITEA_RUNNER_REGISTRATION_TOKEN=<token> ssh root@<proxmox> "pct exec 5700 -- bash -s" < scripts/dev-vm/setup-act-runner.sh
Or SSH into dev-vm (192.168.11.59) and run manually:
cd /opt/act_runner
GITEA_RUNNER_REGISTRATION_TOKEN=<token> bash /path/to/setup-act-runner.sh
Instance URL for register: From inside dev-vm, Gitea is usually reachable as http://127.0.0.1:3000 (same host). The setup script defaults to http://192.168.11.59:3000; override if needed:
INSTANCE=http://127.0.0.1:3000 GITEA_RUNNER_REGISTRATION_TOKEN=<token> bash setup-act-runner.sh
Run as systemd service
Prefer the install script (writes the unit, enables and starts the service):
ssh root@<proxmox> "pct exec 5700 -- bash -s" < scripts/dev-vm/install-act-runner-systemd.sh
Optional: if Gitea is not on localhost from the runner’s view, set GITEA_ACTION_URL (must match a URL the runner can reach):
ssh root@<proxmox> "pct exec 5700 -- env GITEA_ACTION_URL=http://192.168.11.59:3000 bash -s" < scripts/dev-vm/install-act-runner-systemd.sh
Manual unit (equivalent): /etc/systemd/system/act-runner.service with Environment=GITEA_ACTION_URL=http://127.0.0.1:3000, then systemctl daemon-reload && systemctl enable --now act-runner.
Troubleshooting
| Symptom | Check |
|---|---|
| Jobs queued, never start | Gitea Admin → Actions → Runners: at least one runner online. Repo Settings → Enable Repository Actions. |
| “No matching runner” / label errors | Workflow runs-on: must match runner labels (e.g. ubuntu-latest). In Gitea, open the runner details and compare labels. |
| Runner exits / register errors | Ensure INSTANCE URL is reachable from the container (curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/). Re-register with a new token if the old one was rotated (remove .runner first, then run setup-act-runner.sh again). |
| Docker steps fail | Install Docker on dev-vm and ensure the act_runner user (or root) can run docker. |
| Binary but no service | If /opt/act_runner/act_runner exists but there is no /opt/act_runner/.runner, registration never completed—run setup-act-runner.sh with a token. If .runner exists but no unit, run install-act-runner-systemd.sh. |
Enable Actions per repository
Repositories must enable Actions: Repository → Settings → Enable Repository Actions