AGENTS.md — Project Conventions for GRM

Build & Test Commands

make setup          # Create venv, install deps, set up hooks
make lint-all       # ruff + pyright + bandit + ansible-lint + checkmake
make pytest-cov     # Unit tests with 100% coverage enforcement
make test-unit      # Unit tests without coverage
make molecule       # All 6 scenarios on Ubuntu 22.04
make molecule-all   # All 6 scenarios on all 4 supported OSes
make test-all       # pytest-cov + molecule

Architecture

Python CLI (src/gitea_runner_manager/) — Click-based CLI that delegates to Ansible
Ansible Role (ansible/roles/gitea-runner/) — Idempotent role for rootless Docker runner setup
CI Scripts (scripts/) — Automation for auto-merge, post-merge, publishing, molecule distribution

Key Conventions

Python 3.12+ required (ruff/pyright target py312)
100% test coverage required (--cov-fail-under=100)
Conventional commits on feature branches (no GRM-N: prefix)
GRM-N: prefix on master branch (added by auto-merge)
Branch names must include GRM-N task ID
Line length: 120 chars
Secrets are passed via temp JSON files, never on the command line (CWE-214)

Ansible Role Structure

main.yml → systemd_check → user_setup → rootless_docker → install_runner → prune → integration_test

install_runner.yml handles: download, config, validate, register, service
main.yml handles: prune, integration_test (NOT install_runner — avoids duplicates)
All systemctl --user tasks must be guarded by docker_rootless_setup
All template creation tasks must be guarded by docker_rootless_setup

Molecule Scenarios

6 scenarios: default, multi-instance, lifecycle, template-content, deregister, update 4 platforms: ubuntu-2204, ubuntu-2404, debian-12, archlinux Platform list is defined in scripts/distribute_molecule.py (single source of truth)

Known Issues

ansible-lint may warn about command-instead-of-module for systemctl --user calls — this is expected (systemd module doesn't support user services) and skipped in .ansible-lint
Molecule Docker driver may print "Event loop is closed" warnings on interrupt — harmless

2.2 KiB Raw Blame History