HomeAssistantAddons/gitea-act-runner

Home Assistant Add-on: Gitea act_runner

This add-on runs the Gitea Actions 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

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, 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.