GitHub-Integration
Jamdesk nutzt zwei GitHub-Verbindungen: eine GitHub App für den Repository-Zugriff und eine persönliche Kontoverknüpfung für die Build-Zuordnung.
Jamdesk nutzt zwei getrennte GitHub-Verbindungen mit unterschiedlichen Aufgaben.
Kurz gesagt: Die GitHub App gibt Jamdesk Zugriff auf dein Repository. Das Verknüpfen deines persönlichen Kontos ordnet deine Commits dir zu.
Bitbucket-Cloud-Projekte funktionieren anders. Eine einzige OAuth-Autorisierung deckt den Repository-Zugriff, den Webhook und die Build-Zuordnung ab. Siehe Bitbucket verbinden.
Übersicht
| Verbindung | Zweck | Geltungsbereich | 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 deinem GitHub-Konto oder deiner Organisation installiert. Sie gibt Jamdesk Zugriff auf die Repositories, die du auswählst.
Was sie tut
- Liest Repository-Inhalte: klont deine Dokumentation, um sie zu bauen
- Empfängt Webhooks: wird benachrichtigt, wenn du Änderungen pushst
- Meldet den Build-Status: zeigt den Bereitstellungsstatus bei Commits an
Warum Sie sie benötigen
Ohne installierte GitHub App kann Jamdesk nicht:
- auf dein Repository zugreifen, um die Dokumentation zu bauen
- bei Pushes automatisch bereitstellen
- den Build-Status bei GitHub-Commits anzeigen
So funktioniert sie
Die Projekteinrichtung führt dich durch die GitHub-Verbindung. Wähle einen von zwei Wegen.
Starter-Dokumentations-Repository erstellen (Standard für neue Projekte)
Autorisiere Jamdesk, ein Repository in deinem Konto oder deiner Organisation zu erstellen.
Wähle dein persönliches Konto oder eine Organisation. Jamdesk erstellt ein neues Repository mit vorausgefüllter Starter-Dokumentation.
Installiere die Jamdesk GitHub App (oder gewähre ihr Zugriff auf das neue Repository). Die App baut deine Dokumentation und stellt sie automatisch bereit.
Jeder Push auf deinen konfigurierten Branch löst automatisch eine Bereitstellung aus. Passe die Starter-Dokumentation an, wann immer du bereit bist.
Vorhandenes Repository verbinden
Installiere die Jamdesk GitHub App und gewähre ihr Zugriff auf dein Dokumentations-Repository. Wähle dann in Jamdesk unter Projekteinstellungen → Git-Repository das Repository und den Branch aus. Der Rest funktioniert genauso.
Eine App, mehrere Projekte
Eine GitHub-App-Installation kann mehrere Jamdesk-Projekte bedienen:
- Installiere die App einmal in deinem Konto oder deiner Organisation
- Verbinde verschiedene Repositories mit verschiedenen Jamdesk-Projekten
- Jedes Projekt hat eine eigene Branch- und Pfadkonfiguration
Ein Organisations-Administrator installiert die GitHub App einmal. Anschließend kann jedes Teammitglied Jamdesk-Projekte aus Repositories erstellen, auf die die App zugreifen kann.
Persönliches GitHub-Konto (Benutzerebene)
Das Verknüpfen deines persönlichen GitHub-Kontos verbindet deine GitHub-Identität mit deinem Jamdesk-Profil. Das ist getrennt von der GitHub App.
Was es tut
- Identifiziert dich: verknüpft deinen GitHub-Benutzernamen mit deinem Jamdesk-Konto
- Ordnet Builds zu: zeigt an, wer jede Bereitstellung ausgelöst hat
- Team-Transparenz: Teammitglieder sehen, wer Änderungen vorgenommen hat
Warum Sie es benötigen
Jamdesk muss jeden Push einem Benutzer zuordnen. Ohne verknüpftes Konto gilt Folgendes:
- Jamdesk weicht auf den Abgleich per E-Mail-Adresse aus
- Wenn deine Git-Commit-E-Mail von deiner Jamdesk-E-Mail abweicht, schlägt die Zuordnung fehl
- Der Build-Verlauf zeigt für deine Commits möglicherweise „Unbekannter Benutzer“ an
Häufiges Problem: Git verwendet eine private E-Mail. Dein Jamdesk-Konto verwendet eine geschäftliche E-Mail. Verknüpfe dein GitHub-Konto, um die Zuordnung zu reparieren.
Git-E-Mail prüfen
git config user.email
git config --global user.email "you@company.com"Setze sie auf die E-Mail deines Jamdesk-Kontos. Eine Abweichung führt im Build-Verlauf zu „Unbekannter Benutzer“.
Konto verknüpfen
Klicke oben rechts auf dein Avatar-Bild und wähle Benutzereinstellungen.
Scrolle zur Karte GitHub-Konto.
Ein Popup öffnet GitHub. Autorisiere Jamdesk, dein Profil zu lesen.
Dein GitHub-Benutzername erscheint in deinem Jamdesk-Profil.
Zusammenspiel der Verbindungen
Stell sie dir als zwei getrennte Schlüssel vor:
| Schlüssel | Öffnet | Besitz von |
|---|---|---|
| GitHub App | Zugriff auf Repositories | Projekt/Organisation |
| Persönliche Verknüpfung | Deine Identität | Einzelner Benutzer |
Beispiel: Team
Ein Team aus 3 Entwicklern arbeitet an der Unternehmensdokumentation:
- Der Admin installiert die GitHub App in der Organisation
- Der Admin 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 erlaubt Jamdesk, das Repository zu lesen und zu bauen
- Die persönliche Verknüpfung identifiziert, wer den Build ausgelöst hat
Beispiel: Einzelner Entwickler
Auch Einzelentwickler brauchen die beiden Verbindungen:
- GitHub App: verbindet dein Repository mit Jamdesk
- Persönliche Verknüpfung: zeigt deinen Namen bei deinen Commits im Build-Verlauf
GitHub trennen und Verknüpfung aufheben
Jede Aktion entfernt einen anderen Zugriff.
GitHub trennen (Project Settings)
Was es tut: Entfernt die Repository-Verbindung aus einem einzelnen Jamdesk-Projekt.
Auswirkungen:
- Automatische Bereitstellungen für dieses Projekt werden beendet
- Die GitHub App bleibt auf GitHub installiert
- Andere Jamdesk-Projekte sind nicht betroffen
- Deine persönliche Kontoverknüpfung bleibt unberührt
Wann verwenden: Du möchtest ein anderes Repository verbinden oder Bereitstellungen vorübergehend stoppen.
So verbindest du erneut: Gehe zu Projekteinstellungen → Git-Repository und wähle ein Repository aus.
GitHub-Verknüpfung aufheben (User Settings)
Was es tut: Entfernt deine GitHub-Identität aus deinem Jamdesk-Profil.
Auswirkungen:
- Dein GitHub-Benutzername erscheint nicht mehr in deinem Profil
- Die Build-Zuordnung weicht auf den E-Mail-Abgleich aus
- Alle Repository-Verbindungen bleiben bestehen
- Die GitHub App bleibt installiert
Wann verwenden: Du möchtest ein anderes GitHub-Konto verknüpfen oder die Verbindung entfernen.
So verknüpfst du erneut: Gehe zu Benutzereinstellungen → GitHub-Konto → GitHub-Konto verknüpfen.
GitHub App deinstallieren (in GitHub)
Was es tut: Entfernt Jamdesks Zugriff auf dein GitHub-Konto.
Auswirkungen:
- Alle Jamdesk-Projekte, die diese Installation nutzen, verlieren den Zugriff
- Automatische Bereitstellungen werden für alle betroffenen Projekte beendet
- Webhooks werden entfernt
- Persönliche Kontoverknüpfungen bleiben unberührt
Deinstalliere die GitHub App nur, wenn du Jamdesks Zugriff auf jedes Repository entfernen möchtest. Dies betrifft jedes Jamdesk-Projekt, das mit deinem GitHub-Konto verbunden ist.
So deinstallierst du:
- Gehe zu GitHub-Einstellungen → Anwendungen → Installierte GitHub Apps
- Finde „Jamdesk“ und klicke auf Konfigurieren
- Scrolle nach unten und klicke auf Deinstallieren
Schnellreferenz
| Aktion | Ort | Geltungsbereich | Umkehrbar? |
|---|---|---|---|
| GitHub trennen | Projekteinstellungen → Git-Repository | Einzelnes Projekt | Ja – jederzeit neu verbinden |
| GitHub-Verknüpfung aufheben | Benutzereinstellungen → GitHub-Konto | Dein Konto | Ja – jederzeit neu verknüpfen |
| GitHub App deinstallieren | GitHub-Einstellungen | Alle Projekte | Ja – neu installieren |
Fehlerbehebung
„Jamdesk ist bereits installiert?“
Wenn du die Jamdesk GitHub App bereits installiert hast, öffnet „GitHub App installieren“ die GitHub-Einstellungsseite statt der Installationsseite. Schließe die Einrichtung dort ab:
Scrolle auf der GitHub-Einstellungsseite zum Abschnitt Repository-Zugriff.
Wenn die Schaltfläche Speichern deaktiviert (ausgegraut) ist, wechsle von „Alle Repositories“ zu „Nur ausgewählte Repositories“ und dann wieder zurück.
Klicke auf die grüne Schaltfläche Speichern. Jamdesk erkennt die Änderung und setzt die Einrichtung fort.
Popup wird blockiert
Wenn sich das GitHub-Popup nicht öffnet, hat dein Browser es möglicherweise blockiert. Suche in der Adressleiste nach einem Symbol für den Popup-Blocker, erlaube Popups von Jamdesk und klicke dann auf Erneut versuchen.
„Meine Builds zeigen ‚Unbekannter Benutzer‘“
Dein persönliches GitHub-Konto ist nicht verknüpft. Gehe zu Benutzereinstellungen → GitHub-Konto verknüpfen.
„Repository wird nicht angezeigt“
Die GitHub App hat keinen Zugriff auf dieses Repository. Gehe zu GitHub-Einstellungen, finde Jamdesk und füge das Repository hinzu.
„Builds werden nicht ausgelöst“
- Prüfe, ob das Repository unter Projekteinstellungen → Git-Repository verbunden ist
- Vergewissere dich, dass du auf den konfigurierten Branch pushst
- Prüfe die Webhook-Zustellung in den Repository-Einstellungen auf GitHub
Wenn das alles stimmt, ist die Person, die gepusht hat, möglicherweise kein Mitglied des Projekts. Jamdesk baut einen Push nur, wenn er von einem Projektmitglied stammt. Der Pusher wird über sein verknüpftes GitHub-Konto zugeordnet oder über eine Commit-E-Mail, die mit der E-Mail übereinstimmt, mit der er sich bei Jamdesk anmeldet.
Ohne Zuordnung schlägt der Build mit Angabe des Grundes fehl. Der Projektinhaber erhält eine E-Mail, höchstens eine pro Woche und Person. Ein Push, der nichts in deinem Docs-Ordner ändert, sendet keine E-Mail.
Lade die Person unter Projekteinstellungen → Mitglieder mit ihrer Commit-E-Mail ein. Sie muss sich bei Jamdesk mit dieser E-Mail anmelden, um die Einladung anzunehmen. Ist sie bereits Mitglied, kann sie stattdessen ihr GitHub-Konto verknüpfen in den Benutzereinstellungen.
„Ich kann nicht auf Organisations-Repositories zugreifen“
Ein Organisations-Administrator muss die Installation der GitHub App genehmigen. Bitte deinen Administrator, Jamdesk in den Organisationseinstellungen zu installieren oder zu genehmigen.
„GitHub leitet mich immer wieder zur Jamdesk-App-Seite zurück“
Dein Unternehmen verwaltet dein GitHub-Konto wahrscheinlich selbst. GitHub erlaubt verwalteten Konten nicht, Apps auf sich selbst zu installieren. Die Lösung findest du unter unternehmensverwaltete GitHub-Konten.