feat(gitea): add README and CHANGELOG for Gitea act_runner add-on
This commit is contained in:
Martin Tahiraj
10
gitea-act-runner/CHANGELOG.md
Normal file
10
gitea-act-runner/CHANGELOG.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# Changelog
|
||||
|
||||
## 1.0.0 - 2026-04-01
|
||||
|
||||
- Initial release
|
||||
- Self-registers to Gitea on first boot using options from HA supervisor
|
||||
- Persists `.runner` registration file in `/data/` across restarts
|
||||
- Generates `act_runner_config.yaml` at runtime from configured options
|
||||
- Docker socket access via `full_access: true` for job container spawning
|
||||
- Configurable: `gitea_url`, `runner_token`, `runner_name`, `runner_labels`, `log_level`
|
||||
@@ -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)
|
||||
|
||||
113
gitea-act-runner/README.md
Normal file
113
gitea-act-runner/README.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
Made with ❤️ for automation and resilience.
|
||||
|
||||
[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
|
||||
@@ -21,8 +21,8 @@ build_from:
|
||||
aarch64: "gitea/act_runner:latest"
|
||||
|
||||
options:
|
||||
gitea_url: ""
|
||||
runner_token: ""
|
||||
gitea_url: "http://192.168.1.x:3000"
|
||||
runner_token: "paste-your-registration-token-here"
|
||||
runner_name: "haos-runner"
|
||||
runner_labels: "ubuntu-latest:docker://catthehacker/ubuntu:act-22.04"
|
||||
log_level: "info"
|
||||
|
||||
Reference in New Issue
Block a user