# 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 |