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.9 KiB

Raw Blame History

Development Setup

Project Structure

.
├── src/gitea_runner_manager/      # Python CLI source
│   ├── cli.py                     # Click commands
│   ├── runner_manager.py          # Ansible orchestration + registry integration
│   ├── executor.py                # Ansible subprocess execution
│   ├── registry.py                # Local JSON runner registry
│   ├── i18n.py                    # Translations (en, bg, de, ru, zh)
│   └── 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
│   ├── start-runner.yml           # Start playbook
│   ├── stop-runner.yml            # Stop playbook
│   ├── enable-runner.yml          # Enable playbook
│   ├── disable-runner.yml         # Disable playbook
│   ├── status-runner.yml          # Status playbook
│   └── remove-runner.yml          # Remove playbook
├── tests/
│   ├── unit/                      # Unit tests
│   └── integration/               # Integration tests
├── Makefile                       # Build & test automation
└── pyproject.toml                # Python project metadata

Setup Development Environment

make setup        # Creates venv, installs deps, sets up hooks
source .venv/bin/activate

The make setup target (from the Makefile):

Verifies Python 3.12+ is installed
Creates a virtualenv in .venv
Installs/updates pip, setuptools, and wheel
Creates .env from .env.example if not present
Generates shell activation scripts (activate.sh, activate.fish, activate.zsh)
Installs checkmake via scripts/install_checkmake.py
Runs scripts/setup.sh to install dependencies and hooks

Developer Quick Start

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.

Running Linters

make lint          # Python (ruff + pyright + bandit)
make lint-bandit   # Security scan only
make ansible-lint  # Ansible
make makefile-lint # Makefile

The full lint target (make lint-all) runs all of the above:

make lint-all       # ruff + pyright + bandit + ansible-lint + checkmake

Individual lint targets from the Makefile:

Target	Description
`lint-ruff`	`ruff check src/ tests/`
`lint-format`	`ruff format --check src/ tests/`
`typecheck`	`pyright`
`lint-bandit`	`bandit -r src/ scripts/`
`ansible-lint`	`ansible-lint ansible/`
`makefile-lint`	`checkmake Makefile`
`lint`	ruff + format check + pyright + bandit
`lint-all`	lint + ansible-lint + makefile-lint

3.9 KiB Raw Blame History