GitHub verbinden
Verbinden Sie Ihr GitHub-Repository mit Jamdesk für automatische Bereitstellungen bei jedem Push. Mit App-Installation, Repository-Auswahl und Branch-Konfiguration.
Jamdesk stellt Ihre Dokumentation automatisch bereit, sobald Sie an GitHub pushen.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Informationen dazu, wie die GitHub-App und die Verknüpfung persönlicher Konten zusammenwirken, finden Sie unter GitHub-Integration verstehen.
Dokumentation in Bitbucket Cloud? Siehe Bitbucket verbinden. Jedes Projekt ist mit genau einem Anbieter verbunden. Kein GitHub-Konto? Siehe Dokumentation ohne GitHub.
GitHub-App installieren
Jamdesk fordert Sie beim ersten Anmelden auf, die Jamdesk-GitHub-App zu installieren. Die App gewährt:
- Repository-Zugriff: Lesen Ihrer Dokumentationsinhalte
- Webhooks: Auslösen von Builds bei Push
- Commit-Status: Anzeige des Build-Status an Commits
Berechtigungen
Die Jamdesk-GitHub-App fordert folgende Berechtigungen an:
| Berechtigung | Zweck |
|---|---|
| Repository-Inhalte (Lesen und Schreiben) | Klonen und Lesen Ihrer Dokumentationsdateien. Schreibzugriffe erfolgen nur, wenn Sie im Dashboard-Editor speichern, KI-Korrekturvorschläge übernehmen oder Übersetzungen aktivieren |
| Metadaten (Lesen) | Auflisten von Repositories und Branches |
| Webhooks | Empfangen von Push-Benachrichtigungen |
Jamdesk greift nur auf Repositories zu, für die Sie den Zugriff ausdrücklich freigegeben haben. Sie können den Zugriff jederzeit in Ihren GitHub-Einstellungen ändern.
Repository verbinden
Klicken Sie beim Erstellen oder Bearbeiten eines Projekts auf Connect Repository.
Wählen Sie aus den Repositories, auf denen die GitHub-App installiert ist.
Wählen Sie den Branch für die Bereitstellung:
- main oder master: am gebräuchlichsten für Produktionsdokumentation
- docs: wenn Sie Ihre Dokumentation in einem eigenen Branch führen
- Beliebiger Branch: für Vorschau-Bereitstellungen
Falls sich Ihre docs.json nicht im Stammverzeichnis des Repositories befindet, geben Sie den Pfad an:
docs/ # Docs in a subdirectory
packages/docs/ # Monorepo with docs packageLassen Sie das Feld leer, wenn sich docs.json im Stammverzeichnis befindet.
Das Projekt-Dashboard zeigt dann das verknüpfte Repository und den Branch an:
Automatische Bereitstellungen
Jeder Push auf Ihren konfigurierten Branch löst einen Build aus:
git add .
git commit -m "Update API documentation"
git push origin mainBuilds sind in der Regel nach 30 bis 90 Sekunden abgeschlossen. Den Status sehen Sie im Dashboard oder am GitHub-Commit.
Repositories ändern
Um ein anderes Repository zu verbinden:
- Gehen Sie zu Settings → Repository
- Klicken Sie auf Change Repository
- Wählen Sie das neue Repository und den Branch aus
Das Wechseln des Repositories kann Ihre Live-Dokumentation beeinflussen. Das neue Repository muss eine gültige Jamdesk-Konfiguration enthalten.
Zugriff auf die GitHub-App verwalten
Legen Sie fest, auf welche Repositories Jamdesk zugreifen darf:
- Gehen Sie zu github.com/settings/installations
- Suchen Sie Jamdesk in der Liste
- Klicken Sie auf Configure
- Wählen Sie unter „Repository access“ bestimmte Repositories oder alle aus
Organisations-Repositories
Ein Organisationsadministrator muss die Installation der GitHub-App für Organisations-Repositories genehmigen:
- Fordern Sie die Installation über Ihr Jamdesk-Dashboard an
- Ein Administrator erhält eine Benachrichtigung in GitHub
- Nach der Genehmigung erscheinen die Organisations-Repositories im Repository-Auswahlfeld
Persönliches Konto verknüpfen
Verknüpfen Sie Ihr persönliches GitHub-Konto unter User Settings für eine zuverlässige Zuordnung der Builds:
- Klicken Sie auf Ihren Avatar → User Settings
- Suchen Sie den Abschnitt GitHub Account
- Klicken Sie auf Link GitHub Account
Diese Verknüpfung ist von der GitHub-App getrennt. Sie ordnet Ihre Commits Ihrem Konto zu. Mehr erfahren.
Fehlerbehebung
Repository wird nicht angezeigt
- Prüfen Sie, ob die GitHub-App auf dem Repository installiert ist
- Bei Organisations-Repositories: Vergewissern Sie sich, dass ein Administrator den Zugriff genehmigt hat
- Aktualisieren Sie die Repository-Liste im Dashboard
GitHub leitet dich immer wieder zur Jamdesk-App-Seite zurück
Ihr Unternehmen verwaltet Ihr GitHub-Konto wahrscheinlich selbst. GitHub erlaubt solchen Konten nicht, eigenständig Apps zu installieren. Lösungen finden Sie unter unternehmensverwaltete GitHub-Konten.
Ein GitHub-Konto verwenden, das ein anderes Jamdesk-Konto nutzt
Die Repository-Liste zeigt eine Meldung, die beginnt mit:
Another Jamdesk account already uses this GitHub account.
Das bedeutet, dass das Projekt eines anderen Jamdesk-Kontos die Jamdesk-GitHub-App bereits für dieses GitHub-Konto nutzt. Meist hat ein Teammitglied Jamdesk zuerst eingerichtet, oder Sie sind mit einem zweiten Jamdesk-Konto angemeldet.
So nutzen Sie die Repositories dieses Kontos:
- Klicken Sie auf Verify on GitHub.
- Melden Sie sich bei GitHub als Benutzer an, der in das Repository pushen darf.
- Wählen Sie das Repository aus der Liste aus.
Verify on GitHub verknüpft den GitHub-Benutzer, mit dem Sie sich anmelden, mit Ihrem Jamdesk-Konto – genau wie User Settings es tut. Falls Ihr Browser bereits bei GitHub mit einem anderen Benutzer angemeldet ist, melden Sie sich zuerst bei GitHub ab.
Die Liste zeigt nur Repositories, in die Ihr GitHub-Benutzer pushen darf. Die Prüfung gilt eine Stunde, wählen Sie das Repository daher zeitnah nach der Verifizierung aus. Falls Jamdesk meldet, dass GitHub keine nutzbaren Installationen gefunden hat, prüfen Sie, ob Sie mit dem richtigen GitHub-Benutzer angemeldet sind. Alternativ bitten Sie einen Inhaber des GitHub-Kontos, Ihnen Zugriff auf das Repository zu gewähren.
Um stattdessen im selben Projekt zu arbeiten, bitten Sie dessen Inhaber, Sie einzuladen.
Builds werden nicht ausgelöst
- Prüfen Sie, ob der Webhook in den Repository-Einstellungen aktiv ist
- Vergewissern Sie sich, dass Sie auf den konfigurierten Branch pushen
- Suchen Sie in GitHub nach Fehlern bei der Webhook-Zustellung
Fehler wegen verweigerter Berechtigung
- Autorisieren Sie die GitHub-App in Ihren GitHub-Einstellungen erneut
- Bestätigen Sie, dass die Jamdesk-App auf das Repository zugreifen kann
Ausführlichere Hinweise zur Fehlerbehebung finden Sie unter GitHub-Integration verstehen.