GRM — Gitea Runner Manager

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

Each runner runs in an isolated rootless Docker environment under a dedicated system user, enabling multiple runners to operate in parallel on the same host without conflicts. GRM handles the entire runner lifecycle — from initial installation and registration with Gitea, through start/stop/enable/disable operations, to clean removal with deregistration.

Pronunciation: GRM is short for Gitea Runner Manager, but say it like ГРЪМ (roughly "GRUM") — the Bulgarian word for thunder. An open-source project from Oblachno (облачно means cloudy in Bulgarian).

Overview

GRM is a two-layer tool: a Python CLI (built with Click) that delegates to an idempotent Ansible role for all remote operations. The CLI handles argument parsing, environment loading, internationalisation, and local registry management. The Ansible role handles the actual runner setup — creating dedicated system users, configuring rootless Docker, downloading and registering the runner binary, creating systemd user services, and setting up Docker prune timers.

Key capabilities

Rootless Docker isolation — Each runner gets its own rootless Docker daemon under a dedicated system user (grm-<name>).
Multi-instance support — Multiple isolated runners on the same host, each with independent users, data directories, and systemd services.
Full lifecycle CLI — install, update, start, stop, enable, disable, status, remove, list.
Idempotent Ansible role — Safe to re-run; second run produces zero changes.
Automatic integration testing — Every installation verifies the .runner registration file and systemd service state.
Local runner registry — Connection details stored locally; manage runners by name after installation.
Internationalisation — Console messages in English, Bulgarian, German, Russian, Chinese, and Polish.
Security-conscious — Secrets passed via temporary JSON files with 0600 permissions (CWE-214).

Supported operating systems

OS	Versions	Package manager
Arch Linux	rolling	pacman
Ubuntu	22.04, 24.04	apt
Debian	12	apt

All supported OSes are tested in CI via Molecule scenarios on every PR that changes Ansible files.

User Documentation

Getting Started — Installation, quick start, token setup, first run, log viewing
Installation — Prerequisites, setup methods, multiple instances, runner registry
CLI Commands — All commands with arguments, options, and examples
Troubleshooting — Common issues, diagnostics, and solutions
FAQ — Frequently asked questions

Technical Documentation

Architecture — High-level design, component diagram, data flow, security model, per-runner isolation
Development Setup — Environment setup, project structure, dependencies, linting, testing
CI/CD Workflow — PR workflow, branch protection, release pipeline, change classification, badge generation
Testing Strategy — Unit tests, Molecule scenarios, integration tests, CI distribution
Decision Log — Key technical decisions and rationale (ADRs)
Contributing Guide — Coding standards, PR workflow, commit conventions, Ansible role conventions

5.4 KiB Raw Blame History