Intégration GitHub

Jamdesk utilise deux connexions GitHub distinctes, chacune avec un rôle différent. Cette page explique ce que fait chaque connexion et quand vous en avez besoin.

Aperçu

GitHub App (niveau projet)

La Jamdesk GitHub App est installée sur votre compte GitHub ou votre organisation. Elle accorde à Jamdesk l'autorisation d'accéder à des dépôts spécifiques.

Ce qu'elle fait

• Lit le contenu du dépôt - Clone votre documentation pour la construire
• Reçoit les webhooks - Est notifiée lorsque vous poussez des modifications
• Signale l'état du build - Affiche l'état du déploiement sur les commits

Pourquoi vous en avez besoin

Sans la GitHub App installée, Jamdesk ne peut pas :

• Accéder à votre dépôt pour construire la documentation
• Déployer automatiquement lorsque vous poussez des modifications
• Afficher l'état du build sur les commits GitHub

Comment ça fonctionne

Lorsque vous configurez un projet, Jamdesk vous guide dans la connexion à GitHub. Il existe deux méthodes.

Créer un dépôt de documentation de démarrage (par défaut pour les nouveaux projets)

Connecter un dépôt existant

Vous avez déjà un dépôt de documentation ? Installez la Jamdesk GitHub App, accordez-lui l'accès à ce dépôt, puis choisissez le dépôt et la branche dans Jamdesk sous Project Settings → Git Repository. À partir de là, cela fonctionne de la même manière.

Une seule application, plusieurs projets

Une seule installation de la GitHub App peut alimenter plusieurs projets Jamdesk :

• Installez l'application une fois sur votre compte ou votre organisation
• Connectez différents dépôts à différents projets Jamdesk
• Chaque projet a sa propre configuration de branche et de chemin

Compte GitHub personnel (niveau utilisateur)

Lier votre compte GitHub personnel associe votre identité GitHub à votre profil Jamdesk. Ceci est distinct de la GitHub App.

Ce qu'il fait

• Vous identifie - Associe votre nom d'utilisateur GitHub à votre compte Jamdesk
• Attribue les builds - Indique qui a déclenché chaque déploiement
• Visibilité d'équipe - Les autres membres de l'équipe peuvent voir qui a effectué des modifications

Pourquoi vous en avez besoin

Lorsque vous poussez vers GitHub, Jamdesk doit déterminer quel utilisateur a déclenché le build. Sans votre compte lié :

• Jamdesk se rabat sur une correspondance par adresse e-mail
• Si l'e-mail de vos commits Git diffère de votre e-mail Jamdesk, l'attribution échoue
• L'historique des builds peut afficher « Unknown user » pour vos commits

Vérifiez votre e-mail Git

git config user.email
git config --global user.email "you@company.com"

Utilisez la même adresse e-mail que celle associée à votre compte Jamdesk pour éviter une attribution « Unknown user » dans l'historique des builds.

Comment lier votre compte

Comment elles fonctionnent ensemble

Considérez-les comme deux clés distinctes :

Exemple d'équipe

Imaginez une équipe de 3 développeurs travaillant sur la documentation de l'entreprise :

1. L'administrateur installe la GitHub App sur l'organisation
2. L'administrateur crée un projet Jamdesk connecté au dépôt de documentation
3. Chaque développeur lie son compte personnel

Maintenant, lorsqu'un développeur pousse des modifications :

• La GitHub App permet à Jamdesk de lire le dépôt et de construire
• Le lien personnel identifie qui a déclenché le build

Exemple de développeur solo

Même en tant que développeur solo, les deux connexions ont des rôles différents :

• GitHub App - Connecte votre dépôt à Jamdesk
• Lien personnel - Garantit que vos commits affichent votre nom dans l'historique des builds

Déconnexion et dissociation

Chaque action supprime un accès différent. Voici ce que chacune affecte.

Déconnecter GitHub (Project Settings)

Ce qu'elle fait : Supprime la connexion au dépôt d'un seul projet Jamdesk.

Effets :

• Les déploiements automatiques s'arrêtent pour ce projet
• La GitHub App reste installée sur GitHub
• Les autres projets Jamdesk ne sont pas affectés
• Votre lien de compte personnel n'est pas affecté

Quand l'utiliser : Vous souhaitez connecter un dépôt différent, ou arrêter temporairement les déploiements.

Comment se reconnecter : Accédez à Project Settings → Git Repository et sélectionnez un dépôt.

Dissocier GitHub (User Settings)

Ce qu'elle fait : Supprime votre identité GitHub de votre profil Jamdesk.

Effets :

• Votre nom d'utilisateur GitHub n'apparaît plus dans votre profil
• L'attribution des builds se rabat sur la correspondance par e-mail
• Toutes les connexions aux dépôts restent intactes
• La GitHub App reste installée

Quand l'utiliser : Vous souhaitez lier un compte GitHub différent, ou supprimer la connexion.

Comment relier : Accédez à User Settings → GitHub Account → Link GitHub Account.

Désinstaller la GitHub App (sur GitHub)

Ce qu'elle fait : Supprime complètement l'accès de Jamdesk à votre compte GitHub.

Effets :

• Tous les projets Jamdesk utilisant cette installation perdent l'accès
• Les déploiements automatiques s'arrêtent pour tous les projets concernés
• Les webhooks sont supprimés
• Les liens de compte personnel ne sont pas affectés

Comment désinstaller :

1. Accédez à GitHub Settings → Applications → Installed GitHub Apps
2. Trouvez « Jamdesk » et cliquez sur Configure
3. Faites défiler vers le bas et cliquez sur Uninstall

Référence rapide

Dépannage

« Vous avez déjà installé Jamdesk ? »

Si vous avez déjà installé la Jamdesk GitHub App, cliquer sur « Install GitHub App » vous amène à la page des paramètres de GitHub au lieu de la page d'installation. C'est normal ! Voici comment terminer la configuration :

Fenêtre contextuelle bloquée

Si la fenêtre contextuelle de GitHub ne s'ouvre pas, votre navigateur l'a peut-être bloquée. Recherchez une icône de blocage des fenêtres contextuelles dans votre barre d'adresse, autorisez les fenêtres contextuelles de Jamdesk, puis cliquez sur Try Again.

« Mes builds affichent 'Unknown user' »

Votre compte GitHub personnel n'est pas lié. Accédez à User Settings → Link GitHub Account.

« Le dépôt n'apparaît pas »

La GitHub App n'a pas accès à ce dépôt. Accédez à GitHub Settings, trouvez Jamdesk, et ajoutez le dépôt.

« Les builds ne se déclenchent pas »

1. Vérifiez que le dépôt est connecté dans Project Settings → Git Repository
2. Vérifiez que vous poussez vers la branche configurée
3. Vérifiez la livraison des webhooks dans les paramètres du dépôt GitHub

Si tout est correct, la personne qui a fait le push n'est peut-être pas membre du projet. Jamdesk ne construit que les pushs de membres du projet. Il identifie l'auteur du push par son compte GitHub lié, ou parce que l'e-mail de son commit correspond à l'e-mail avec lequel il se connecte à Jamdesk.

Sans correspondance, le build apparaît comme échoué avec le motif, et le propriétaire du projet reçoit un e-mail, au plus un par semaine et par personne. Un push qui ne modifie rien dans votre dossier de documentation n'en envoie pas.

Pour corriger, invitez la personne dans Project Settings → Members avec l'e-mail de son commit. Elle doit se connecter à Jamdesk avec cet e-mail pour accepter. Si elle est déjà membre, elle peut lier son compte GitHub dans User Settings.

« Je ne peux pas accéder aux dépôts de l'organisation »

Un administrateur de l'organisation doit approuver l'installation de la GitHub App. Demandez à votre administrateur d'installer ou d'approuver Jamdesk dans les paramètres de l'organisation.

« GitHub me renvoie sans cesse vers la page de l'application Jamdesk »

Votre entreprise gère probablement votre compte GitHub, et GitHub ne permet pas à ces comptes d'installer des applications sur leur propre compte. Consultez comptes GitHub gérés par l'entreprise pour résoudre ce problème.

Articles connexes