68 lines
5.4 KiB
Markdown
68 lines
5.4 KiB
Markdown
# 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).
|
|
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
|
|
[](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
|
|
[](https://www.python.org/downloads/)
|
|
|
|
## 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](Getting-Started) — Installation, quick start, token setup, first run, log viewing
|
|
- [Installation](Installation) — Prerequisites, setup methods, multiple instances, runner registry
|
|
- [CLI Commands](CLI-Commands) — All commands with arguments, options, and examples
|
|
- [Troubleshooting](Troubleshooting) — Common issues, diagnostics, and solutions
|
|
- [FAQ](FAQ) — Frequently asked questions
|
|
|
|
## Technical Documentation
|
|
|
|
- [Architecture](Architecture) — High-level design, component diagram, data flow, security model, per-runner isolation
|
|
- [Development Setup](Development-Setup) — Environment setup, project structure, dependencies, linting, testing
|
|
- [CI/CD Workflow](CI-CD-Workflow) — PR workflow, branch protection, release pipeline, change classification, badge generation
|
|
- [Testing Strategy](Testing-Strategy) — Unit tests, Molecule scenarios, integration tests, CI distribution
|
|
- [Decision Log](Decision-Log) — Key technical decisions and rationale (ADRs)
|
|
- [Contributing Guide](Contributing-Guide) — Coding standards, PR workflow, commit conventions, Ansible role conventions
|
|
|
|
## Quick Links
|
|
|
|
- [Repository](https://git.oblachno.oblachno.fyi/oblachno-oss/grm)
|
|
- [Releases](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
|
|
- [Issues](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/issues)
|
|
- [CI/CD Pipeline](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
|
|
- [Changelog](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/CHANGELOG.md)
|
|
- [License (GPL-3.0)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
|