my2dos/docs/gitea-integration.md

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

/issue Fehler beim Speichern
Weitere Beschreibung des Problems.

Repository über einen Alias auswählen

/issue my2dos Fehler beim Speichern
Weitere Beschreibung des Problems.

Dabei könnte my2dos beispielsweise auf rucki/my2dos verweisen.

Mögliche spätere Optionen

/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:

POST /api/v1/repos/{owner}/{repository}/issues
Authorization: token <API-TOKEN>
Content-Type: application/json

Beispielinhalt:

{
  "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.