---
title: "Connecteur GitHub (backlog ↔ issues / PR)"
module: integrations
type: functional
status: active
updated: 2026-07-31
---

# 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](../projects/backlog-workflow-builder.md).

## 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`