Diagnostics, tokens & dépannage
Ce que vous allez apprendre
Sur cette page vous apprendrez à diagnostiquer l’accès à vos repositories et l’état des webhooks, vérifier et rafraîchir les tokens GitLab, récupérer le token d’installation GitHub App côté serveur, suivre et annuler des jobs en cours, recevoir des mises à jour en temps réel via sockets, et effectuer les étapes de dépannage courantes (réinstaller l’app, recréer un webhook, rafraîchir un token).
Fonctionnalités couvertes
Diagnostics & webhooks
Lancer un diagnostic depuis la vue repository pour inspecter permissions, présence et état du webhook, et voir les erreurs remontées.
Gestion des tokens
Vérifier si un token GitLab approche de l’expiration, le rafraîchir, et préparer les données d’un repo incluant les tokens OAuth (useGitProviderTokens.prepareRepositoryData).
Jobs & updates en temps réel
Suivre la progression des jobs avec barres de progression et sockets en temps réel, et annuler les jobs d’un projet si nécessaire.
GitHub App (côté serveur)
Récupération du token d’installation GitHub App côté serveur (server/utils/github/getInstallationToken.ts) pour effectuer des actions authentifiées.
Flux d'ajout de repository
Ajouter un repo via OAuth ou GitHub App, liste des repos accessibles et création automatique d’un webhook.
Extraction tokens côté client
Utilitaires client pour extraire des tokens depuis les query params (useGitProviderTokens.extractTokensFromQuery) et détecter les tokens proches de l’expiration (useGitProviderTokens.isTokenExpiringSoon).
Étapes pas à pas
1 — Diagnostiquer l'accès au repository et le webhook
- Ouvrez votre projet puis l’onglet “Repos”.
- Sélectionnez le repository concerné et cliquez sur le bouton “Diagnostics”.
- Consultez : permissions disponibles, erreurs remontées, et si un webhook est présent côté provider.
- Si le diagnostic indique “Webhook manquant” ou “Webhook invalide”, cliquez sur “Create webhook” depuis la vue repository : DeployIt crée le webhook côté Git (et génère un secret si nécessaire).
2 — Vérifier et rafraîchir un token GitLab
- Si vous avez connecté un repo via GitLab, vérifiez si DeployIt a détecté un token proche de l’expiration (outil client useGitProviderTokens.isTokenExpiringSoon).
- Depuis la vue repository ou la page d’authentification GitLab, lancez l’opération de rafraîchissement : DeployIt tentera gitlabAuth.refreshGitLabToken automatiquement.
- Si le rafraîchissement automatique échoue, relancez le flux d’authentification GitLab (OAuth) via l’option “Reconnecter GitLab”.
- Astuce : lors d’un retour depuis l’auth OAuth vous pouvez compléter la connexion si DeployIt a extrait les tokens depuis l’URL en utilisant useGitProviderTokens.extractTokensFromQuery.
3 — Obtenir le token d'installation GitHub App (côté serveur)
- Si votre repository est connecté via GitHub App, DeployIt récupère le token d’installation côté serveur pour agir au nom de l’app.
- Cette opération utilise le code serveur (server/utils/github/getInstallationToken.ts). En pratique : vous cliquez sur “Refresh GitHub App token” ou suivez l’option “Install GitHub App” dans l’UI.
- Si l’interface affiche un problème d’autorisation avec GitHub App, réinstallez l’app (voir section dépannage) et retentez la récupération du token.
4 — Suivre la progression d'un job et recevoir des updates en temps réel
- Quand vous lancez une action (ajouter un repository, indexer, uploader), DeployIt met le travail en file (projectSourceQueue).
- Ouvrez la page projet pour voir la barre de progression et les logs en direct : DeployIt utilise des sockets pour pousser les mises à jour en temps réel.
- Si la progression ne bouge pas, rafraîchissez la page ; si le problème persiste, consultez les diagnostics du repository et vérifiez les webhooks.
5 — Annuler des jobs en cours
- Pour annuler les jobs d’un projet : ouvrez le menu de votre projet et cliquez sur “Cancel jobs”.
- Le backend videra la queue et tentera d’annuler les tâches associées (les workers respectent l’annulation et les rate limiters).
- Après annulation, vous pouvez relancer l’opération une fois le problème résolu.
6 — Étapes de dépannage courantes
- Réinstaller la GitHub App :
- Dans l’UI cliquez sur “Install GitHub App” et suivez le flux d’installation GitHub.
- Une réinstallation corrige souvent les permissions manquantes et permet à server/utils/github/getInstallationToken.ts d’obtenir un token valide.
- Recréer un webhook :
- Depuis la vue repository, cliquez sur “Create webhook”. DeployIt génère un secret et enregistre le webhook chez le provider.
- Exemple : si vous voyez “push events non reçus”, recréez le webhook et poussez un commit test.
- Rafraîchir un token GitLab :
- Lancez la tentative automatique (gitlabAuth.refreshGitLabToken). Si elle échoue, relancez le login GitLab depuis DeployIt.
- Exemple : message “401 Unauthorized” lors d’opérations Git -> souvent token expiré ; reconnectez GitLab.
Astuce pratique
Si vous terminez le flux OAuth et que la page semble vide, revenez à la page d’ajout de repository : DeployIt utilise useGitProviderTokens.extractTokensFromQuery pour récupérer les tokens dans l’URL et useGitProviderTokens.prepareRepositoryData pour finir la création automatiquement.
Erreur fréquente à éviter
Ne recréez pas plusieurs fois la même webhook sans supprimer l’ancienne : vous risquez d’avoir des événements dupliqués. Supprimez l’ancien webhook côté provider ou depuis la vue repository avant d’en créer un nouveau.
Que faire si rien ne fonctionne ?
- Lancez le diagnostic du repository et copiez les erreurs affichées.
- Réinstallez la GitHub App ou reconnectez GitLab selon le provider.
- Recréez le webhook depuis la vue repository (bouton “Create webhook”).
- Si besoin, contactez le support avec le résultat du diagnostic et la capture d’écran des logs en temps réel. Le plugin de support (Crisp) peut être enrichi avec le contexte de votre projet.
Next steps
- Vérifiez maintenant un repository réel : Projet → Repos → sélectionnez un repo → Diagnostics.
- Si un token GitLab est indiqué comme “expiring soon”, lancez le rafraîchissement.
- Testez la création d’un webhook et poussez un commit pour vérifier que les events arrivent.
- Prochaine page (10/11) : “Équipe, permissions & facturation” pour gérer qui peut faire ces opérations.
Besoin d'aide ?
Si le diagnostic affiche une erreur que vous ne comprenez pas, envoyez les détails au support (copiez les messages du diagnostic et l’ID du projet). Ils utiliseront server/utils/github/getInstallationToken.ts et les logs serveur pour investiguer.