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.
Kurz gesagt: Die GitHub App ermöglicht Jamdesk den Zugriff auf Ihr Repository. Durch die Verknüpfung Ihres persönlichen Kontos werden Ihre Commits Ihnen zugeordnet.
Übersicht
| Verbindung | Zweck | Umfang | Erforderlich? |
|---|---|---|---|
| GitHub App | Repository-Zugriff und Webhooks | Pro Projekt | Ja |
| Persönliches Konto | Benutzeridentität und Zuordnung | Pro Benutzer | Empfohlen |
GitHub App (Projektebene)
Die Jamdesk GitHub App ist 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 einem Push von Ä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-Repository für Dokumentation 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 vorbereiteten Starter-Dokumenten.
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 Repository für Ihre Dokumentation? 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 unterstützen:
- Installieren Sie die App einmal in Ihrem Konto oder Ihrer Organisation
- Verbinden Sie verschiedene Repositories mit verschiedenen Jamdesk-Projekten
- Jedes Projekt verfügt über eine eigene Branch- und Pfadkonfiguration
Für Organisationen muss ein Administrator die GitHub App nur einmal installieren. Anschließend 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 verknüpft. Dies ist unabhängig von der GitHub App.
Was es tut
- Identifiziert Sie – Verknüpft Ihren GitHub-Benutzernamen mit Ihrem Jamdesk-Konto
- Ordnet Builds zu – Zeigt an, wer die jeweilige Bereitstellung ausgelöst hat
- Macht Teamsichtbarkeit möglich – Andere Teammitglieder können sehen, wer Änderungen vorgenommen hat
Warum Sie es benötigen
Wenn Sie zu GitHub pushen, muss Jamdesk ermitteln, welcher Benutzer den Build ausgelöst hat. Ohne verknüpftes Konto gilt:
- Jamdesk versucht, die Zuordnung anhand der E-Mail-Adresse vorzunehmen
- Wenn sich Ihre Git-Commit-E-Mail-Adresse von Ihrer Jamdesk-E-Mail-Adresse unterscheidet, schlägt die Zuordnung fehl
- In der Build-Historie wird für Ihre Commits möglicherweise „Unknown user“ angezeigt
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-Adresse überprüfen
git config user.email
git config --global user.email "you@company.com"Verwenden Sie dieselbe E-Mail-Adresse wie in Ihrem Jamdesk-Konto, damit in der Build-Historie keine Zuordnung als „Unknown user“ erfolgt.
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.
So arbeiten sie zusammen
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 |
Teambeispiel
Betrachten Sie ein Team mit 3 Entwicklern, die an der Unternehmensdokumentation arbeiten:
- Administrator installiert die GitHub App in der Organisation
- Administrator erstellt ein Jamdesk-Projekt, das mit dem Repository für die Dokumentation verbunden ist
- Jeder Entwickler verknüpft sein persönliches Konto
Wenn nun ein beliebiger 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 für einen einzelnen 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-Verbindung trennen und Verknüpfung aufheben
Jede Aktion entfernt einen anderen Teil des Zugriffs. Im Folgenden 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 stoppen 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 erfolgt wieder anhand der E-Mail-Adresse
- 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 ALL Ihre Repositories entfernen möchten. Dies betrifft jedes Jamdesk-Projekt, das mit Ihrem GitHub-Konto verbunden ist.
So deinstallieren Sie die App:
- 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 einen Klick auf „Install GitHub App“ zur Einstellungsseite von GitHub statt zur Installationsseite. Das ist normal. So schließen Sie die Einrichtung ab:
Scrollen Sie auf der GitHub-Einstellungsseite zum Abschnitt Repository access.
Wenn die Schaltfläche Save 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, hat Ihr Browser es möglicherweise blockiert. Suchen Sie in der Adressleiste nach dem Symbol für den Popup-Blocker, erlauben Sie Popups von Jamdesk und klicken Sie anschließend auf Try Again.
„Meine Builds zeigen ‚Unknown user‘“
Ihr persönliches GitHub-Konto ist nicht verknüpft. Wechseln 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.