244 lines
8.6 KiB
Markdown
244 lines
8.6 KiB
Markdown
# 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.
|
|
|
|
By default, runners are deployed as **Docker containers** using the official `gitea/runner` image. A traditional **binary** deployment mode is also available.
|
|
|
|
> **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
|
|
|
|
## Prerequisites
|
|
|
|
- **SSH key authentication** — The remote host must be reachable via SSH using the user specified with `--user` and the private key specified with `--key`. GRM uses Ansible under the hood, which connects to the target host over SSH to execute all installation and configuration tasks. Without valid SSH credentials, Ansible cannot establish a connection and the deployment will fail.
|
|
- **Sudo privileges** — The specified user must have passwordless or password-prompted (`--ask-become-pass`) sudo access on the remote host. Runner installation requires root privileges for tasks such as installing packages, creating systemd services, and managing Docker.
|
|
|
|
## Quick Start
|
|
|
|
### Developer Setup
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env:
|
|
# GITEA_URL=https://git.example.com
|
|
# GITEA_REGISTRATION_TOKEN=your-registration-token
|
|
```
|
|
|
|
`GITEA_REGISTRATION_TOKEN` is the runner registration token obtained from your Gitea instance (Admin → Actions → Runners → Create Registration Token).
|
|
|
|
### Install a Runner
|
|
|
|
Using the CLI:
|
|
|
|
```bash
|
|
# Docker mode (default) — deploys gitea_runner as a container
|
|
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner
|
|
|
|
# Binary mode — downloads and installs the gitea_runner binary with systemd
|
|
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner --mode binary
|
|
```
|
|
|
|
If the remote user requires a sudo password:
|
|
|
|
```bash
|
|
grm install 192.168.1.10 --user ubuntu --ask-become-pass
|
|
```
|
|
|
|
Using Make:
|
|
|
|
```bash
|
|
# Docker mode (default)
|
|
make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner
|
|
|
|
# Binary mode
|
|
make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner MODE=binary
|
|
|
|
# With sudo password prompt:
|
|
make install HOST=192.168.1.10 USER=ubuntu ASK_BECOME_PASS=1
|
|
```
|
|
|
|
### Verify Runner
|
|
|
|
Check Gitea admin UI under **Actions → Runners**. The runner should appear as **Online**.
|
|
|
|
### View Logs
|
|
|
|
```bash
|
|
# Binary mode logs
|
|
sudo journalctl -u gitea-runner-<name> -f
|
|
|
|
# Docker mode logs
|
|
docker logs gitea-runner-<name> -f
|
|
```
|
|
|
|
## Architecture
|
|
|
|
GRM consists of two layers:
|
|
|
|
1. **Python CLI** (`src/gitea_runner_manager/`) — built with Click, handles argument parsing, environment loading, and delegates to Ansible via the `ansible-playbook` subprocess.
|
|
2. **Ansible Role** (`ansible/roles/gitea-runner/`) — idempotent role that installs Docker, configures the runner (binary or container), creates systemd services, and registers the runner with Gitea.
|
|
|
|
```
|
|
grm install <host>
|
|
└── RunnerManager.install()
|
|
└── ansible-playbook ansible/install-runner.yml
|
|
└── role: gitea-runner
|
|
├── docker.yml (Docker installation)
|
|
├── docker_mode.yml (container deployment)
|
|
├── binary_mode.yml (binary + systemd deployment)
|
|
├── prune.yml (Docker prune timer)
|
|
└── integration_test.yml (validate online status)
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All tunable values are exposed as Ansible variables in `ansible/roles/gitea-runner/defaults/main.yml`:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `runner_mode` | `docker` | Deployment mode: `docker` or `binary` |
|
|
| `gitea_runner_version` | `1.0.8` | Docker image tag / binary version |
|
|
| `gitea_runner_docker_image` | `gitea/runner` | Docker image name |
|
|
| `runner_labels` | `ubuntu-latest:docker://runner-images:ubuntu-22.04` | Runner labels |
|
|
| `skip_runner_registration` | `false` | Skip API registration (useful for tests) |
|
|
| `gitea_runner_data_dir` | `/var/lib/gitea-runner` | Runtime data directory |
|
|
| `gitea_runner_config_dir` | `/etc/gitea-runner` | Config directory (binary mode) |
|
|
| `gitea_runner_binary_path` | `/usr/local/bin/gitea_runner` | Binary install path |
|
|
| `gitea_runner_prune_until` | `24h` | Prune resources older than this |
|
|
| `gitea_runner_prune_schedule` | `daily` | systemd timer schedule |
|
|
| `gitea_runner_prune_label` | `gitea-runner=true` | Docker label for pruning |
|
|
| `gitea_runner_service_restart_sec` | `5` | systemd RestartSec value |
|
|
| `gitea_runner_service_user` | `{{ ansible_user \| default('root') }}` | Service user |
|
|
| `gitea_runner_log_level` | `info` | Runner log level |
|
|
| `gitea_runner_container_label` | `gitea-runner=true` | Container label |
|
|
| `docker_gpg_key_path` | `/etc/apt/keyrings/docker.asc` | Docker GPG key path |
|
|
|
|
Override any variable by passing it to the CLI with `--extra-vars` or by setting it in your Ansible inventory.
|
|
|
|
## Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
.
|
|
├── src/gitea_runner_manager/ # Python CLI source
|
|
│ ├── cli.py # Click commands
|
|
│ ├── runner_manager.py # Ansible orchestration
|
|
│ └── exceptions.py # Custom exceptions
|
|
├── ansible/
|
|
│ ├── roles/gitea-runner/ # Main Ansible role
|
|
│ │ ├── defaults/main.yml # Default variables
|
|
│ │ ├── tasks/ # Task files
|
|
│ │ ├── templates/ # Jinja2 templates
|
|
│ │ └── molecule/ # Test scenarios
|
|
│ ├── install-runner.yml # Install playbook
|
|
│ └── update-runner.yml # Update playbook
|
|
├── tests/ # Unit tests
|
|
├── Makefile # Build & test automation
|
|
└── pyproject.toml # Python project metadata
|
|
```
|
|
|
|
### Setup Development Environment
|
|
|
|
```bash
|
|
make setup # Creates venv, installs deps, sets up hooks
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
### Running Linters
|
|
|
|
```bash
|
|
make lint # Python (ruff + pyright)
|
|
make ansible-lint # Ansible
|
|
make makefile-lint # Makefile
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
|
|
```bash
|
|
make test-unit
|
|
```
|
|
|
|
Runs pytest with 100% coverage requirement.
|
|
|
|
### Molecule Tests
|
|
|
|
```bash
|
|
make molecule
|
|
```
|
|
|
|
Runs two scenarios:
|
|
|
|
- **default** — Docker mode installation in an Ubuntu 22.04 container
|
|
- **binary** — Binary mode installation in an Ubuntu 22.04 container
|
|
|
|
Both scenarios test idempotence (second run produces zero changes).
|
|
|
|
### Full Test Suite
|
|
|
|
```bash
|
|
make test-all # Runs unit tests + linters + molecule
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Event loop is closed" warning
|
|
|
|
This is a harmless cleanup traceback from Molecule's Docker driver when the test process is interrupted. It does not indicate a test failure.
|
|
|
|
### Runner appears offline after installation
|
|
|
|
- Check that the `GITEA_URL` and `GITEA_REGISTRATION_TOKEN` environment variables are correct.
|
|
- Verify the runner container or service is running: `docker ps` or `systemctl status gitea-runner-<name>`.
|
|
- Check logs for registration errors.
|
|
|
|
### Docker mode: container won't start
|
|
|
|
- Ensure Docker is installed and running on the host.
|
|
- Verify the Docker socket is accessible: `docker version`.
|
|
|
|
### Binary mode: systemd service fails
|
|
|
|
- Check the service status: `systemctl status gitea-runner-<name>`.
|
|
- Verify the binary exists at `gitea_runner_binary_path`.
|
|
- Ensure the service user is in the `docker` group.
|
|
|
|
## Makefile Targets
|
|
|
|
| Target | Description |
|
|
|--------|-------------|
|
|
| `setup` | Full environment setup |
|
|
| `install` | Installs a runner on a host (`MODE=docker` or `binary`) |
|
|
| `update` | Updates a runner on a host (`MODE=docker` or `binary`) |
|
|
| `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 |