Gitea Runner Manager (GRM)

A lean command-line tool to automate the installation, configuration, and lifecycle management of Gitea Actions runners on Arch Linux, Ubuntu, and Debian hosts.

Pronunciation note: GRM is short for Gitea Runner Manager, but say it like ГРЪМ (roughly "GRUM" in Latin letters) — the Bulgarian word for thunder. Wherever there are clouds, there may be thunders. This is an open-source project from Oblachno (облачно means cloudy in Bulgarian).

Features

Simple and focused — no unnecessary features.
Secure — no hardcoded secrets, uses scoped tokens.
Idempotent — can be run multiple times safely.
Flexible — accepts a plain IP address or hostname, and allows specifying the SSH user and private key.

Supported Operating Systems

Arch Linux
Ubuntu 22.04 / 24.04 / 26.04
Debian 12 / 13

Quick Start

Developer Setup

git clone https://git.oblachno.oblachno.com/oblachno/gitea-runner-manager.git
cd gitea-runner-manager
pyenv install 3.11.11
pyenv local 3.11.11
make setup

Configure Gitea Credentials

cp .env.example .env
# Edit .env:
# GITEA_URL=https://git.example.com
# GITEA_TOKEN=your-personal-access-token

The token needs admin:runner scope.

Install a Runner

Using the CLI:

./grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner

Using Make:

make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner

Verify Runner

Check Gitea admin UI under Actions → Runners. The runner should appear as Online.

View Logs

sudo journalctl -u act-runner-<name> -f

Makefile Targets

Target	Description
`setup`	Full environment setup
`install`	Installs a runner on a host
`lint`	Runs Python linters
`ansible-lint`	Runs `ansible-lint`
`test-unit`	Runs unit tests with coverage
`molecule`	Runs Ansible Molecule tests
`test-all`	Runs all tests

License

GPL-3.0

2.0 KiB Raw Permalink Blame History