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.

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. 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 :

• 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).

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 Sync GitHub sur le 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.

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.

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 : configurez votre pipeline de déploiement pour définir la release au SHA Git déployé, et lancez une synchronisation GitHub après chaque déploiement, pour que le lien erreur → commit soit toujours disponible.