103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# 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`:
|
||
|
||
```bash
|
||
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
|
||
|
||
1. **Registration token** — Get from Gitea Admin → Actions → Runners:
|
||
- https://gitea.d-bis.org/-/admin/actions/runners
|
||
- Or org-level: https://gitea.d-bis.org/d-bis/settings/actions/runners
|
||
|
||
2. **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
|
||
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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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
|
||
|
||
---
|
||
|
||
## References
|
||
|
||
- [Gitea Actions Quick Start](https://docs.gitea.com/usage/actions/quickstart)
|
||
- [act_runner](https://gitea.com/gitea/act_runner)
|