martin/HomeAssistantAddons
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(gitea): add README and CHANGELOG for Gitea act_runner add-on

Browse Source
This commit is contained in:
Martin Tahiraj
2026-04-02 09:45:05 +02:00
parent dc68562bbd
commit bc2fbe7f5b
4 changed files with 146 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
gitea-act-runner/DOCS.md
View File

@@ -1,88 +1,37 @@
# Gitea act_runner — Home Assistant Addon
# Gitea act_runner
Runs the [Gitea Actions runner](https://gitea.com/gitea/act_runner) as a native Home Assistant addon, allowing your HAOS machine to execute Gitea CI/CD jobs.
Runs the Gitea Actions runner on your Home Assistant machine.
The runner self-registers on first boot and persists its state across restarts.
---
## Setup
## Prerequisites
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
1. A running **Gitea instance** (version ≥ 1.21) with Actions enabled.
In Gitea: **Site Administration → Configuration** — confirm `[actions] ENABLED = true`.
2. A **runner registration token** from your Gitea instance (see below).
3. The Gitea instance must be reachable from your HA machine by a **LAN IP address** (e.g. `http://192.168.1.50:3000`), not `localhost`.
## Runner Labels
---
## Getting the Registration Token
1. Log in to Gitea as a **site administrator**.
2. Navigate to **Site Administration → Actions → Runners**.
3. Click **Create new runner**.
4. Copy the displayed registration token — you will paste it into the addon options.
> **Tip:** Tokens can also be scoped to an organisation or a single repository via the respective *Settings → Actions → Runners* page if you don't want a global runner.
---
## Configuration Options
| Option | Required | Default | Description |
|---|---|---|---|
| `gitea_url` | ✅ | — | Full URL of your Gitea instance, e.g. `http://192.168.1.50:3000` |
| `runner_token` | ✅ | — | Registration token from the Gitea Runners page |
| `runner_name` | | `haos-runner` | Display name shown in Gitea's runner list |
| `runner_labels` | | `ubuntu-latest:docker://catthehacker/ubuntu:act-22.04` | Comma-separated list of labels this runner accepts |
| `log_level` | | `info` | Verbosity: `debug`, `info`, `warn`, or `error` |
---
## Runner Labels Format
Labels tell Gitea which job `runs-on:` values this runner handles, and which Docker image to use for each:
```
<label>:docker://<image>
```
**Examples:**
Labels map a workflow `runs-on:` value to a Docker image:
```
ubuntu-latest:docker://catthehacker/ubuntu:act-22.04
ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04,ubuntu-20.04:docker://catthehacker/ubuntu:act-20.04
```
The label on the left must match the `runs-on:` string in your workflow YAML. Multiple labels are comma-separated.
---
## Why `full_access: true`?
`full_access: true` in the addon manifest mounts `/var/run/docker.sock` inside the container. This is required so `act_runner` can communicate with the host Docker daemon to **spawn and manage job containers** for each CI run.
Without this, the runner starts but will fail every job that uses a `container:` or `docker://` image.
> ⚠️ This grants the addon broad access to the host Docker daemon. Only install this addon if you trust the Gitea instance and the workflow definitions it will run.
---
Multiple labels are comma-separated.
## Persistent State
The runner's registration file (`.runner`) and the generated runtime config are stored in `/data/` inside the addon, which is **persisted across restarts and updates**. The runner will **not** re-register on every boot.
To force re-registration (e.g. if the token is revoked):
1. Stop the addon.
2. SSH into HAOS and delete `/data/addon_configs/gitea_act_runner/.runner` (exact path may vary).
3. Update the `runner_token` option with a new token.
4. Start the addon.
---
`.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 | Likely cause | Fix |
|---|---|---|
| Runner shows **Offline** in Gitea immediately | `gitea_url` uses `localhost` or `127.0.0.1` | Use the LAN IP of the Gitea machine |
| `[ERROR] runner_token is not configured` | Token field is blank | Paste the token from Gitea Runners page |
| Jobs fail with *"Cannot connect to the Docker daemon"* | `full_access` not effective | Verify the addon config has `full_access: true` and restart |
| Runner registers but jobs stay **Waiting** | Labels mismatch | Ensure workflow `runs-on:` matches a label configured in `runner_labels` |
| Want more detail in logs | — | Set `log_level` to `debug` and restart |
| 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](https://github.com/martemme/HomeAssistantAddons/tree/main/gitea-act-runner)