Files

T

emil 5b05db4e6d GRM-36: feat: implement documentation-as-code with wiki sync and doc-coverage

Add /docs/ directory with user and technical documentation extracted from README, AGENTS.md, and source code. Add scripts/sync_wiki.py to sync docs to Gitea wiki via API. Add scripts/doc_coverage.py to check CLI commands, modules, and CI scripts are documented. Add sync-wiki.yml workflow for auto-sync on merge and release. Slim down README.md to lean entry point. 28 new unit tests, 100% coverage maintained.

Closes GRM-36

2026-06-21 19:45:34 +00:00

3.1 KiB

Raw Blame History

Getting Started

Developer Setup

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

Configure Gitea Credentials

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).

Admin API Token (optional)

Set GITEA_ADMIN_TOKEN to enable informational API checks during integration test. This is optional — the test primarily verifies the runner by checking:

.runner registration file exists and contains valid JSON (proves successful registration)
Systemd user service is active (proves daemon is polling for jobs)

API checks, if enabled, are purely informational and do not affect pass/fail.

Install a Runner

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.

Using Make:

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

Verify Runner

The installer performs an automated integration test that verifies:

.runner file exists with valid JSON containing id, uuid, token, address — this proves successful registration with Gitea
Systemd user service is active — this proves the daemon is polling for jobs

You can also check the Gitea UI under Actions → Runners to confirm the runner appears as Online.

Optional: If GITEA_ADMIN_TOKEN is set, the installer will also query the Gitea API and report whether the runner appears in the admin or repo runners list. This is purely informational.

View Logs

GRM application logs (Python CLI output):

# Application log file (all messages including DEBUG)
cat ~/.local/state/grm/logs/grm.log

# Enable debug logging in the current session
GRM_LOG_LEVEL=DEBUG grm install 192.168.1.10 --user ubuntu --name prod-runner

Runner logs (on the remote host):

# Runner logs (via systemd user service)
sudo -u grm-<name> journalctl --user -u gitea-runner -f

The GRM application writes to two destinations:

Destination	Level	Content
Console (stdout)	`GRM_LOG_LEVEL` (default: INFO)	Colorised user-facing messages and operation reports
`~/.local/state/grm/logs/grm.log`	DEBUG	All messages with timestamps and severity

Set GRM_LOG_LEVEL to one of DEBUG, INFO, WARNING, ERROR, or CRITICAL to control console verbosity. The log file always captures everything at DEBUG level regardless of the console setting.

Console output is automatically colorised via click.echo: operation headers in bright cyan, completed steps in green, failures in red, and status updates in yellow.

3.1 KiB Raw Blame History