Bitbucket verbinden

Jamdesk baut aus Bitbucket Cloud genauso wie aus GitHub. Autorisiere Jamdesk einmal. Jeder Push auf den von dir gewählten Branch veröffentlicht dann eine neue Version deiner Seite.

Deine Doku liegt auf GitHub? Lies stattdessen GitHub verbinden. Ein Projekt ist immer mit genau einem Git-Anbieter verbunden.

Vor dem Start

Ein Bitbucket-Cloud-Konto. Bitbucket Data Center und Bitbucket Server werden nicht unterstützt.
Admin-Berechtigung für das Repository. Jamdesk installiert einen Push-Webhook im Repository. Bitbucket erlaubt das nur Repository-Admins.
Ein Projekt ohne verbundenes Repository. Um ein Projekt von GitHub zu Bitbucket zu verschieben, trenne zuerst GitHub unter Settings → Git Repository.
Pop-ups für das Dashboard erlaubt. Die Bitbucket-Anmeldung öffnet sich in einem Pop-up-Fenster.

Was Jamdesk anfordert

Jamdesk verbindet sich über einen Bitbucket-OAuth-Consumer. Bitbucket listet die angeforderten Berechtigungen bei der Anmeldung auf:

Berechtigung	Warum Jamdesk sie braucht
Account: Read	Speichert, welches Bitbucket-Konto das Projekt verbunden hat. Jamdesk erkennt Pushes von diesem Konto
Repositories: Read	Klont dein Repository, um es zu bauen. Listet deine Repositories auf, wenn du das Repository wechselst
Repositories: Write	Erstellt das Starter-Docs-Repository und pusht die Startinhalte hinein
Webhooks: Read and write	Installiert den Push-Webhook, der Builds auslöst. Entfernt ihn, wenn sich die Verbindung ändert

Jamdesk speichert den Refresh-Token verschlüsselt mit Google Cloud KMS. Der Zugriff wird automatisch erneuert. Du brauchst kein App-Passwort und kein persönliches Access-Token.

Bitbucket für ein Projekt auswählen

Öffne das Projekt im Dashboard. Solange kein Repository verbunden ist, zeigt die Projektseite eine Karte Connect your docs repository mit zwei Optionen. Klicke auf Bitbucket.

Lass Jamdesk ein Starter-Repository anlegen oder verbinde ein bereits vorhandenes.

Starter-Doku-Repository erstellen

Workspace eingeben

Gib den Workspace-Slug ein, also den Teil deiner Bitbucket-URL nach bitbucket.org/. Für https://bitbucket.org/acme/ gibst du acme ein.

Mit Bitbucket anmelden

Klicke auf Sign in with Bitbucket. Ein Pop-up öffnet sich auf bitbucket.org. Prüfe die Berechtigungen und erteile den Zugriff.

Auf das Repository warten

Jamdesk erstellt ein Repository in diesem Workspace, benannt nach deinem Projekt mit dem Suffix -docs. Ein Projekt namens Acme Docs erhält acme-docs. Ist dieser Name belegt, verwendet Jamdesk stattdessen -documentation.

Das Repository startet auf dem Branch main mit bereits vorhandener Starter-Dokumentation. Jamdesk installiert den Webhook und führt den ersten Build aus.

Wenn die Karte Starter docs created and connected! anzeigt, ist deine Seite auf dem Weg. Klone das neue Repository und beginne mit dem Bearbeiten.

Vorhandenes Repository verbinden

Repository eingeben

Gib das Repository als workspace/repository-slug ein, zum Beispiel acme/developer-docs. Workspace und Slug entnimmst du der Repository-URL auf bitbucket.org.

Branch wählen

Gib den Branch ein, der bereitgestellt werden soll. Lass das Feld leer, um main zu verwenden.

Bitbucket verbinden

Klicke auf Connect Bitbucket und erteile den Zugriff im Pop-up. Danach prüft Jamdesk:

Ob dein Konto Admin-Berechtigung für das Repository hat
Ob im Repository-Root oder einem Unterordner (bis zu drei Ebenen tief) eine docs.json liegt
Installiert den Push-Webhook
Registriert deine Adresse yourproject.jamdesk.app und startet den ersten Build

Das Repository braucht eine gültige docs.json auf dem angegebenen Branch. Findet Jamdesk keine, füge eine hinzu und verbinde erneut. Findet es mehrere, behalte pro Repository nur eine docs.json. Ein Repository mit einer mint.json ist ein Mintlify-Projekt: Führe jamdesk migrate darauf aus, pushe und verbinde erneut.

Die Karte des verbundenen Projekts zeigt das Repository, den Branch und ein Badge Connected.

Automatische Builds bei Pushes

Jeder Push auf den verbundenen Branch startet einen Build:

git add .
git commit -m "Update API documentation"
git push origin main

Bitbucket sendet ein Push-Ereignis an den Webhook von Jamdesk. Jamdesk baut diesen Commit genau einmal. Eine doppelte Zustellung desselben Commits startet keinen zweiten Build. Das Löschen eines Branches löst nie einen Build aus.

Bitbucket wiederholt eine fehlgeschlagene Webhook-Zustellung nicht. Jamdesk prüft außerdem alle fünf Minuten die Spitze deines Branches. Es baut jeden Commit, den es noch nicht gebaut hat. Ein Push, dessen Webhook verloren ging, wird trotzdem innerhalb weniger Minuten bereitgestellt.

Manuelle Builds aus dem Dashboard funktionieren wie bei GitHub-Projekten. Siehe Builds auslösen.

Welche Pushes lösen einen Build aus

Jamdesk baut Pushes des Bitbucket-Kontos, das das Projekt verbunden oder zuletzt neu autorisiert hat. Ein Push von einem anderen Konto erscheint in der Build-Liste als fehlgeschlagener Build mit einem Autorisierungsfehler. Es wird nichts bereitgestellt.

Bitbucket-Projekte erlauben derzeit noch nicht, ein persönliches Konto unter User Settings zu verknüpfen oder zusätzliche Konten unter Settings → Automation accounts zu autorisieren. Wenn mehrere Personen auf den Deploy-Branch pushen, verbinde das Projekt mit dem Konto, das in diesen Branch mergt, oder lass dieses Konto pushen.

Repository oder Branch ändern

Klicke auf der Projektkarte auf Change repository. Jamdesk listet die Repositories auf, auf die dein Bitbucket-Konto zugreifen kann. Wähle ein Repository und einen Branch und bestätige.

Jamdesk installiert den Webhook im neuen Repository, entfernt ihn aus dem alten und startet einen Build.

Ein Repository-Wechsel wirkt sich auf deine Live-Doku aus, sobald der Build fertig ist. Das neue Repository muss eine gültige docs.json enthalten.

Abgelaufene Verbindung erneut autorisieren

Bitbucket widerruft den Zugriff von Jamdesk, wenn der verbindende Benutzer Jamdesk in Bitbucket entfernt oder wenn der Refresh-Token mehrere Monate ungenutzt bleibt. Die Projektkarte zeigt dann ein Badge Needs reauth und die Meldung Bitbucket connection needs attention.

Klicke auf Re-authorize und melde dich erneut an. Builds laufen wieder. Die nächste Fünf-Minuten-Prüfung erfasst den neuesten Commit auf deinem Branch.

Unterschiede zwischen Bitbucket und GitHub

Bitbucket-Projekte verwenden eine OAuth-Autorisierung. GitHub-Projekte verwenden eine GitHub App plus optional eine persönliche Kontoverknüpfung. Der Großteil der Plattform funktioniert gleich. Die Unterschiede:

Funktion	GitHub	Bitbucket Cloud
Build bei Push	Webhook	Webhook, plus Fünf-Minuten-Prüfung für verlorene Zustellungen
Starter-Docs-Repository	Ja	Ja
Eigene Domains, Hosting im Unterpfad, manuelle Builds, CLI-Deploys	Ja	Ja
Build-Status an Commits	Am Commit in GitHub sichtbar	Nur im Dashboard
Verknüpfung persönlicher Konten für Build-Zuordnung	User Settings	Nicht verfügbar. Builds werden dem verbindenden Konto zugeordnet
Allowlist für Automatisierungskonten	Settings → Automation accounts	Noch nicht
Web-Editor	Ja	Noch nicht
Fix with AI	Ja	Noch nicht
KI-Übersetzung	Ja	Noch nicht

Das Löschen eines Projekts entfernt den Webhook aus deinem Repository und widerruft den Zugriff von Jamdesk.

Fehlerbehebung

„Your Bitbucket account lacks admin permission on this repository“

Jamdesk braucht Admin-Zugriff, um den Webhook zu installieren. Bitte einen Workspace-Admin, dir Admin-Berechtigung für das Repository zu erteilen, oder lass einen Admin das Projekt verbinden.

„We could not find docs.json in this repository“

Jamdesk hat im Root und bis zu drei Ordner tief auf dem angegebenen Branch gesucht. Füge eine docs.json hinzu, pushe sie auf diesen Branch und verbinde erneut. Siehe die docs.json-Referenz.

„Multiple docs.json files were found“

Behalte pro Repository nur eine docs.json. Entferne oder benenne die anderen um und verbinde dann erneut.

„This repository looks like a Mintlify project“

Das Repository enthält eine mint.json. Führe jamdesk migrate aus, um sie zu konvertieren, pushe das Ergebnis und verbinde erneut.

Erlaube Pop-ups für das Dashboard in deinem Browser und klicke dann erneut auf Sign in with Bitbucket oder Connect Bitbucket.

Builds werden nicht ausgelöst

Öffne in Bitbucket Repository settings → Webhooks und prüfe, ob der Jamdesk-Webhook vorhanden und aktiv ist
Prüfe, ob du auf den konfigurierten Branch pushst
Warte fünf Minuten. Die periodische Prüfung baut jeden Commit, den der Webhook verpasst hat
Zeigt die Projektkarte Needs reauth, autorisiere die Verbindung neu
Kam der Push von einem anderen Bitbucket-Konto, siehe Welche Pushes einen Build auslösen

Wie geht es weiter?

Projekt erstellen

Richte ein neues Jamdesk-Projekt ein

Eigene Domains

Stelle deine Doku über deine eigene Domain bereit

Builds auslösen

Alle Wege, wie ein Build starten kann

Verzeichnisstruktur

Organisiere deine Doku für Wachstum