Connecter Bitbucket

Jamdesk construit à partir de Bitbucket Cloud de la même façon qu'à partir de GitHub : vous autorisez Jamdesk une fois, et chaque push vers la branche choisie publie une nouvelle version de votre site. Cette page s'adresse aux équipes dont la documentation se trouve sur Bitbucket, ou qui souhaitent garder leurs docs à proximité du code qui s'y trouve déjà.

Avant de commencer

• Un compte Bitbucket Cloud. Bitbucket Data Center et Bitbucket Server ne sont pas pris en charge.
• La permission admin sur le dépôt. Jamdesk installe un webhook de push sur le dépôt, et Bitbucket ne permet qu'aux administrateurs du dépôt de créer des webhooks.
• Un projet sans dépôt connecté. Pour déplacer un projet de GitHub vers Bitbucket, déconnectez d'abord GitHub sous Settings → Git Repository.
• Les popups autorisés pour le dashboard. La connexion Bitbucket s'ouvre dans une fenêtre popup.

Ce que demande Jamdesk

Jamdesk se connecte via un consommateur OAuth Bitbucket. Lors de la connexion, Bitbucket liste les permissions demandées :

Jamdesk stocke le jeton de rafraîchissement obtenu, chiffré avec Google Cloud KMS, et renouvelle l'accès de lui-même. Vous n'avez besoin ni d'un mot de passe d'application ni d'un jeton d'accès personnel.

Choisir Bitbucket pour un projet

Ouvrez le projet dans le dashboard. Tant qu'aucun dépôt n'est connecté, la page du projet affiche une carte Connect your docs repository avec deux options. Cliquez sur Bitbucket.

De là, vous pouvez soit laisser Jamdesk créer un dépôt de démarrage, soit en connecter un que vous possédez déjà.

Créer un dépôt de documentation de démarrage

Quand la carte affiche Starter docs created and connected!, votre site est en cours de mise en ligne. Clonez le nouveau dépôt et commencez à éditer.

Connecter un dépôt existant

Le dépôt a besoin d'un docs.json valide sur la branche saisie. Si Jamdesk n'en trouve aucun, ajoutez-en un et reconnectez-vous. S'il en trouve plusieurs, ne gardez qu'un seul docs.json par dépôt. Un dépôt contenant un mint.json est un projet Mintlify : exécutez jamdesk migrate dessus, poussez, puis reconnectez-vous.

Une fois connecté, la carte du projet affiche le dépôt, la branche et un badge Connected.

Builds automatiques au push

Chaque push vers la branche connectée déclenche un build :

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

Bitbucket délivre un événement de push au webhook de Jamdesk, et Jamdesk construit ce commit une seule fois. Une livraison en double du même commit ne démarre pas un second build, et la suppression d'une branche ne déclenche jamais de build.

Bitbucket ne retente pas la livraison d'un webhook en échec. Pour pallier cela, Jamdesk vérifie aussi la pointe de votre branche toutes les cinq minutes et construit tout commit qu'il n'a pas encore construit. Un push dont le webhook a été perdu est tout de même déployé en quelques minutes.

Les builds manuels depuis le dashboard fonctionnent de la même façon que pour les projets GitHub. Consultez Déclencher des builds.

Quels push déclenchent un build

Jamdesk construit les push effectués par le compte Bitbucket qui a connecté le projet, ou qui l'a réautorisé en dernier. Un push provenant de tout autre compte apparaît dans la liste des builds comme un build échoué avec une erreur d'autorisation, et rien n'est déployé.

Changer le dépôt ou la branche

Cliquez sur Change repository sur la carte du projet. Jamdesk liste les dépôts auxquels votre compte Bitbucket a accès. Choisissez un dépôt et une branche, puis confirmez.

Jamdesk installe le webhook sur le nouveau dépôt, le supprime de l'ancien, et lance un build.

Réautoriser une connexion expirée

Bitbucket révoque l'accès de Jamdesk lorsque l'utilisateur connecté le retire dans Bitbucket, ou lorsque le jeton de rafraîchissement reste inutilisé pendant plusieurs mois. La carte du projet affiche alors un badge Needs reauth et le message Bitbucket connection needs attention.

Cliquez sur Re-authorize et reconnectez-vous. Les builds reprennent, et la prochaine vérification de cinq minutes récupère le dernier commit de votre branche.

En quoi Bitbucket diffère de GitHub

Les projets Bitbucket utilisent une autorisation OAuth unique, là où les projets GitHub utilisent une GitHub App plus une liaison optionnelle de compte personnel. La majeure partie de la plateforme fonctionne de la même façon. Les différences :

La suppression d'un projet retire le webhook de votre dépôt et révoque l'accès de Jamdesk.

Dépannage

« Votre compte Bitbucket ne dispose pas de la permission admin sur ce dépôt »

Jamdesk a besoin d'un accès admin pour installer le webhook. Demandez à un administrateur du workspace de vous accorder la permission admin sur le dépôt, ou faites connecter le projet par un administrateur.

« Nous n'avons pas trouvé de docs.json dans ce dépôt »

Jamdesk a cherché à la racine et jusqu'à trois dossiers de profondeur sur la branche saisie. Ajoutez un docs.json, poussez-le vers cette branche, et reconnectez-vous. Consultez la référence docs.json.

« Plusieurs fichiers docs.json ont été trouvés »

Ne gardez qu'un seul docs.json par dépôt. Supprimez ou renommez les autres, puis reconnectez-vous.

« Ce dépôt ressemble à un projet Mintlify »

Le dépôt contient un mint.json. Exécutez jamdesk migrate pour le convertir, poussez le résultat, et reconnectez-vous.

Popup bloquée

Autorisez les popups pour le dashboard dans votre navigateur, puis cliquez à nouveau sur Sign in with Bitbucket ou Connect Bitbucket.

Les builds ne se déclenchent pas

• Dans Bitbucket, ouvrez Repository settings → Webhooks et vérifiez que le webhook Jamdesk est présent et actif
• Vérifiez que vous poussez vers la branche configurée
• Attendez cinq minutes. La vérification périodique construit tout commit manqué par le webhook
• Si la carte du projet affiche Needs reauth, réautorisez la connexion
• Si le push provient d'un compte Bitbucket différent, consultez Quels push déclenchent un build

Et ensuite ?