Token d'installation GitHub App (backend)
Token d'installation GitHub App (backend)
Récupérer et utiliser le token d'installation GitHub App côté serveur pour diagnostics, webhook et synchronisation
Guide complet pour obtenir, valider et exploiter le token d’installation GitHub App depuis le backend — actions courantes, scénarios et résolution des problèmes.
Couvert dans cette page
Obtenir le token d'installation
Comment le backend obtient un token d’installation pour accéder aux dépôts de votre projet.
Utiliser le token côté serveur
Scénarios courants : diagnostics de permissions, création de webhooks, synchronisation et lecture de fichiers.
Dépannage & bonnes pratiques
Que faire en cas d’erreurs de permission, d’expiration ou de limites d’API.
À propos de l'outil côté serveur
Le back-end dispose d’un utilitaire centralisé qui récupère et renouvelle le token d’installation GitHub App pour un projet donné. Les actions « Diagnostiquer », « Créer un webhook » ou « Synchroniser » déclenchent automatiquement l’utilisation de ce token côté serveur.
Introduction
Ce guide explique, pour un utilisateur non technique, comment le token d’installation d’une GitHub App est obtenu et utilisé par le backend de votre application. Vous apprendrez :
- comment déclencher la récupération du token depuis l’interface,
- quelles actions serveur l’utilisent,
- comment interpréter les erreurs courantes et relancer une authentification si nécessaire.
Important : ces opérations sont majoritairement automatisées côté serveur après l’installation de la GitHub App. Vous intervenez principalement via l’interface (installation, connexion de dépôt, bouton de diagnostic/sync).
Flux 1 — Installer la GitHub App et lier un projet (côté utilisateur)
Étape 1 — Installer l'application GitHub
Ouvrez le lien d’installation de la GitHub App (fournie dans l’interface d’intégration) et suivez l’assistant GitHub pour sélectionner les organisations ou dépôts à connecter.
Étape 2 — Retourner à l'application et choisir le projet
Dans l’interface, allez sur la page du projet puis choisissez “Ajouter un dépôt” ou “Connecter via GitHub App”. L’application enregistre l’installation associée à l’utilisateur du projet.
Étape 3 — Vérifier la liste des dépôts accessibles
Après l’installation, vous pourrez voir la liste des dépôts que la GitHub App peut accéder. Si un dépôt attendu n’apparaît pas, vérifiez la sélection de dépôts dans l’écran d’installation GitHub.
Étape 4 — Lancer une action qui nécessite un token (diagnostic, webhook, sync)
Cliquez sur « Diagnostiquer », « Créer webhook » ou « Synchroniser » : le backend va récupérer le token d’installation lié au projet et l’utiliser pour l’opération demandée.
Vérifiez les permissions lors de l'installation
Quand vous installez la GitHub App, accordez les permissions minimales nécessaires (lecture de code, gestion des webhooks si vous voulez que l’app crée des webhooks). Si une action échoue pour cause de permission, la réinstallation avec permissions étendues peut résoudre le problème.
Flux 2 — Récupération automatique du token côté serveur (ce que vous devez savoir)
Étape 1 — Le backend identifie l'installation liée au projet
Lorsque vous demandez une action, le backend vérifie quel utilisateur du projet a lié une installation GitHub. Si aucune installation n’est présente, l’action renverra une erreur décrite plus bas.
Étape 2 — Le serveur demande un token d'installation
Le serveur demande un token d’accès temporaire pour l’installation GitHub. Ce token est ce qui permet au backend d’appeler l’API GitHub pour ce dépôt/organisation.
Étape 3 — Utilisation du token pour l'action demandée
Le token est utilisé immédiatement pour l’opération (vérifier permissions, créer webhooks, lister fichiers, lire commits). Le token est éphémère et n’est normalement pas exposé au client.
Étape 4 — Gestion des erreurs et logs
Si la récupération du token échoue (installation manquante, clé privée expirée, problème côté GitHub), le serveur renverra une erreur visible dans l’interface. Consultez les messages affichés pour savoir si une réinstallation est nécessaire.
Sécurité : le token reste côté serveur
Le token d’installation est toujours obtenu et utilisé côté serveur. Les utilisateurs finaux n’ont pas accès au token brute : seules les opérations autorisées via l’interface sont exécutées par le backend.
Limites et erreurs courantes
- Si le backend n’a pas de token valide pour le dépôt, les diagnostics et actions renverront des erreurs de permission.
- La vérification de webhooks s’appuie sur des points de terminaison du fournisseur (GitHub) et peut être sujette aux limites de débit (rate limits).
- Pour les intégrations GitLab, le rafraîchissement automatique n’est possible que si un refresh_token est stocké ; sinon, une ré-authentification manuelle sera nécessaire.
Flux 3 — Actions courantes qui utilisent le token (mode opératoire)
Diagnostiquer les permissions d'un dépôt
Dans la page du dépôt, cliquez sur « Diagnostiquer ». Le serveur va : récupérer le token d’installation, interroger GitHub pour vérifier les accès (lecture de code, gestion des webhooks), puis afficher un rapport (permissions manquantes, webhooks inaccessibles).
Créer ou vérifier un webhook
Choisissez « Créer un webhook ». Le serveur utilisera le token d’installation pour vérifier qu’il existe un webhook correspondant ; s’il n’existe pas, il peut le créer (si vous avez accordé la permission webhook lors de l’installation).
Synchroniser un dépôt / indexer le code
Lancez la synchronisation manuelle (RAG sync). Le backend récupère les commits/fichiers en utilisant le token d’installation et met à jour l’indexage ; vous verrez l’activité et l’état de la synchronisation dans l’interface.
Traitement des commits récents
Pour déclencher le traitement des récents commits, lancez l’option « Traiter commits récents ». Le serveur récupère les diffs via le token et exécute les flux de génération d’index/documentation.
Vous venez d’installer la GitHub App et d’ajouter un dépôt au projet. Le backend récupérera automatiquement le token lors de la première action (diagnostic/sync). Si tout est bien, les actions réussissent et aucun travail supplémentaire n’est requis.
Comparaison : Token d’installation GitHub App
- Valide pour l’installation (organisation / ensemble de dépôts sélectionnés)
- Utilisé côté serveur pour actions automatisées
- Ne dépend pas d’un utilisateur spécifique (après installation)
- Généralement éphémère mais renouvelable par le serveur
Comparaison : Token OAuth utilisateur
- Lié à un utilisateur individuel et ses permissions
- Peut expirer et nécessiter re-authentification si pas de refresh token
- Utile pour actions qui doivent refléter précisément l’identité d’un utilisateur
- Moins adapté pour automatisations serveur partagées
Flux 4 — Dépannage pas à pas (si une action échoue)
Étape 1 — Lire le message d'erreur affiché
La plupart des erreurs de permission ou d’accès s’affichent directement dans l’interface. Notez le message précis : « installation manquante », « permission refusée », « rate limit », etc.
Étape 2 — Vérifier l'installation GitHub
Allez sur la page d’installation GitHub (via le lien d’intégration) et confirmez que l’installation existe, que les dépôts nécessaires sont sélectionnés et que les permissions requises sont accordées.
Étape 3 — Relancer l'action depuis l'interface
Après avoir corrigé l’installation/permissions, relancez l’action (diagnostic, création webhook ou sync). Le serveur doit pouvoir obtenir un token valide et poursuivre.
Étape 4 — Si le problème persiste, ré-installer l'app
Si les erreurs continuent, effectuez une réinstallation complète de la GitHub App depuis l’interface d’installation (sélectionnez correctement les dépôts et permissions) puis relancez l’opération.
Étape 5 — Contacter le support avec les logs
Si vous ne parvenez toujours pas à résoudre le problème, exportez le message d’erreur affiché et contactez le support en fournissant : action tentée, nom du projet, dépôt concerné, et heure de l’échec.
Ayez toujours une installation de secours
Pour les organisations, envisagez de lier l’application à un compte de service ou à un administrateur central afin d’éviter les ruptures si un utilisateur quitte l’organisation.
Rate limits et opérations massives
Les vérifications répétées de webhooks, des lectures massives de fichiers ou le traitement de très gros dépôts peuvent entraîner des limitations côté GitHub (rate limits). Si vous donnez l’ordre de synchroniser beaucoup de projets, espacez les actions ou utilisez les outils d’orchestration fournis.
Frequently Asked Questions
Récapitulatif
- La récupération du token d’installation est automatique et se fait côté serveur lorsque vous lancez une action.
- Vérifiez les permissions et la sélection de dépôts au moment de l’installation GitHub.
- En cas d’erreur : lisez le message, vérifiez l’installation, réinstallez si nécessaire, puis relancez l’action.
- Attention aux limites d’API et aux différences entre tokens d’installation et tokens OAuth utilisateur.
Besoin d'aide ?
Si vous rencontrez des erreurs persistantes, fournissez le message d’erreur affiché, le projet et le dépôt concernés pour accélérer l’assistance.