GitHub-Integration
Jamdesk verwendet zwei GitHub-Verbindungen: eine GitHub App für den Repository-Zugriff und eine persönliche Kontoverknüpfung zur Build-Zuordnung.
Jamdesk verwendet zwei separate GitHub-Verbindungen, die jeweils eine andere Aufgabe erfüllen. Diese Seite erklärt, was die einzelnen Verbindungen tun und wann Sie sie benötigen.
Kurzfassung: Die GitHub App ermöglicht Jamdesk den Zugriff auf Ihr Repository. Durch die Verknüpfung Ihres persönlichen Kontos werden Ihre Commits Ihnen zugeordnet.
Bitbucket Cloud-Projekte funktionieren anders: Eine einzelne OAuth-Autorisierung deckt den Repository-Zugriff, den Webhook und die Build-Zuordnung ab. Siehe Bitbucket verbinden.
Übersicht
| Verbindung | Zweck | Umfang | Erforderlich? |
|---|---|---|---|
| GitHub App | Repository-Zugriff & Webhooks | Pro Projekt | Ja |
| Persönliches Konto | Benutzeridentität & Zuordnung | Pro Benutzer | Empfohlen |
GitHub App (Projektebene)
Die Jamdesk GitHub App wird in Ihrem GitHub-Konto oder Ihrer Organisation installiert. Sie gewährt Jamdesk Zugriff auf bestimmte Repositories.
Was sie tut
- Liest Repository-Inhalte – Klont Ihre Dokumentation, um sie zu erstellen
- Empfängt Webhooks – Wird benachrichtigt, wenn Sie Änderungen pushen
- Meldet den Build-Status – Zeigt den Bereitstellungsstatus von Commits an
Warum Sie sie benötigen
Ohne installierte GitHub App kann Jamdesk Folgendes nicht:
- Auf Ihr Repository zugreifen, um die Dokumentation zu erstellen
- Bei Änderungen automatisch bereitstellen
- Den Build-Status bei GitHub-Commits anzeigen
So funktioniert sie
Wenn Sie ein Projekt einrichten, führt Jamdesk Sie durch die Verbindung mit GitHub. Es gibt zwei Möglichkeiten.
Starter-Dokumentations-Repository erstellen (Standard für neue Projekte)
Autorisieren Sie Jamdesk, damit ein Repository in Ihrem Konto oder Ihrer Organisation erstellt werden kann.
Wählen Sie Ihr persönliches Konto oder eine Organisation aus. Jamdesk erstellt ein neues Repository mit einer vorausgefüllten Starter-Dokumentation.
Installieren Sie die Jamdesk GitHub App (oder gewähren Sie ihr Zugriff auf das neue Repository), damit sie Ihre Dokumentation erstellen und automatisch bereitstellen kann.
Jeder Push in Ihren konfigurierten Branch löst automatisch eine Bereitstellung aus. Passen Sie die Starter-Dokumentation an, sobald Sie bereit sind.
Vorhandenes Repository verbinden
Sie haben bereits ein Dokumentations-Repository? Installieren Sie die Jamdesk GitHub App, gewähren Sie ihr Zugriff auf dieses Repository und wählen Sie anschließend das Repository und den Branch in Jamdesk unter Project Settings → Git Repository aus. Danach funktioniert alles auf dieselbe Weise.
Eine App, mehrere Projekte
Eine einzelne GitHub-App-Installation kann mehrere Jamdesk-Projekte versorgen:
- Installieren Sie die App einmal in Ihrem Konto oder Ihrer Organisation
- Verbinden Sie unterschiedliche Repositories mit unterschiedlichen Jamdesk-Projekten
- Jedes Projekt verfügt über eine eigene Branch- und Pfadkonfiguration
Bei Organisationen muss ein Administrator die GitHub App nur einmal installieren. Danach kann jedes Teammitglied Jamdesk-Projekte mit Repositories erstellen, auf die die App Zugriff hat.
Persönliches GitHub-Konto (Benutzerebene)
Durch die Verknüpfung Ihres persönlichen GitHub-Kontos wird Ihre GitHub-Identität mit Ihrem Jamdesk-Profil verbunden. Dies ist von der GitHub App unabhängig.
Was es tut
- Identifiziert Sie – Verknüpft Ihren GitHub-Benutzernamen mit Ihrem Jamdesk-Konto
- Ordnet Builds zu – Zeigt, wer die jeweilige Bereitstellung ausgelöst hat
- Sichtbarkeit im Team – Andere Teammitglieder können sehen, wer Änderungen vorgenommen hat
Warum Sie es benötigen
Wenn Sie zu GitHub pushen, muss Jamdesk feststellen, welcher Benutzer den Build ausgelöst hat. Ohne verknüpftes Konto gilt:
- Jamdesk versucht ersatzweise eine Zuordnung anhand der E-Mail-Adresse
- Wenn sich Ihre Git-Commit-E-Mail von Ihrer Jamdesk-E-Mail unterscheidet, schlägt die Zuordnung fehl
- In der Build-Historie kann für Ihre Commits „Unbekannter Benutzer“ angezeigt werden
Häufiges Problem: Ihr Git ist mit einer persönlichen E-Mail-Adresse konfiguriert, Sie haben sich bei Jamdesk jedoch mit einer geschäftlichen E-Mail-Adresse registriert. Verknüpfen Sie Ihr GitHub-Konto, um eine korrekte Zuordnung sicherzustellen.
Git-E-Mail prüfen
git config user.email
git config --global user.email "you@company.com"Verwenden Sie dieselbe E-Mail-Adresse, die in Ihrem Jamdesk-Konto angezeigt wird, um die Zuordnung als „Unbekannter Benutzer“ in der Build-Historie zu vermeiden.
Konto verknüpfen
Klicken Sie oben rechts auf Ihren Avatar und wählen Sie anschließend User Settings aus.
Scrollen Sie zur Karte GitHub Account.
Ein Popup mit GitHub wird geöffnet. Autorisieren Sie Jamdesk, Ihr Profil zu lesen.
Ihr GitHub-Benutzername wird in Ihrem Jamdesk-Profil angezeigt.
Zusammenspiel der Verbindungen
Stellen Sie sie sich als zwei separate Schlüssel vor:
| Schlüssel | Öffnet | Gehört zu |
|---|---|---|
| GitHub App | Zugriff auf Repositories | Projekt/Organisation |
| Persönliche Verknüpfung | Ihre Identität | Einzelner Benutzer |
Beispiel: Team
Stellen Sie sich ein Team mit 3 Entwicklern vor, die an der Unternehmensdokumentation arbeiten:
- Administrator installiert die GitHub App in der Organisation
- Administrator erstellt ein Jamdesk-Projekt, das mit dem Dokumentations-Repository verbunden ist
- Jeder Entwickler verknüpft sein persönliches Konto
Wenn nun ein Entwickler pusht:
- Die GitHub App ermöglicht Jamdesk, das Repository zu lesen und den Build zu erstellen
- Die persönliche Verknüpfung identifiziert, wer den Build ausgelöst hat
Beispiel: Einzelner Entwickler
Auch als einzelner Entwickler erfüllen beide Verbindungen unterschiedliche Zwecke:
- GitHub App – Verbindet Ihr Repository mit Jamdesk
- Persönliche Verknüpfung – Stellt sicher, dass Ihre Commits in der Build-Historie unter Ihrem Namen angezeigt werden
GitHub trennen und Verknüpfung aufheben
Jede Aktion entfernt einen anderen Teil des Zugriffs. Hier erfahren Sie, was jeweils betroffen ist.
GitHub trennen (Project Settings)
Was geschieht: Die Repository-Verbindung wird aus einem einzelnen Jamdesk-Projekt entfernt.
Auswirkungen:
- Automatische Bereitstellungen werden für dieses Projekt beendet
- Die GitHub App bleibt in GitHub installiert
- Andere Jamdesk-Projekte sind nicht betroffen
- Ihre persönliche Kontoverknüpfung bleibt bestehen
Wann verwenden: Wenn Sie ein anderes Repository verbinden oder Bereitstellungen vorübergehend anhalten möchten.
Erneut verbinden: Wechseln Sie zu Project Settings → Git Repository und wählen Sie ein Repository aus.
GitHub-Verknüpfung aufheben (User Settings)
Was geschieht: Ihre GitHub-Identität wird aus Ihrem Jamdesk-Profil entfernt.
Auswirkungen:
- Ihr GitHub-Benutzername wird nicht mehr in Ihrem Profil angezeigt
- Die Build-Zuordnung fällt auf den Abgleich per E-Mail zurück
- Alle Repository-Verbindungen bleiben bestehen
- Die GitHub App bleibt installiert
Wann verwenden: Wenn Sie ein anderes GitHub-Konto verknüpfen oder die Verbindung entfernen möchten.
Erneut verknüpfen: Wechseln Sie zu User Settings → GitHub Account → Link GitHub Account.
GitHub App deinstallieren (in GitHub)
Was geschieht: Der Zugriff von Jamdesk auf Ihr GitHub-Konto wird vollständig entfernt.
Auswirkungen:
- Alle Jamdesk-Projekte, die diese Installation verwenden, verlieren den Zugriff
- Automatische Bereitstellungen werden für alle betroffenen Projekte beendet
- Webhooks werden entfernt
- Persönliche Kontoverknüpfungen bleiben bestehen
Deinstallieren Sie die GitHub App nur, wenn Sie den Jamdesk-Zugriff auf ALLE Ihre Repositories entfernen möchten. Dies betrifft jedes Jamdesk-Projekt, das mit Ihrem GitHub-Konto verbunden ist.
Deinstallation:
- Gehen Sie zu GitHub Settings → Applications → Installed GitHub Apps
- Suchen Sie nach „Jamdesk“ und klicken Sie auf Configure
- Scrollen Sie nach unten und klicken Sie auf Uninstall
Schnellreferenz
| Aktion | Ort | Umfang | Umkehrbar? |
|---|---|---|---|
| GitHub trennen | Project Settings → Git Repository | Einzelnes Projekt | Ja – jederzeit erneut verbinden |
| GitHub-Verknüpfung aufheben | User Settings → GitHub Account | Ihr Konto | Ja – jederzeit erneut verknüpfen |
| GitHub App deinstallieren | GitHub Settings | Alle Projekte | Ja – erneut installieren |
Fehlerbehebung
„Jamdesk ist bereits installiert?“
Wenn Sie die Jamdesk GitHub App bereits installiert haben, gelangen Sie durch Klicken auf „Install GitHub App“ zur GitHub-Einstellungsseite statt zur Installationsseite. Das ist normal. So schließen Sie die Einrichtung ab:
Scrollen Sie auf der GitHub-Einstellungsseite zum Bereich Repository access.
Wenn die Save-Schaltfläche deaktiviert (ausgegraut) ist, wechseln Sie von „All repositories“ zu „Only select repositories“ und anschließend wieder zurück.
Klicken Sie auf die grüne Schaltfläche Save. Jamdesk erkennt die Änderung und setzt die Einrichtung fort.
Popup wird blockiert
Wenn das GitHub-Popup nicht geöffnet wird, wurde es möglicherweise von Ihrem Browser blockiert. Suchen Sie in der Adressleiste nach einem Symbol für den Popup-Blocker, erlauben Sie Popups von Jamdesk und klicken Sie anschließend auf Try Again.
„Meine Builds zeigen ‚Unbekannter Benutzer‘“
Ihr persönliches GitHub-Konto ist nicht verknüpft. Gehen Sie zu User Settings → Link GitHub Account.
„Repository wird nicht angezeigt“
Die GitHub App hat keinen Zugriff auf dieses Repository. Gehen Sie zu GitHub Settings, suchen Sie nach Jamdesk und fügen Sie das Repository hinzu.
„Builds werden nicht ausgelöst“
- Prüfen Sie, ob das Repository unter Project Settings → Git Repository verbunden ist
- Vergewissern Sie sich, dass Sie in den konfigurierten Branch pushen
- Prüfen Sie die Webhook-Zustellung in den GitHub-Repository-Einstellungen
„Ich kann nicht auf Organisations-Repositories zugreifen“
Ein Organisationsadministrator muss die Installation der GitHub App genehmigen. Bitten Sie Ihren Administrator, Jamdesk in den Organisationseinstellungen zu installieren oder zu genehmigen.
„GitHub leitet mich immer wieder zur Jamdesk-App-Seite zurück“
Ihr Unternehmen verwaltet wahrscheinlich Ihr GitHub-Konto, und GitHub erlaubt diesen Konten nicht, Apps im eigenen Konto zu installieren. Siehe unternehmensverwaltete GitHub-Konten, um das Problem zu beheben.