GitHub-Repository-Verbindung#
Eine GitHub-Repository-Verbindung speichert Zugangsdaten und Gültigkeitsbereich für ein owner/repository-Paar. Dieselbe Verbindung nutzt OakCore für mehrere Binding-Familien zu diesem Repo — z. B. GitHub Issues, GitHub Pull Requests und GitHub-Quellcode.
Eine Connection pro Repository#
OakCore legt eine Connection pro Gültigkeitsbereich an. Das bedeutet wenn Sie mehrere GitHub-Repositories verknüpfen wollen, dann benötigen Sie jeweils eine eigene Connection.
Hinweis: Ein Personal Access Token (PAT) kann auf GitHub mehrere Repositories abdecken. Sie können denselben Token beim Anlegen mehrerer Connections wiederverwenden. OakCore speichert ihn pro Connection getrennt, der Gültigkeitsbereich bleibt aber immer ein Repo pro Connection.
Warum nicht ein Connection-Eintrag mit mehreren Repos?
- Webhooks werden auf GitHub pro Repository konfiguriert.
- Bindings prüfen, ob das Artefakt zum Scope der gewählten Connection passt.
- Fehler, Berechtigungen und Health-Status bleiben pro Repo nachvollziehbar.
Voraussetzungen#
- Projekt in OakCore öffnen → Einstellungen → Integrationen.
- Pro Ziel-Repository eine GitHub-Repository-Verbindung anlegen.
- Auf GitHub: Lesezugriff auf das Repository für die Binding-Familien, die Sie nutzen wollen. Schreibzugriff auf Issue-Kommentare nur, wenn Sie Backlinks auf Issues oder Pull Requests brauchen. Admin-Zugriff für Webhooks (empfohlen).
Connection hinzufügen#
Unter Einstellungen → Integrationen auf Hinzufügen klicken.
Label#
Kurzer Name nur in OakCore, um Connections zu unterscheiden.
| Gut | Vermeiden |
|---|---|
Acme widgets |
acme/widgets |
Platform team backlog |
github |
Owner / Repository#
Für https://github.com/acme/widgets: Owner acme, Repository widgets.
Gebundene Artefakte müssen zu genau diesem Paar gehören.
Personal Access Token (PAT)#
Verschlüsselt gespeichert; nach dem Speichern nicht erneut anzeigbar.
Berechtigungen sind optional — nur das einrichten, was Sie nutzen
Sie müssen nicht alle Scopes auf einmal vergeben. Richten Sie nur die Berechtigungen ein, die zu den Binding-Familien passen, die Sie an diesem Repo nutzen wollen. Fehlende Berechtigungen für andere Familien sind in Ordnung.
| Binding-Familie | Benötigte Token-Berechtigung (Fine-grained) | Classic PAT |
|---|---|---|
| Issues — lesen | Issues → Read | repo / public_repo |
| Issues — Backlink-Kommentare | Issues → Read and write | repo / public_repo |
| Pull Requests — lesen | Pull requests → Read | repo / public_repo |
| Pull Requests — Backlink-Kommentare | Pull requests → Read and write | repo / public_repo |
| Quelldatei-Bindings — lesen | Contents → Read | repo / public_repo |
Pull-Request-Backlinks laufen über die Issue-Comment-API (/issues/{number}/comments), aber GitHub autorisiert Kommentare auf Pull Requests über Pull requests → Read and write.
Fine-grained PAT (empfohlen)#
- Unter Repository access das Ziel-Repo auswählen.
- Unter Repository permissions nur die Zeilen aus der Tabelle oben setzen, die Sie brauchen.
Classic PAT#
Scope repo (bzw. public_repo für öffentliche Repos). Deckt alle Familien ab, ist aber breiter als nötig.
Webhook-Secret (optional)#
Gemeinsames Passwort zwischen GitHub und OakCore. Denselben Wert in OakCore und im GitHub-Webhook unter Secret verwenden.
openssl rand -hex 32
Connection testen#
Nach dem Speichern auf der Connection-Karte Test klicken.
Der Test prüft, ob das Token das konfigurierte owner/repository erreichen kann, und erkennt danach Token-Berechtigungen für die unterstützten Binding-Familien. Fehlende Berechtigungen erscheinen auf der Connection-Karte als Missing — z. B. Contents (read) ohne Quelldatei-Zugriff.
GitHub-Webhook einrichten (empfohlen)#
Settings → Webhooks → Add webhook
| Feld | Wert |
|---|---|
| Payload URL | Von der Connection-Karte kopieren oder {API_URL}/api/v1/integrations/webhooks/issue/github/{connection_id} |
| Content type | application/json |
| Secret | Wie Webhook secret in OakCore |
| Events | Siehe Familien-Docs unten |
Welche Events
| Binding-Familie | GitHub-Events |
|---|---|
| Issues | Issues (nicht Issue comments) |
| Pull Requests | Pull requests |
| Quelldatei-Bindings | Kein Webhook nötig (Sync beim Binden und manuell) |
Beide Webhook-Familien können ein Webhook mit derselben Payload-URL abdecken.
Die Payload-URL muss den OakCore-API-Host nutzen, von GitHub aus erreichbar.
Mehrere Repositories#
Jedes Repository braucht eine eigene Connection (eigenes Label, optional eigener Webhook). Sie können denselben PAT in mehreren Connections verwenden, wenn das Token auf alle Repos Zugriff hat.
Fehlerbehebung#
| Symptom | Prüfen |
|---|---|
| Test schlägt fehl | Owner/Repo, PAT abgelaufen, Token hat keinen Zugriff auf dieses Repo |
| Bind abgelehnt | Artefakt gehört zu anderem Repo als die gewählte Connection |
| Issue/PR-Binding schlägt fehl | Fehlende Issues- oder Pull requests-Berechtigung |
| Quelldatei-Vorschau schlägt fehl | Fehlende Contents → Read-Berechtigung |
| Keine Live-Updates | Webhook-URL, Secret, Events, API erreichbar |
Bei Self-Hosting: API-URL für GitHub erreichbar machen (z. B. ngrok).