Intégration GitHub

Connecter un projet à son dépôt GitHub permet à Quiet Guard de suivre le travail qui livre votre application et de corréler les erreurs de production au commit qui les a introduites.

Sur les forfaits payants. L'intégration GitHub fait partie d'Indie et Studio. Sur Free, les réglages du projet présentent ce que fait l'intégration au lieu des champs du dépôt. Tout ce qui a déjà été synchronisé reste visible sur l'onglet GitHub du projet ; rien de nouveau n'est récupéré tant que le forfait ne la comprend pas.

Connecter un dépôt

Sur la page Réglages du projet, section Intégration GitHub, renseignez :

• Dépôt : le dépôt sous la forme propriétaire/nom (par ex. acme/store), tel qu'il apparaît dans l'adresse GitHub.
• Jeton d'accès : un jeton d'accès personnel GitHub capable de lire ce dépôt. Quiet Guard ne lit que trois choses : les métadonnées du dépôt, ses commits et ses branches, et ses pull requests. Il n'écrit jamais, sauf pour ouvrir une issue depuis une anomalie si vous l'y autorisez (voir plus bas).

Créer le jeton sur GitHub

1. Connecté à GitHub avec un compte qui voit le dépôt, ouvrez Settings > Developer settings > Personal access tokens > Fine-grained tokens, puis Generate new token. Adresse directe : https://github.com/settings/personal-access-tokens/new.
2. Resource owner : l'utilisateur ou l'organisation propriétaire du dépôt. Pour le dépôt d'une organisation, choisissez l'organisation, pas votre propre compte ; certaines organisations exigent qu'un administrateur approuve le jeton avant qu'il ne fonctionne.
3. Repository access : Only select repositories, puis le seul dépôt concerné.
4. Repository permissions : Contents en Read-only (commits et branches) et Pull requests en Read-only. GitHub ajoute Metadata en Read-only de lui-même. Pour suivre les issues du dépôt, ajoutez Issues en Read-only ; pour en ouvrir depuis une anomalie, Issues en Read and write. Rien d'autre.
5. Expiration : ce que votre politique permet. À l'expiration, la synchronisation s'arrête et plus rien de nouveau n'apparaît dans l'onglet GitHub tant que vous n'avez pas collé un nouveau jeton.
6. Générez le jeton et copiez-le (il commence par github_pat_) : GitHub ne l'affiche qu'une fois.

Collez-le dans le champ Jeton d'accès et enregistrez. Le champ ne réaffiche jamais le jeton stocké : laissez-le vide aux enregistrements suivants pour conserver le jeton actuel, saisissez-en un nouveau pour le remplacer.

Un jeton personnel classic fonctionne aussi, avec la portée repo pour un dépôt privé ou public_repo pour un dépôt public. Le jeton à portée restreinte est préférable : il se limite à un seul dépôt et à des permissions en lecture seule, ce qui est tout ce que cette intégration utilise.

Le jeton est chiffré au repos. La colonne github_token est stockée via le cast chiffré de Laravel ; le jeton n'est donc jamais persisté en clair dans la base de données.

Un projet est considéré comme connecté à GitHub dès qu'un dépôt et un jeton sont présents. Lancez Synchroniser GitHub une fois juste après l'enregistrement : c'est le moyen le plus rapide de découvrir qu'un jeton n'ouvre pas le dépôt.

Ce qui est synchronisé

La synchronisation récupère et stocke trois types d'activité du dépôt, et un quatrième sur demande :

• Commits: les commits récents, avec SHA, message, auteur et horodatage.
• Pull requests: les PR ouvertes et récentes.
• Branches: les branches du dépôt, réconciliées à chaque synchronisation (les branches disparues en amont sont supprimées localement).
• Issues, si le projet l'a demandé : les issues du dépôt, leurs libellés et, en option, leurs commentaires (voir Les issues du dépôt).

La synchronisation suit une approche tout récupérer puis tout écrire dans une transaction : les données sont d'abord tirées de l'API REST GitHub puis écrites en une seule transaction, pour qu'une panne réseau partielle ne laisse jamais le projet à moitié mis à jour.

Lancer une synchronisation

Utilisez l'action Synchroniser GitHub de l'onglet GitHub (menu Réglages du projet) pour récupérer la dernière activité à la demande. Les commits, PR et branches synchronisés sont affichés dans l'onglet GitHub du projet.

Sur les forfaits qui portent l'intégration, un projet connecté est également synchronisé de lui-même, quelques fois par jour, pour que l'image reste à jour entre deux déploiements sans que personne ne clique.

Les issues du dépôt

Les issues GitHub sont la conversation de l'équipe : les tirer dans le tableau de bord est un choix, pas un effet de bord du jeton collé pour les commits. Sur la page Réglages du projet, section Intégration GitHub, quatre interrupteurs, tous éteints par défaut :

• Suivre les issues du dépôt : à chaque synchronisation, les issues ouvertes du dépôt arrivent dans l'onglet GitHub du projet, sous Issues, avec leur titre, leur auteur, leurs libellés et le nombre de commentaires. Les pull requests que GitHub liste parmi les issues sont écartées, elles ont leur propre onglet.
• Récupérer aussi les commentaires : une requête GitHub par issue commentée, limitée aux trente issues les plus récentes à chaque synchronisation. Un commentaire supprimé sur GitHub disparaît à la synchronisation suivante.
• Inclure les issues fermées : sans cette option, l'onglet n'affiche que les issues ouvertes. Les fermées restent synchronisées, pour qu'une issue liée à une anomalie dise quand elle se ferme. La synchronisation lit les 100 issues les plus récentes du dépôt.
• Ouvrir une issue GitHub pour chaque nouvelle anomalie : voir ci-dessous.

Depuis l'onglet, Lire ouvre une issue et ses commentaires sans quitter le tableau de bord ; le Markdown est rendu par le même moteur que cette documentation, qui échappe tout avant de l'afficher. Le lien Ouvrir sur GitHub mène à l'issue elle-même. Le jeton doit porter la permission Issues en lecture.

Depuis une anomalie

Sur la page d'une anomalie, deux actions apparaissent dès que le projet suit ses issues :

• Ouvrir une issue GitHub propose un titre et une description composés à partir des métadonnées de l'anomalie : la classe de l'exception, l'emplacement, la première trame dans votre code, le nombre d'occurrences, les environnements et versions touchés, et le lien vers l'anomalie. Le message de l'exception n'y figure que s'il n'est pas chiffré : une équipe qui scelle son contenu ne le voit jamais copié sur GitHub par cette action. Relisez et modifiez avant d'envoyer, ce texte est public si le dépôt l'est. L'issue est créée avec le libellé quiet-guard et reliée à l'anomalie, qui l'affiche ensuite dans sa vue d'ensemble.
• Lier une issue GitHub rattache l'anomalie à une issue ouverte déjà synchronisée, pour un rapport que quelqu'un a écrit avant vous.

L'onglet Issues du projet montre, pour chaque issue, l'anomalie qu'elle suit.

Avec Ouvrir une issue GitHub pour chaque nouvelle anomalie, la première occurrence d'une exception jamais vue ouvre l'issue elle-même, avec le même corps, sans intervention. Une régression (une anomalie résolue qui se reproduit) n'en ouvre pas de nouvelle : l'issue qu'elle avait est toujours là. Un refus de GitHub (jeton sans la permission d'écriture, dépôt archivé) est journalisé et n'empêche jamais l'ingestion ; l'issue peut alors être ouverte à la main. Au plus dix issues par heure et par projet sont ouvertes ainsi : une clé de projet fuitée peut fabriquer des anomalies à volonté, et elle ne doit pas remplir votre dépôt sous votre nom.

Ouvrir une issue demande au jeton la permission Issues en Read and write ; c'est la seule écriture que l'intégration fait sur votre dépôt.

Corrélation release → commit

C'est là que les données GitHub portent leurs fruits. Lorsqu'une occurrence d'exception porte une valeur release qui est un SHA de commit, Quiet Guard la résout vers le commit synchronisé correspondant. Depuis l'issue, vous pouvez ouvrir le commit exact qui était déployé au moment de l'erreur.

Le même commit sert à la trace d'appel : sur la page d'une anomalie, chaque trame de votre application propose Ouvrir ce fichier sur GitHub, à la ligne exacte, dans le commit déployé quand l'occurrence s'est produite (à défaut, dans la branche par défaut du dépôt).

Pour que cela se résolve, deux conditions doivent être réunies :

1. Votre application envoie le SHA du commit déployé dans context.release du payload d'exception.
2. Ce commit a été synchronisé depuis GitHub.

Astuce : le SDK Laravel détecte le SHA tout seul depuis le checkout ou un fichier REVISION, et la page de configuration donne une recette par mode de déploiement (Forge, Envoyer, GitHub Actions, Docker). Lancez ensuite une synchronisation GitHub après chaque déploiement, pour que le lien erreur → commit soit toujours disponible.