Installation

Before you start: Make sure you have cloned the repo and checked out the latest stable release tag. See Getting Started for setup instructions. Do not run from master — it may contain unreleased changes.

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 access — GRM requires root privileges on the remote host to create system users, install packages, and configure rootless Docker. By default, you will be prompted interactively for the sudo password. For automation or uninterrupted workflows, configure passwordless sudo on the remote host and pass --no-ask-become-pass.
Gitea registration token — You need a runner registration token from your Gitea instance. See Getting Started for detailed instructions on obtaining tokens.

Supported Operating Systems

Arch Linux
Ubuntu 22.04 / 24.04
Debian 12

All supported OSes are tested in CI via molecule scenarios on every PR.

Quick Start Install

Using the CLI (you will be prompted for the sudo password by default):

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

Automation tip: Configure passwordless sudo on the remote host and pass --no-ask-become-pass to skip the password prompt. This is recommended for CI/CD pipelines.

Make Install

Using Make:

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

Runner Registry

After installation, GRM stores each runner's connection details (host, user, SSH key, Gitea URL) in a local JSON registry at ~/.local/share/grm/runners.json. This means you rarely need to repeat connection arguments:

# List all registered runners with live systemd status
grm list

Multiple Instances on the Same Host

Each runner instance is fully isolated with its own system user, rootless Docker daemon, data directory, and systemd user service:

# Install two runners on the same host
grm install 192.168.1.10 --user ubuntu --name workflow-runner
grm install 192.168.1.10 --user ubuntu --name build-runner

# Manage them independently by name
grm stop workflow-runner
grm status build-runner

2.6 KiB Raw Blame History