Connecteur GitHub (backlog ↔ issues / PR)

Doc fonctionnelle : décrit le quoi et le pourquoi (point de vue utilisateur / chef de projet).

À quoi ça sert

Relier les items de backlog à GitHub et faire avancer automatiquement le statut du backlog selon ce qui se passe sur GitHub (label posé sur une PR, PR mergée, issue fermée). C'est le socle qui rend vivants les déclencheurs GitHub des automatisations du backlog.

Comment ça marche (côté utilisateur)

1. Connexion (réservée aux développeurs ISI) : dans le Store, le connecteur GitHub se configure avec les identifiants d'une GitHub App (App ID, clé privée .pem, webhook secret, Installation ID) et la liste des dépôts. Les secrets sont chiffrés.
2. Nommage de branche : depuis un item de backlog, on génère ‹type›/backlog-‹id›-‹titre› (cf. générateur de branche). Ce nom relie automatiquement la PR à l'item.
3. Synchronisation entrante : quand une PR change (label posé ou retiré, merge) ou qu'une issue se ferme, GitHub notifie l'app (webhook). L'item de backlog lié voit alors s'exécuter les règles d'automatisation correspondantes (ex. label in review posé → statut « En cours »). La pose et le retrait d'un label sont deux déclencheurs distincts (« Label de PR posé » / « Label de PR retiré ») : retirer un label ne déclenche jamais une règle « label posé », et réciproquement.
4. Labels dans le builder : dans une règle « Label de PR posé » ou « Label de PR retiré », le champ label propose les labels réels des dépôts connectés (sinon saisie libre). Le champ « Dépôts » du connecteur n'a plus besoin d'être rempli pour ça : à défaut, les dépôts auxquels la GitHub App a accès sont récupérés automatiquement. Préférer le choix dans la liste à la saisie libre — un label tapé à la main qui diffère d'un caractère (emoji, espace) produit une règle qui ne se déclenchera jamais.
5. Sortant (backlog → GitHub) : une règle peut poser ou retirer un label sur la/les PR liée(s) (action « Poser / retirer un label GitHub ») — reverse sync, ex. statut → « À tester » ⇒ poser le label need testing sur la PR.
6. PR / issues liées : la fiche d'un item affiche les PR/issues liées (état ouverte / mergée / fermée + lien direct GitHub).

Règles d'accès

• Configuration du connecteur réservée aux développeurs ISI (isDeveloper), côté écran et serveur.
• Mono-organisation ISI aujourd'hui ; l'architecture est isolée par entité (une instance = un tenant) pour rester activable en multi-client plus tard.
• Cloisonnement vérifié à la réception : un webhook ne peut agir que sur les items de son entité. Une PR (ou une issue) citant un item appartenant à un autre client est ignorée — aucune liaison, aucune automatisation — et l'événement est consigné dans le journal. Sans effet en mono-organisation ISI, où tous les items relèvent de la même entité.

Quand ça ne marche pas

Les pannes de la chaîne GitHub → backlog sont consignées dans un journal dédié aux automatisations : le fichier workflows.log, à ouvrir dans le Log-Viewer (tuile « Log-Viewer » de /admin → onglet Actions, puis workflows.log dans la liste des fichiers). Les messages sont rédigés pour être lisibles sans plonger dans le code :

• connecteur inutilisable (secrets à ressaisir), dépôt non déclaré, item de backlog référencé inexistant ou appartenant à une autre entité, PR sur une branche feature//bugfix//hotfix/ sans backlog-‹id› (donc jamais rattachée), règle qui ne se déclenche pas, action en échec, notification non délivrée ;
• webhooks rejetés pour signature invalide, à un niveau volontairement bas : un scan externe ne doit pas ressembler à une panne applicative.

Chaque ligne indique le dépôt, le numéro de PR, l'item et la règle concernés. Deux réflexes de lecture :

• suivre un événement de bout en bout : rechercher son identifiant de livraison (delivery, visible sur chaque ligne) → réception du webhook, traitement, règle évaluée, action exécutée ;
• ne voir que ce qui demande une action : filtrer sur les niveaux notice et au-dessus. Tout ce qui est normal mais fréquent (re-livraison, événement non géré, branche dependabot/*) reste en dessous.

Les journaux ne sont pas cloisonnés par client : leur consultation est réservée aux développeurs ISI. Un administrateur non développeur ne voit pas la tuile et l'URL renvoie une erreur d'accès.

Points d'attention

• Prérequis : une GitHub App doit être créée sur l'org ISI (permissions Issues:RW, Pull requests:R, Contents:R, Metadata:R ; events Pull request + Issues ; webhook URL /webhooks/github).
• Liaison des issues : l'auto-liaison par nom de branche concerne les PR. Les issues ne se lient pas encore automatiquement (création sortante d'issue = livrable suivant).
• Sortant : poser/retirer un label sur une PR liée est actif (action de workflow). La création d'issue depuis le backlog reste à faire (livrable suivant).

Voir aussi

• Doc technique : ../../.claude/technical-docs/integrations/github-connector.md
• Automatisations du backlog : ../projects/backlog-workflow-builder.md