HomeAssistantAddons/gitea-act-runner/DOCS.md

Gitea act_runner

Runs the Gitea Actions runner on your Home Assistant machine.
The runner self-registers on first boot and persists its state across restarts.

Setup

1. Get a registration token: Gitea → Site Admin → Actions → Runners → Create new runner
2. Set gitea_url to your Gitea LAN IP, e.g. http://192.168.1.50:3000 — not localhost
3. Paste the token into runner_token
4. Start the add-on

Runner Labels

Labels map a workflow runs-on: value to a Docker image:

ubuntu-latest:docker://catthehacker/ubuntu:act-22.04

Multiple labels are comma-separated.

Persistent State

.runner is stored in /data/ and survives restarts — the runner will not re-register on every boot.
To force re-registration: stop the add-on, delete /data/.runner, update the token, and restart.

Troubleshooting

Symptom	Fix
Runner Offline in Gitea	Use the LAN IP in gitea_url, not localhost
Jobs fail with "Cannot connect to Docker"	Ensure full_access: true is set and restart
Jobs stay Waiting	Check runner_labels matches the workflow runs-on: value
Need more detail	Set log_level: debug and restart

Full documentation: README.md