emil
5b05db4e6d
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
109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```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).
|
|
|
|
#### 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:
|
|
|
|
1. **`.runner` registration file** exists and contains valid JSON (proves successful registration)
|
|
2. **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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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 |
|