113 lines
5.1 KiB
Markdown
113 lines
5.1 KiB
Markdown
# Home Assistant Add-on: Gitea act_runner
|
|
|
|
![Supports amd64 Architecture][amd64-shield]
|
|
![Supports aarch64 Architecture][aarch64-shield]
|
|
|
|
This add-on runs the **[Gitea Actions runner](https://gitea.com/gitea/act_runner)** natively on your Home Assistant machine, perfect for:
|
|
|
|
- Running CI/CD pipelines defined in your Gitea repositories
|
|
- Building and testing software directly on your home server
|
|
- Executing Docker-based job containers without a separate runner host
|
|
|
|
It self-registers to your Gitea instance on first boot, persists the registration across restarts, and is fully configurable from the HA add-on UI.
|
|
|
|
## ⚙️ Configuration
|
|
|
|
```yaml
|
|
gitea_url: "http://192.168.1.50:3000"
|
|
runner_token: "your-registration-token"
|
|
runner_name: "haos-runner"
|
|
runner_labels: "ubuntu-latest:docker://catthehacker/ubuntu:act-22.04"
|
|
log_level: "info"
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Variable | Default | Description |
|
|
|-----------------|-----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
|
|
| `gitea_url` | *(required)* | Full URL of your Gitea instance. **Must be a LAN IP**, not `localhost`. |
|
|
| `runner_token` | *(required)* | Registration token from Gitea → Site Admin → Actions → Runners → Create new runner. |
|
|
| `runner_name` | `haos-runner` | Display name shown in the Gitea runner list. |
|
|
| `runner_labels` | `ubuntu-latest:docker://catthehacker/ubuntu:act-22.04` | Comma-separated `<label>:docker://<image>` pairs. Must match the `runs-on:` in your workflows. |
|
|
| `log_level` | `info` | Verbosity level: `debug`, `info`, `warn`, or `error`. |
|
|
|
|
## 🚀 Installation
|
|
|
|
1. Go to Home Assistant → **Settings → Add-ons → Add-on Store**
|
|
2. Click **⋮ → Repositories** and add: `https://github.com/martemme/HomeAssistantAddons`
|
|
3. Find **Gitea act_runner**, install it
|
|
4. Fill in `gitea_url` and `runner_token` in the **Configuration** tab
|
|
5. Start the add-on
|
|
|
|
## 🏃 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** and copy the token
|
|
|
|
> Tokens can also be scoped to an organisation or a single repository via the respective *Settings → Actions → Runners* page.
|
|
|
|
## 🔖 Runner Labels Format
|
|
|
|
Labels map a workflow `runs-on:` value to a Docker image:
|
|
|
|
```
|
|
<label>:docker://<image>
|
|
```
|
|
|
|
Multiple labels are comma-separated:
|
|
|
|
```
|
|
ubuntu-latest:docker://catthehacker/ubuntu:act-22.04,ubuntu-20.04:docker://catthehacker/ubuntu:act-20.04
|
|
```
|
|
|
|
## 📂 Repository Structure
|
|
|
|
```
|
|
gitea-act-runner/
|
|
├── config.yaml # Add-on definition
|
|
├── Dockerfile # Extends gitea/act_runner:latest
|
|
├── run.sh # Startup & registration script
|
|
├── README.md
|
|
└── DOCS.md
|
|
```
|
|
|
|
## 🧾 Requirements
|
|
|
|
- Home Assistant OS or Supervised
|
|
- A running Gitea instance (≥ 1.21) with Actions enabled
|
|
- Supported architecture: `amd64`, `aarch64`
|
|
|
|
## 🔒 Security — Why `full_access: true`?
|
|
|
|
`full_access: true` mounts `/var/run/docker.sock` inside the container so `act_runner` can spawn and manage job containers on the host Docker daemon. Without it, every CI job fails with *"Cannot connect to the Docker daemon"*.
|
|
|
|
> ⚠️ Only install this add-on if you trust the Gitea instance and the workflow definitions it will run.
|
|
|
|
## 🛠 Troubleshooting
|
|
|
|
| Symptom | Fix |
|
|
|---|---|
|
|
| Runner shows **Offline** in Gitea | Use the LAN IP in `gitea_url`, not `localhost` |
|
|
| Jobs fail with *"Cannot connect to Docker"* | Confirm `full_access: true` is present in config and restart |
|
|
| Runner registers but jobs stay **Waiting** | Check that `runner_labels` matches the workflow `runs-on:` value |
|
|
| Need more detail in logs | Set `log_level` to `debug` and restart |
|
|
|
|
## Changelog & Releases
|
|
|
|
Releases are based on [Semantic Versioning][semver], and use the format
|
|
of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented
|
|
based on the following:
|
|
|
|
- `MAJOR`: Incompatible or major changes.
|
|
- `MINOR`: Backwards-compatible new features and enhancements.
|
|
- `PATCH`: Backwards-compatible bugfixes and package updates.
|
|
|
|
---
|
|
|
|
[semver]: http://semver.org/spec/v2.0.0.html
|
|
[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
|
|
[amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg
|
|
[repository-badge]: https://img.shields.io/badge/Add%20repository%20to%20my-Home%20Assistant-41BDF5?logo=home-assistant&style=for-the-badge
|
|
[repository-url]: https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fmartemme%2FHomeAssistantAddons
|