rucki
225 lines
6.2 KiB
Markdown
225 lines
6.2 KiB
Markdown
# Mögliche Erweiterung: Gitea-Integration
|
||
|
||
## Status
|
||
|
||
Konzeptvorschlag – noch nicht implementiert.
|
||
|
||
## Ziel
|
||
|
||
my2dos soll Issues in einer Gitea-Instanz erstellen können. Die Erfassung erfolgt direkt über einen Slash-Befehl. In einer ersten Version findet keine automatische bidirektionale Synchronisation statt.
|
||
|
||
## Vorgeschlagene Bedienung
|
||
|
||
### Issue im Standard-Repository erstellen
|
||
|
||
```text
|
||
/issue Fehler beim Speichern
|
||
Weitere Beschreibung des Problems.
|
||
```
|
||
|
||
### Repository über einen Alias auswählen
|
||
|
||
```text
|
||
/issue my2dos Fehler beim Speichern
|
||
Weitere Beschreibung des Problems.
|
||
```
|
||
|
||
Dabei könnte `my2dos` beispielsweise auf `rucki/my2dos` verweisen.
|
||
|
||
### Mögliche spätere Optionen
|
||
|
||
```text
|
||
/issue my2dos Fehler beim Speichern /labels bug,frontend
|
||
```
|
||
|
||
Weitere denkbare Angaben:
|
||
|
||
- Labels
|
||
- zuständige Person
|
||
- Meilenstein
|
||
- Priorität
|
||
- Gitea-Projekt
|
||
|
||
Die genaue Syntax sollte erst nach Erfahrungen mit der Basisversion festgelegt werden.
|
||
|
||
## Verhalten der ersten Version
|
||
|
||
1. Benutzer gibt `/issue` mit Titel und optionaler Beschreibung ein.
|
||
2. my2dos bestimmt das Standard-Repository oder löst den angegebenen Alias auf.
|
||
3. Das Issue wird über die Gitea-REST-API erstellt.
|
||
4. In my2dos wird ein lokaler Link-Eintrag zum Issue angelegt.
|
||
5. Issue-Nummer, Repository und URL werden lokal gespeichert.
|
||
6. Schlägt der API-Aufruf fehl, bleibt der eingegebene Text als lokaler Eintrag erhalten und zeigt einen verständlichen Fehlerstatus.
|
||
|
||
Der Text darf bei Netzwerk- oder Gitea-Fehlern nicht verloren gehen.
|
||
|
||
## Einstellungen
|
||
|
||
In den Benutzereinstellungen könnte ein Bereich **Gitea** ergänzt werden:
|
||
|
||
- URL der Gitea-Instanz
|
||
- API-Token
|
||
- Standard-Repository
|
||
- optionale Repository-Aliase
|
||
- Verbindung testen
|
||
|
||
Beispiel für Aliase:
|
||
|
||
| Alias | Gitea-Repository |
|
||
|---|---|
|
||
| `my2dos` | `rucki/my2dos` |
|
||
| `website` | `rucki/website` |
|
||
|
||
Später könnten Verbindungen auch einem Team statt nur einem Benutzer gehören.
|
||
|
||
## Mögliches Datenmodell
|
||
|
||
### `GiteaConnection`
|
||
|
||
- Benutzer oder Team
|
||
- Server-URL
|
||
- verschlüsselter API-Token
|
||
- aktiv/inaktiv
|
||
- Erstellungs- und Änderungszeitpunkt
|
||
|
||
### `GiteaRepository`
|
||
|
||
- Gitea-Verbindung
|
||
- Alias
|
||
- Owner
|
||
- Repository-Name
|
||
- Kennzeichnung als Standard-Repository
|
||
|
||
### `ExternalIssue`
|
||
|
||
- lokaler my2dos-Eintrag
|
||
- Gitea-Repository
|
||
- Issue-Nummer
|
||
- externe URL
|
||
- Synchronisationsstatus
|
||
- letzte Fehlermeldung
|
||
- Zeitpunkt der letzten Synchronisation
|
||
|
||
Alternativ könnte `ExternalIssue` später zu einem allgemeinen Modell für externe Systeme erweitert werden.
|
||
|
||
## Gitea-API
|
||
|
||
Zum Erstellen eines Issues wird voraussichtlich folgender Endpunkt verwendet:
|
||
|
||
```http
|
||
POST /api/v1/repos/{owner}/{repository}/issues
|
||
Authorization: token <API-TOKEN>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
Beispielinhalt:
|
||
|
||
```json
|
||
{
|
||
"title": "Fehler beim Speichern",
|
||
"body": "Weitere Beschreibung des Problems."
|
||
}
|
||
```
|
||
|
||
Die genaue API muss gegen die eingesetzte Gitea-Version geprüft werden.
|
||
|
||
## Fehlerbehandlung
|
||
|
||
Zu berücksichtigen sind insbesondere:
|
||
|
||
- Gitea nicht erreichbar
|
||
- Zeitüberschreitung
|
||
- ungültiger oder abgelaufener Token
|
||
- fehlende Berechtigung für das Repository
|
||
- unbekannter Repository-Alias
|
||
- Repository nicht gefunden
|
||
- ungültige Labels oder Meilensteine
|
||
|
||
Ein externer API-Aufruf sollte ein kurzes Timeout besitzen. Fehler müssen im lokalen Eintrag nachvollziehbar sein. Für spätere automatische Wiederholungen wäre ein Hintergrundjob sinnvoll.
|
||
|
||
## Sicherheit
|
||
|
||
- API-Tokens dürfen nicht im Klartext angezeigt oder protokolliert werden.
|
||
- Tokens sollten verschlüsselt gespeichert oder zunächst über Umgebungsvariablen bereitgestellt werden.
|
||
- Tokens sollten nur die notwendigen Gitea-Berechtigungen besitzen.
|
||
- Benutzerdefinierte Gitea-URLs müssen validiert werden, um SSRF-Zugriffe auf interne Dienste zu verhindern.
|
||
- Für produktive Verbindungen sollte HTTPS verlangt werden.
|
||
- Spätere Webhooks benötigen eine Signatur- oder Secret-Prüfung.
|
||
|
||
## Zusammenspiel mit Slash-Befehlen
|
||
|
||
`/issue` ist eine Aktion und nicht zwingend ein neuer Eintragstyp. Zwei Varianten sind möglich:
|
||
|
||
1. `/issue` erstellt das externe Issue und lokal einen Link-Eintrag.
|
||
2. `/issue` erstellt lokal eine Aufgabe, die mit dem externen Issue verbunden ist.
|
||
|
||
Für den MVP wird Variante 1 empfohlen, weil der externe Issue-Link das primäre Ergebnis ist. Vor der Implementierung sollte entschieden werden, ob `/issue` – wie die Typbefehle – nur am Anfang eines Eintrags erlaubt ist.
|
||
|
||
## Tests
|
||
|
||
Mindestens erforderlich:
|
||
|
||
- Parser für `/issue`
|
||
- Standard-Repository und Alias-Auflösung
|
||
- Titel und mehrzeilige Beschreibung
|
||
- erfolgreicher API-Aufruf mit gemockter Gitea-API
|
||
- Fehlerantworten und Timeouts
|
||
- kein Verlust des lokalen Textes bei Fehlern
|
||
- Berechtigungsprüfung für Benutzer und Teams
|
||
- sichere Behandlung des Tokens
|
||
- API- und UI-Erstellung
|
||
|
||
## Ausbaustufen
|
||
|
||
### Stufe 1: Issues erstellen
|
||
|
||
- eine Gitea-Verbindung pro Benutzer
|
||
- Standard-Repository
|
||
- `/issue Titel`
|
||
- lokaler Link zum erstellten Issue
|
||
- robuste Fehlerbehandlung
|
||
|
||
Geschätzter Aufwand: **1–2 Entwicklungstage**.
|
||
|
||
### Stufe 2: Mehrere Repositories und Labels
|
||
|
||
- Repository-Aliase
|
||
- Label-Zuordnung
|
||
- Team-Verbindungen
|
||
- Verbindungstest in den Einstellungen
|
||
|
||
Geschätzter Gesamtaufwand: **3–5 Entwicklungstage**.
|
||
|
||
### Stufe 3: Bidirektionale Synchronisation
|
||
|
||
- geschlossenes Gitea-Issue erledigt die lokale Aufgabe
|
||
- erledigte lokale Aufgabe schließt das Gitea-Issue
|
||
- Kommentare synchronisieren
|
||
- Webhooks
|
||
- Schutz vor Synchronisationsschleifen
|
||
|
||
Geschätzter Aufwand: **1–2 Wochen**.
|
||
|
||
### Stufe 4: Vollständige Integration
|
||
|
||
- OAuth statt manueller Tokens
|
||
- mehrere Gitea-Instanzen
|
||
- Hintergrundjobs und automatische Wiederholungen
|
||
- Bearbeiter, Meilensteine und Projekte
|
||
- Konfliktbehandlung
|
||
|
||
Geschätzter Aufwand: **2–3 Wochen**.
|
||
|
||
## Empfohlener MVP
|
||
|
||
1. Gitea-URL, Token und Standard-Repository konfigurierbar machen.
|
||
2. Repository-Aliase unterstützen.
|
||
3. `/issue [alias] Titel` parsen.
|
||
4. Restlichen mehrzeiligen Text als Beschreibung verwenden.
|
||
5. Issue synchron über die Gitea-API erstellen.
|
||
6. Einen lokalen Link-Eintrag mit externer Referenz anlegen.
|
||
7. Bei Fehlern einen lokalen Eintrag mit Wiederholungsmöglichkeit behalten.
|
||
8. Noch keine automatische Synchronisation oder Webhooks implementieren.
|
||
|
||
Diese Variante liefert schnell einen praktischen Nutzen und hält Sicherheits-, Synchronisations- und Betriebsaufwand zunächst überschaubar.
|