proxmox/docs/04-configuration/GITEA_ACT_RUNNER_SETUP.md

Gitea act_runner Setup

Last Updated: 2026-05-11
Gitea: https://gitea.d-bis.org

Runner layout (two pools)

CT (VMID)	Hostname	Labels	Use
5700	dev-vm	ubuntu-latest-heavy	Heavy monorepo CI (pnpm, run-all-validation) — proxmox workflows use runs-on: ubuntu-latest-heavy.
5701	gitea-runner-1	ubuntu-latest, ubuntu-22.04, ubuntu-20.04	Default pool for other repos / lighter workflows that keep runs-on: ubuntu-latest.

Both CTs live on r630-04 (192.168.11.14) as of live inventory; confirm before pct exec:

ssh root@192.168.11.14 'pct list | grep -E "5700|5701"'

Gitea HTTP on dev-vm: 192.168.11.59:3000 (from CT 5700, same host as Gitea when Actions hit the LAN URL).

---

Config templates (repo)

Canonical act_runner YAML (Docker limits, fetch_interval, labels):

• config/gitea-act-runner/config-5700-heavy.yaml
• config/gitea-act-runner/config-5701-standard.yaml

Deploy to both CTs and restart daemons (LAN, repo root):

bash scripts/dev-vm/apply-act-runner-config.sh

Job containers use privileged: false. container.network must be empty (per-job Docker network) so workflow services: (Postgres, etc.) resolve; network: bridge isolates the job from service containers (Prisma P1001). Resource caps: 5700 4 CPU / 10 GiB RAM; 5701 2 CPU / 4 GiB RAM (container.options).

---

Register or re-register runners

Requires GITEA_TOKEN (admin) in repo root `.env**.

Heavy pool (5700)

Default labels: ubuntu-latest-heavy:docker://docker.gitea.com/runner-images:ubuntu-latest

bash scripts/dev-vm/bootstrap-gitea-act-runner-site-wide.sh

To pick up new labels after changing Docker image tokens in Gitea:

RUNNER_FORCE_REREGISTER=1 bash scripts/dev-vm/bootstrap-gitea-act-runner-site-wide.sh

Standard pool (5701)

Registers ubuntu-latest + ubuntu-22.04 + ubuntu-20.04 against http://IP_DEV_VM:3000:

bash scripts/dev-vm/bootstrap-gitea-act-runner-secondary-lan.sh

Re-register:

RUNNER_FORCE_REREGISTER=1 bash scripts/dev-vm/bootstrap-gitea-act-runner-secondary-lan.sh

Low-level script (custom VMID / labels / instance URL):

export DEV_VM_VMID=5701
export GITEA_RUNNER_INSTANCE='http://192.168.11.59:3000'
export RUNNER_LABELS='ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest'
bash scripts/dev-vm/bootstrap-gitea-act-runner.sh

After RUNNER_FORCE_REREGISTER=1, Gitea may show an old offline runner — remove the stale entry under Admin → Actions → Runners if desired.

---

Systemd unit

The unit passes act_runner daemon -c /etc/act_runner/config.yaml. Install or refresh:

ssh root@192.168.11.14 "pct exec 5700 -- env GITEA_ACTION_URL=http://127.0.0.1:3000 bash -s" < scripts/dev-vm/install-act-runner-systemd.sh
ssh root@192.168.11.14 "pct exec 5701 -- env GITEA_ACTION_URL=http://192.168.11.59:3000 bash -s" < scripts/dev-vm/install-act-runner-systemd.sh

---

Workflows in d-bis/proxmox

Canonical validation/deploy workflows use runs-on: ubuntu-latest-heavy so jobs land on 5700. Submodule copies under this repo (explorer-monorepo, cross-chain-pmm-lps, OMNIS) keep ubuntu-latest so they prefer the 5701 pool.

---

Cache

Both runners keep built-in Actions cache enabled. If job logs show connect ETIMEDOUT to the cache port, set cache.host to the runner’s LAN IP (reachable from job containers) and cache.port to a fixed port; publish that port on the host if the runner is itself containerized (see Gitea act_runner cache).

Optional: point cache.external_server at a shared cache URL in both YAML files so npm layers dedupe across runners (requires a reachable cache service).

---

Monitoring (per-runner CPU)

Host loadavg inside LXCs tracks the Proxmox node, not the CT — do not use it to compare 5700 vs 5701. While jobs run, prefer docker stats on the runner CT:

bash scripts/dev-vm/act-runner-resource-snapshot.sh

---

Troubleshooting

Symptom	Check
Jobs queued, never start	Admin → Actions → Runners: at least one runner online with a label matching runs-on. Repo Settings → Actions enabled.
“No matching runner”	Workflow runs-on must match a label on an online runner (ubuntu-latest-heavy vs ubuntu-latest).
Old offline duplicate runners after re-register	Delete via Admin API or: bash scripts/dev-vm/delete-offline-gitea-actions-runners.sh --dry-run then --apply (needs GITEA_TOKEN). Not removable by SSH alone — Gitea stores runner rows in its DB.
Runner exits / register errors	curl from the CT to GITEA_RUNNER_INSTANCE. Re-register with a fresh admin token after RUNNER_FORCE_REREGISTER=1.
Docker steps fail	Docker installed on the CT; act_runner runs as root in the default unit.
Prisma P1001 / “Can't reach … postgres:5432” with services: postgres	Repo DATABASE_URL must use host postgres (not localhost). On runners, container.network in /etc/act_runner/config.yaml must be empty (""), not bridge. Apply: bash scripts/dev-vm/apply-act-runner-config.sh.

---

References

• Gitea Actions Quick Start
• act_runner