Diagnostic d'accès et Webhooks
Diagnostic d'accès et Webhooks
Comment lancer et interpréter un diagnostic d'accès au repository, vérifier l'état des webhooks côté provider, et résoudre les erreurs courantes
Lisez ce guide pour exécuter les diagnostics pas à pas, comprendre les résultats et restaurer un accès complet aux sources et webhooks.
Ce que couvre cette page
Diagnostiquer l'accès au repository
Vérifier si l’application peut accéder au repository, l’état des tokens (présence, expiration, type) et les permissions disponibles.
Vérifier l'état des webhooks
Confirmer si un webhook est présent côté provider (GitHub / GitLab), si les events et le secret sont configurés et détecter les anomalies.
Résolution des erreurs et limites
Guides pratiques pour les erreurs 401/403, tokens expirés, limites de rate et webhooks manquants ou mal configurés.
Introduction
Ce guide détaille comment lancer le diagnostic d’un repository depuis l’interface, comment lire chaque élément du rapport, comment vérifier manuellement la présence d’un webhook chez le provider et quelles actions entreprendre selon les résultats. Il couvre aussi les particularités GitHub vs GitLab, les cas où un token peut être rafraîchi automatiquement et les erreurs fréquentes liées aux permissions et aux limites d’API.
Astuce — préparez vos accès
Avant de lancer les diagnostics, assurez-vous d’être connecté avec un compte qui a accès au projet dans l’application et, si possible, d’avoir accès au compte provider (GitHub/GitLab) pour vérifier les webhooks côté provider si nécessaire.
Workflow : Lancer le diagnostic d'accès (vue Repository)
Étape 1 — Ouvrir la vue Repository
Dans l’application, naviguez vers le projet, ouvrez l’onglet Repos/Repositories et sélectionnez le repository concerné.
Étape 2 — Cliquer sur 'Diagnostics'
Dans la fiche du repository, cliquez sur le bouton “Diagnostics” (ou lien équivalent). Le diagnostic est lancé côté backend et peut prendre quelques secondes.
Étape 3 — Attendre la complétion et charger le rapport
Patientez pendant que le diagnostic interroge le provider. Un écran ou une fenêtre récapitulative s’affiche avec plusieurs champs (tokens, permissions, accessibilité du repo, webhooks).
Étape 4 — Inspecter immédiatement les champs clés
Vérifiez en priorité : présence d’un token d’accès, présence d’un refresh_token, date d’expiration du token, indication d’utilisation d’un GitHub App, repository_accessible (booléen), webhooks_accessible (booléen), existing_webhooks_count et tout message d’erreur.
Étape 5 — Copier ou sauvegarder le rapport
Si vous devez ouvrir un ticket ou consulter une autre personne, copiez les détails du diagnostic (messages d’erreur, permissions listées, counts) pour accélérer le dépannage.
Astuce — capturez les messages d'erreur exacts
Les messages d’erreur retournés par le diagnostic (ex. : ‘Cannot access repository’, ‘Cannot access webhooks’, ou ‘No access token available’) contiennent des indications précises pour déterminer si le problème est côté token, permissions ou rate limit. Capturez-les tels quels.
Interpréter en détail les résultats du diagnostic
Étape 1 — has_access_token = false
Signification : l’application ne dispose pas d’un token valide pour ce repository. Actions : ré-authentifier le repository via l’interface (connexion OAuth) ou, si vous utilisez GitHub App, vérifier que l’application est bien installée pour ce repo.
Étape 2 — has_refresh_token = true / false
Signification : pour GitLab, la présence d’un refresh_token permet souvent un rafraîchissement automatique. Si false, une ré-authentification manuelle sera nécessaire à l’expiration. Action : si token expiré et pas de refresh_token, lancez la procédure de ré-authentification depuis le formulaire du repository.
Étape 3 — token_expires_at
Interprétation : notez la date d’expiration. Si elle est passée, le diagnostic peut échouer. Pour GitLab, si un refresh_token est présent, le système peut le renouveler automatiquement ; sinon, planifiez une ré-authentification.
Étape 4 — uses_github_app = true
Signification : le repository est configuré via une installation GitHub App. L’application utilisera un token d’installation spécifique ; vérifiez que l’App est installée sur le repo/organisation et que l’installation n’a pas été révoquée.
Étape 5 — permissions (liste ou objet)
Interprétation : ces champs montrent ce que le token peut faire (lecture, écriture, admin). Si l’accès aux webhooks est nécessaire et manque (ex. pas d’admin ou pas de scope write:repo_hook), vous ne pourrez pas créer/lister webhooks.
Étape 6 — repository_accessible = false
Cause typique : token invalide/expiré, accès utilisateur insuffisant ou repo supprimé/migré. Action : vérifier token, droits du compte, ou existence du repository sur le provider.
Étape 7 — webhooks_accessible = false ou existing_webhooks_count = 0
Cause typique : le token n’a pas la permission de lister/créer les webhooks, le webhook n’existe pas, ou les appels ont été bloqués (rate limit, restrictions IP). Action : vérifier scopes, installer l’App, ou inspecter côté provider.
Étape 8 — message d'erreur présent
Lisez le texte exact. Exemples : “Cannot access repository: 404 Not Found” → repository inaccessible ; “Cannot access webhooks: 403 Forbidden” → token sans permission webhooks. Adaptez les actions (ré-authentification, vérifier scopes ou installation de l’App).
Limites et comportements à connaître
Le diagnostic dépend d’un token valide côté backend : si le backend n’a pas de token pour ce repository, vous verrez des erreurs de permission. De plus, la vérification des webhooks interroge les endpoints du provider et peut échouer temporairement à cause de limites de rate (retours 429) — attendez quelques minutes avant de relancer.
Vérifier manuellement la présence d'un webhook côté provider (GitHub / GitLab)
Étape 1 — Se connecter sur le provider
Ouvrez GitHub ou GitLab avec un compte qui a accès au repository.
Étape 2 — Accéder aux paramètres du repository
GitHub : Repository → Settings → Webhooks.
GitLab : Repository/Project → Settings → Webhooks.
Étape 3 — Rechercher l'URL du webhook
Cherchez dans la liste un webhook dont l’URL contient la partie attendue (ex. la route d’API de l’application, souvent /api/webhooks/github ou /api/webhooks/gitlab). Vérifiez aussi le champ “Events” pour s’assurer que push / pull request / merge_requests sont cochés.
Étape 4 — Vérifier le secret/signature
Confirmez la présence du token/secret côté provider (nommé “Secret token” ou “Secret”). Si votre application attend un secret mais qu’il n’est pas enregistré, la signature des requêtes webhook échouera.
Étape 5 — Tester le webhook
Si le provider offre un bouton “Test delivery” ou “Ping”, utilisez-le pour envoyer un événement de test et observer les logs de réception dans l’application (si disponibles) ou vérifier l’état retourné par le provider (200 OK attendu).
Étape 6 — Si le webhook n'existe pas
Si absent, retournez dans l’application et utilisez l’action “Créer webhook” (ou suivez la procédure d’ajout recommandée) après avoir vérifié que le token possède les droits nécessaires.
- Les webhooks sont listés dans les Settings > Webhooks du repo.
- Pour créer/lister les webhooks, le token doit avoir les scopes/permissions nécessaires (écriture/admin sur hooks) ou l’installation GitHub App doit être active pour le repo.
- Vérifiez la correspondance de l’URL du webhook et la présence du secret.
- Testez via “Recent deliveries” / “Deliver again” pour voir le statut.
Avant (symptômes courants)
- Diagnostics : No access token / token expiré
- repository_accessible = false
- webhooks_accessible = false ou existing_webhooks_count = 0
- Erreurs 401/403 ou 404 côté provider
Après (état attendu)
- Token valide présent ou installation GitHub App active
- repository_accessible = true
- webhooks_accessible = true et count > 0
- Tests de webhook retournent 200 OK et signatures valides
Créer ou forcer la création d'un webhook depuis l'application
Étape 1 — Confirmer qu'un token est disponible
Avant de créer un webhook, vérifiez dans le diagnostic que le repository a un token ou utilise une installation GitHub App. Si non, ré-authentifiez.
Étape 2 — Lancer l'action 'Créer webhook' dans la vue Repository
Cliquez sur le bouton pour créer le webhook. L’interface doit indiquer le succès ou renvoyer un message expliquant pourquoi la création a échoué (ex. permissions manquantes).
Étape 3 — Vérifier le message de retour
Si l’application indique “Webhook already exists”, allez vérifier côté provider pour confirmer que l’URL est correcte et que le secret est enregistré. Si “Webhook created successfully”, sauvegardez le secret si demandé par l’interface.
Étape 4 — Tester la réception
Effectuez un push de test ou utilisez la fonction ‘Test delivery’ du provider pour valider la réception et la signature.
Étape 5 — Sauvegarder et documenter
Consignez le résultat dans le ticket/notes du projet : date de création, ID du webhook coté provider, events activés et si un secret a été enregistré.
Astuce — privilégiez la création via l'application
Lorsque possible, créez le webhook depuis l’interface de l’application : elle génère souvent le secret automatiquement et met à jour le repository avec les informations nécessaires évitant les erreurs de signature.
Dépannage : erreurs courantes et comment les résoudre
Erreur 401 / 403 (Forbidden)
Causes : token invalide/expiré, scopes insuffisants, ou utilisateur sans droits. Actions : ré-authentifier le repository, vérifier les scopes requis (ex. droits webhooks), ou réinstaller l’application GitHub si utilisé.
Erreur 404 Not Found
Cause : repository supprimé, renommé ou URL incorrecte. Actions : vérifier l’URL, vérifier si le repo a été archivé/privé, et mettre à jour la configuration.
Webhooks présents mais non détectés par le diagnostic
Causes possibles : rate limits temporaires du provider, token utilisé pour la vérification différent du token qui a créé le webhook, ou webhook configuré sur une URL légèrement différente. Actions : attendre quelques minutes et relancer, vérifier la liste côté provider, comparer URL exactes.
Rate limit et réponses 429
Si vous atteignez une limite, attendez la fenêtre de reset indiquée côté provider. Évitez de relancer trop fréquemment le diagnostic ; attendez 1 à 5 minutes.
Self‑hosted GitLab ou GitHub Enterprise
Si le repository est sur une instance self-hosted, vérifiez le domaine (URL) utilisé lors de la connexion et si l’instance impose des restrictions réseau ou des tokens différents. Contactez l’administrateur si nécessaire.
Token GitLab expiré — rafraîchissement automatique
Si un refresh_token est stocké, l’application peut tenter un rafraîchissement automatique. Si le refresh échoue (refresh_token absent ou révoqué), une ré-authentification manuelle est requise.
Webhooks 500 / payload non traités
Si le provider affiche des échecs de livraison (5xx), vérifiez l’état de réception dans l’application (logs ou interface) : problème d’authentification, firewall bloquant les requêtes entrantes, ou endpoint indisponible.
Gotcha fréquent — permissions sur les webhooks
Pour créer/lister des webhooks sur GitHub, le token ou l’installation GitHub App doit disposer des permissions appropriées (écriture/admin sur les hooks). Sans ces permissions, la création échouera même si le token permet d’accéder aux fichiers du repo.
Frequently Asked Questions
Bonnes pratiques opérationnelles
- Planifiez les changements de tokens/webhooks pendant des fenêtres de maintenance pour minimiser les perturbations.
- Après avoir créé ou modifié un webhook, effectuez un test de livraison immédiat et conservez l’ID/les captures d’écran pour le support.
Besoin d'aide supplémentaire ?
Si vous ne parvenez pas à résoudre un problème après ces étapes, contactez le support en fournissant le rapport de diagnostic et les captures d’écran des webhooks côté provider.