GitHub verbinden
Verbinde dein GitHub-Repository mit Jamdesk für automatische Bereitstellungen bei Pushes – mit App-Installation, Repository-Auswahl und Branch-Konfiguration.
Jamdesk lässt sich mit GitHub integrieren, um deine Dokumentation bei jedem Push automatisch bereitzustellen.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Weitere Informationen dazu, wie die GitHub-App und die Verknüpfung persönlicher Konten zusammenspielen, findest du unter GitHub-Integration verstehen.
Dokumentation stattdessen in Bitbucket Cloud? Siehe Bitbucket verbinden. Jedes Projekt wird mit genau einem Anbieter verbunden.
GitHub-App installieren
Wenn du dich zum ersten Mal bei Jamdesk anmeldest, wirst du aufgefordert, die Jamdesk-GitHub-App zu installieren. Diese App ermöglicht:
- Repository-Zugriff – Deine Dokumentationsinhalte lesen
- Webhooks – Builds bei Pushes auslösen
- Commit-Status – Build-Status für Commits anzeigen
Berechtigungen
Die Jamdesk-GitHub-App fordert folgende Berechtigungen an:
| Berechtigung | Zweck |
|---|---|
| Repository-Inhalte (Lesen) | Deine Dokumentationsdateien klonen und lesen |
| Metadaten (Lesen) | Repositories und Branches auflisten |
| Webhooks | Push-Benachrichtigungen empfangen |
Jamdesk greift nur auf Repositories zu, für die du ausdrücklich Zugriff gewährst. Du kannst den Zugriff jederzeit in deinen GitHub-Einstellungen ändern.
Repository verbinden
Klicke beim Erstellen oder Bearbeiten eines Projekts auf Connect Repository.
Wähle ein Repository aus, in dem die GitHub-App installiert ist.
Wähle den bereitzustellenden Branch aus:
- main oder master – Am häufigsten für Produktionsdokumentation
- docs – Wenn du die Dokumentation in einem separaten Branch speicherst
- Beliebiger Branch – Für Vorschau-Bereitstellungen
Wenn sich deine docs.json nicht im Repository-Stammverzeichnis befindet, gib den Pfad an:
docs/ # Docs in a subdirectory
packages/docs/ # Monorepo with docs packageLass das Feld leer, wenn sich docs.json im Stammverzeichnis befindet.
Nach der Verbindung zeigt dein Projekt-Dashboard das verknüpfte Repository und den Branch an:
Automatische Bereitstellungen
Nach der Verbindung löst jeder Push auf deinen konfigurierten Branch einen Build aus:
git add .
git commit -m "Update API documentation"
git push origin mainBuilds sind normalerweise innerhalb von 30–90 Sekunden abgeschlossen. Du kannst den Status im Dashboard oder beim GitHub-Commit anzeigen.
Repositories ändern
So verbindest du ein anderes Repository:
- Gehe zu Settings → Repository
- Klicke auf Change Repository
- Wähle das neue Repository und den Branch aus
Das Ändern von Repositories kann sich auf deine live geschaltete Dokumentation auswirken. Das neue Repository muss eine gültige Jamdesk-Konfiguration enthalten.
Zugriff auf die GitHub-App verwalten
Lege fest, auf welche Repositories Jamdesk zugreifen kann:
- Gehe zu github.com/settings/installations
- Suche Jamdesk in der Liste
- Klicke auf Configure
- Wähle unter „Repository access“ bestimmte Repositories oder alle Repositories aus
Organisations-Repositories
Bei Organisations-Repositories muss ein Organisationsadministrator die Installation der GitHub-App genehmigen:
- Fordere die Installation über dein Jamdesk-Dashboard an
- Ein Administrator erhält eine Benachrichtigung in GitHub
- Nach der Genehmigung werden Organisations-Repositories in der Repository-Auswahl angezeigt
Persönliches Konto verknüpfen
Für eine zuverlässige Zuordnung von Builds verknüpfst du dein persönliches GitHub-Konto in den User Settings:
- Klicke auf deinen Avatar → User Settings
- Suche den Abschnitt GitHub Account
- Klicke auf Link GitHub Account
Dies ist unabhängig von der GitHub-App und stellt sicher, dass deine Commits korrekt dir zugeordnet werden. Mehr erfahren.
Fehlerbehebung
Repository wird nicht angezeigt
- Überprüfe, ob die GitHub-App im Repository installiert ist
- Stelle bei Organisations-Repositories sicher, dass ein Administrator den Zugriff genehmigt hat
- Aktualisiere die Repository-Liste im Dashboard
GitHub leitet dich immer wieder zur Jamdesk-App-Seite zurück
Dein Unternehmen verwaltet wahrscheinlich dein GitHub-Konto, und GitHub erlaubt es solchen Konten nicht, Apps auf eigene Faust zu installieren. Siehe unternehmensverwaltete GitHub-Konten, um das Problem zu beheben.
Builds werden nicht ausgelöst
- Überprüfe, ob der Webhook in den Repository-Einstellungen aktiv ist
- Stelle sicher, dass du auf den konfigurierten Branch pushst
- Suche in GitHub nach Fehlern bei der Webhook-Zustellung
Fehler wegen verweigerter Berechtigung
- Autorisiere die GitHub-App in deinen GitHub-Einstellungen erneut
- Stelle sicher, dass auf das Repository über die Jamdesk-App zugegriffen werden kann
Eine ausführlichere Fehlerbehebung findest du unter GitHub-Integration verstehen.