# 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)