224 lines
12 KiB
Markdown
224 lines
12 KiB
Markdown
# Anleitung: KI-Review für hsadmin-ng auf dev.hostsharing.net
|
||
|
||
Stand: 2026-10-05, nach dem Versuch auf git.javagil.de (siehe [betrieb-git.javagil.de.md](betrieb-git.javagil.de.md)).
|
||
Diese Anleitung ist noch nicht ausgeführt.
|
||
Was vor Ort zu prüfen ist, steht als „prüfen“ dabei.
|
||
|
||
## Ziel
|
||
|
||
Die Repositories `hostsharing/hs.hsadmin.ng` und das Frontend-Repository (Name prüfen) bekommen denselben KI-Review wie `mi/werkprobe`.
|
||
Unterschiede zum Versuch:
|
||
|
||
- Ein Frontier-Modell und höchstens 1 USD pro Review, weil es nur 2–3 PRs pro Tag gibt.
|
||
- Werkator läuft auf vm4006 mit rootless Docker statt Werkdock.
|
||
- Eigene Regeln für automatisch freigebbare Änderungen; Migrationen und RBAC bleiben YELLOW, bis das Team anders entscheidet.
|
||
|
||
## Zusammenspiel
|
||
|
||
So arbeiten die Systeme zusammen:
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
dev["Entwickler"] -- "push, PR ohne WIP" --> gitea
|
||
human["Mensch, z. B. mi"] -- "Approval bei YELLOW" --> gitea
|
||
subgraph gitea["Gitea"]
|
||
pr["Pull Request"]
|
||
bp{"Branch Protection"}
|
||
end
|
||
subgraph host["vm4006"]
|
||
werkator["Werkator"]
|
||
subgraph sandbox["Docker-Container, frisches Home"]
|
||
werkrevisor["werkrevisor"] --> pragent["PR-Agent"]
|
||
end
|
||
mcfg[("Maschinen-Konfiguration:<br/>Build ai-review, Secrets,<br/>WERKREVISOR_CONFIG_TOML")]
|
||
end
|
||
openrouter["OpenRouter"] --> llm["Sprachmodell"]
|
||
|
||
werkator -- "pollt neue Heads und offene PRs" --> pr
|
||
mcfg -. "Befehl, Umgebung" .-> werkator
|
||
werkator -- "CI-Build" --> ci["normaler Build"]
|
||
werkator -- "PR-Target-Build" --> werkrevisor
|
||
werkrevisor -- "liest PR, Diff, Dateien" --> pr
|
||
pragent -- "Prompt" --> openrouter
|
||
werkrevisor -- "Kommentar, Approval / Request changes /<br/>Review-Anfrage, ai-review/assessment" --> pr
|
||
werkator -- "Status werkator und ai-review/gate" --> pr
|
||
pr --> bp
|
||
bp -- "Merge erlaubt oder gesperrt" --> dev
|
||
```
|
||
|
||
## Voraussetzungen
|
||
|
||
| Was | Soll | prüfen |
|
||
| ----------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
|
||
| Gitea | 1.27.3 | erledigt: `GET https://dev.hostsharing.net/api/v1/version` |
|
||
| Werkator auf vm4006 | mindestens 1.36.0 | Fußzeile der Werkator-Oberfläche |
|
||
| Docker auf vm4006 | rootless, für den Werkator-Benutzer | `docker info` als dieser Benutzer |
|
||
| Gitea-Administrator | darf Konten anlegen | Menü „Site Administration“ |
|
||
| Werkator-Gitea-Token | in `.git/werkator/.werkator.yml` (`git.token`) | nötig, damit Werkator offene PRs liest |
|
||
|
||
## 1. Bot-Konto
|
||
|
||
1. In dev.hostsharing.net als Administrator das Konto `ai-reviewer` anlegen:
|
||
- lokal;
|
||
- Passwort im Passwort-Manager;
|
||
- „Max. Anzahl an Repositorys“ `0`;
|
||
- nicht Administrator, keine Organisationen.
|
||
2. In beiden Repositories `ai-reviewer` mit Recht „Schreiben“ eintragen.
|
||
Bei Organisations-Repositories geht das als Mitarbeiter oder über ein eigenes Team nur für diese beiden Repositories.
|
||
Ohne Schreibrecht zählt das Approval des Bots nicht als offiziell.
|
||
3. Als `ai-reviewer` den Token `pr-agent-bot` erzeugen:
|
||
- repository: Lesen und Schreiben;
|
||
- issue: Lesen und Schreiben;
|
||
- user: Lesen.
|
||
Ohne „user: Lesen“ kann werkrevisor seine eigenen Kommentare nicht erkennen.
|
||
|
||
## 2. OpenRouter-Key
|
||
|
||
Einen eigenen Key für Hostsharing anlegen, damit die Kosten getrennt bleiben, z. B. `hostsharing-review`.
|
||
Vorschlag für das Limit: 60 USD, monatlich zurückgesetzt; das reicht für etwa 60–90 Reviews bis 1 USD.
|
||
|
||
Für den Classifier Jev (ab werkrevisor 0.5.0, `[engine] mode` `classifier` oder `combined`) kommt ein TypeSafe-Key hinzu.
|
||
Er steht als `TYPESAFE_API_KEY` neben `OPENROUTER_API_KEY` in `docker.env`.
|
||
Mit dem Standard `mode = "llm"` ist er nicht nötig.
|
||
|
||
## 3. Modell und Betreiber-Konfiguration
|
||
|
||
Die Konfiguration steht in werkrevisor unter `config/hsadmin-ng.toml` und kommt ins Image; ein PR kann sie nicht ändern.
|
||
Vor der Aktivierung festzulegen:
|
||
|
||
- **Modell:** Kandidaten mit Preisen vom 2026-10-05 in USD pro 1 Mio. Tokens (Input / Output):
|
||
- `anthropic/claude-sonnet-5.5`: 2 / 10;
|
||
- `openai/gpt-6-astra`: 10 / 50.
|
||
Auswahl nach einem Offline-Vergleich (Schritt 6), nicht nach Gefühl.
|
||
- **Preise und Grenzen:**
|
||
- Die Preise des gewählten Modells gehören in `[model]`.
|
||
- `max_input_tokens` und `max_output_tokens` so wählen, dass `2 × (Input × Preis + Output × Preis)` höchstens 1 USD ergibt.
|
||
- **Kategorien:** `docs` = `doc/**`, `**/*.md`; `tests` = `src/test/**`; `main` = `src/main/**`; `api_spec` = `src/main/resources/api-definition/**`.
|
||
- **Harte YELLOW-Regeln, Vorschlag:**
|
||
- Liquibase-Changelogs `src/main/resources/db/**`;
|
||
- RBAC und Security (`**/rbac/**`, `**/*Security*`, `**/*ApiKey*`);
|
||
- Build und Abhängigkeiten (`build.gradle.kts`, `buildSrc/**`, `gradle/**`);
|
||
- CI und Deployment (`.werkator*`, `tools/remote`, `Dockerfile*`);
|
||
- Profile (`src/main/resources/application*.yml`).
|
||
Die endgültige Liste legt das Team fest.
|
||
- **Projektwissen:**
|
||
- `repo_context_files = ["AGENTS.md"]` gibt dem Modell die Review-Regeln des Projekts mit.
|
||
- PR-Agent liest die Datei über die Gitea-API aus der Basis des PRs, nie aus dem PR selbst; ein PR kann seine eigenen Review-Regeln also nicht ändern.
|
||
- **Gate:** `yellow_gate = "approval"`, `human_reviewers` = die drei Entwickler-Konten.
|
||
- **Vollständige Dateien:** Ab werkrevisor 0.3.0 sieht das Modell nach dem Diff auch den vollständigen neuen Inhalt jeder geänderten Datei (`full_files = true`).
|
||
Passt eine Datei nicht in die Grenzen `max_full_file_chars` bzw. `max_full_files_chars`, wird das Ergebnis höchstens YELLOW.
|
||
- **Engine:** `[engine] mode = "llm"` bleibt der Standard.
|
||
Mit `combined` bewertet Jev zuerst die Abschnitte und Gherkin-Szenarien der PR-Dokumente unter `doc/PR/`;
|
||
ein klar schlechtes Szenario ergibt RED, auch ohne Befund des LLM.
|
||
Die Fragen und Schwellwerte in `[classifier]` vorher mit `tools/jev-eval` an den vorhandenen PR-Dokumenten prüfen.
|
||
|
||
## 4. Image auf vm4006
|
||
|
||
Auf vm4006 als Werkator-Benutzer:
|
||
|
||
```bash
|
||
git clone https://git.javagil.de/mi/werkrevisor.git && cd werkrevisor
|
||
docker pull pragent/pr-agent:0.47.0@sha256:7d98954c29289846a08faf00aaea0f1f1375b1676cd8a2ed303e0af07010af7a
|
||
docker build --pull=false -t werkrevisor:$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' werkrevisor/__init__.py) .
|
||
```
|
||
|
||
Jede neue werkrevisor-Version bekommt ein eigenes Tag; die Build-Definition nennt das Tag ausdrücklich.
|
||
|
||
## 5. Werkator-Build-Definition
|
||
|
||
Je Repository in der Maschinen-Konfiguration `.git/werkator/.werkator.yml` auf vm4006 (nie in eine eingecheckte Datei):
|
||
|
||
```yaml
|
||
builds:
|
||
ai-review:
|
||
trigger:
|
||
onPullRequestTarget: true
|
||
statusContext: ai-review/gate
|
||
cleanCommand: ""
|
||
buildCommand: python -s -m werkrevisor
|
||
timeout: 15m
|
||
artifactDirs: [build/werkrevisor]
|
||
docker:
|
||
enabled: true
|
||
image: werkrevisor:0.4.0
|
||
env:
|
||
PYTHONNOUSERSITE: "1"
|
||
GITEA_BOT_TOKEN: "…"
|
||
OPENROUTER_API_KEY: "…"
|
||
# nur für [engine] mode "classifier" oder "combined":
|
||
# TYPESAFE_API_KEY: "…"
|
||
# Die vollständige Betreiber-Konfiguration, Ausgangspunkt ist config/hsadmin-ng.toml.
|
||
WERKREVISOR_CONFIG_TOML: |
|
||
[model]
|
||
id = "openrouter/anthropic/claude-sonnet-5.5"
|
||
input_price_usd_per_mtok = 2.00
|
||
output_price_usd_per_mtok = 10.00
|
||
max_input_tokens = 190000
|
||
max_output_tokens = 10000
|
||
reasoning_effort = "medium"
|
||
# … alle weiteren Abschnitte aus config/hsadmin-ng.toml …
|
||
```
|
||
|
||
Modell und Reasoning-Stufe wechselt man in `WERKREVISOR_CONFIG_TOML` (`id`, beide Preise, `reasoning_effort`, bei Bedarf die Token-Grenzen); der nächste Review nutzt sie, ein neues Image ist nicht nötig.
|
||
Der eingebettete TOML-Text ersetzt die Datei vollständig, deshalb immer die ganze Konfiguration einfügen; fehlt ein Abschnitt, bricht werkrevisor mit ERROR ab.
|
||
`python -s` und `PYTHONNOUSERSITE=1` verhindern, dass Python Code aus dem Home-Verzeichnis lädt; ohne sie bricht werkrevisor mit Exit 30 ab.
|
||
|
||
Die Datei muss die Rechte `600` haben.
|
||
Zuerst eine Sicherung der bisherigen Datei anlegen.
|
||
Das Timeout muss über `timeout_seconds × (max_retries + 1) + 120` Sekunden liegen.
|
||
|
||
## 6. Erprobung vor der Aktivierung
|
||
|
||
1. **Nur Regeln, kostenlos:** `tools/dry-run <PR-URL> config/hsadmin-ng.toml` für die letzten etwa 25 gemergten PRs.
|
||
Ergebnis: Welche PRs würden die Regeln automatisch freigeben, welche würden sie sperren?
|
||
2. **Mit Modell:** dieselben PRs mit `--llm` und je Kandidatenmodell; zuerst PRs, deren Befunde aus menschlichen Reviews bekannt sind.
|
||
Ergebnis: gefundene und übersehene Befunde sowie die Kosten je Modell.
|
||
3. Mit dem Team die Regeln und das Modell festlegen.
|
||
|
||
`tools/dry-run` schreibt nichts nach Gitea; es braucht `GITEA_BOT_TOKEN` (Lesen genügt) und für `--llm` den OpenRouter-Key.
|
||
|
||
## 7. Branch Protection
|
||
|
||
Erst nach Schritt 6 und erst, wenn ein paar echte PRs ohne Pflicht gelaufen sind.
|
||
|
||
1. Die bestehende Regel sichern:
|
||
`GET /api/v1/repos/<owner>/<repo>/branch_protections/master` in eine Datei schreiben.
|
||
2. Die Regel per `PATCH` ergänzen; die bestehenden Status-Kontexte (z. B. `GitTally`) bleiben:
|
||
|
||
| Feld | Wert |
|
||
| ----------------------------------- | --------------------------------------------- |
|
||
| `status_check_contexts` | bisherige Kontexte und `ai-review/gate` |
|
||
| `required_approvals` | `1` |
|
||
| `enable_approvals_whitelist` | `true` |
|
||
| `approvals_whitelist_username` | `ai-reviewer` und die menschlichen Reviewer |
|
||
| `block_on_rejected_reviews` | `true` |
|
||
| `block_on_official_review_requests` | `true` |
|
||
| `dismiss_stale_approvals` | `true` |
|
||
| `block_on_outdated_branch` | `true` |
|
||
| `block_admin_merge_override` | `true`, damit auch Administratoren die Sperre nicht übergehen |
|
||
|
||
3. Mit einem harmlosen PR prüfen: GREEN wird mergebar, YELLOW sperrt bis zum Approval.
|
||
|
||
## Vertrauensmodell
|
||
|
||
Auf vm4006 laufen nur eng zusammengehörige Repositories (Backend und Frontend von hsadmin-ng).
|
||
Pushen können nur Entwickler, die ohnehin Schreibrecht auf allen diesen Repositories und vollen Zugriff auf vm4006 haben.
|
||
Ein CI-Build mit Docker-Socket (Testcontainers) könnte das Image `werkrevisor:<version>` umbenennen oder ersetzen;
|
||
dieses Restrisiko ist akzeptiert, weil ein PR niemandem mehr Zugriff verschafft, als er schon hat.
|
||
Sobald Fremde pushen dürfen, etwa bei einem öffentlichen Repository, muss die Build-Definition das Image über seine ID ansprechen (`docker image inspect --format '{{.Id}}' werkrevisor:<version>`).
|
||
|
||
## Rückbau
|
||
|
||
1. Die gesicherte Branch-Protection-Regel per `PATCH` zurückschreiben.
|
||
2. Den Block `builds.ai-review` aus der Maschinen-Konfiguration entfernen.
|
||
3. `ai-reviewer` aus den Repositories entfernen, Token löschen, Konto deaktivieren.
|
||
4. Den OpenRouter-Key löschen.
|
||
5. `docker image rm werkrevisor:<version>`.
|
||
|
||
## Offene Punkte vor dem Einsatz
|
||
|
||
- Vollständige geänderte Dateien als Kontext (werkrevisor).
|
||
- Review-Builds sollen nicht hinter der CI warten; dazu müssen sie das Limit `maxConcurrentPerRepository` umgehen können (Werkator).
|
||
- Ein menschliches Approval sollte `ai-review/assessment` aktualisieren (Werkator oder werkrevisor).
|
||
- Konfiguration für das Frontend-Repository; dessen Pfade kenne ich noch nicht.
|