Intégration GitHub

Une fois GitHub connecté, Multica associe automatiquement les pull requests à partir des identifiants de tâche. Le détail de la tâche affiche directement l'état de la PR, l'ampleur des modifications, les résultats de la CI et les conflits de fusion.

L'intégration GitHub se contente de lire les dépôts autorisés lors de l'installation ; elle ne pousse jamais de commits, de commentaires ni de status checks.

Multica auto-hébergé peut aussi connecter en parallèle des instances Forgejo, Gitea ou GitLab auto-hébergées, avec la même association automatique des PR, le même passage à Terminé à la fusion et le même affichage de la CI. Le point d'entrée est Paramètres → Intégrations → Fournisseurs git (auto-hébergés) ; voir Fournisseurs Git auto-hébergés. Multica Cloud ne propose pas ce point d'entrée.

Connecter GitHub

Un propriétaire ou un administrateur de l'espace de travail peut effectuer la connexion :

1. Ouvrez Paramètres → GitHub.
2. Activez l'interrupteur principal de l'intégration GitHub, Activer les fonctions GitHub.
3. Cliquez sur Connecter GitHub.
4. Sur GitHub, choisissez le compte ou l'organisation, puis autorisez tous les dépôts ou une sélection d'entre eux.
5. Revenez sur Multica une fois l'installation terminée.

L'état de la connexion s'affiche sur la même page. Les membres ordinaires peuvent consulter cet état, mais ne peuvent ni connecter, ni déconnecter, ni modifier les interrupteurs.

Interrupteurs de fonctions

Paramètres → GitHub comporte quatre interrupteurs :

Associer une PR à une tâche

Le plus simple est de mettre l'identifiant de la tâche dans le nom de branche ou le titre de la PR. Par exemple, pour la tâche MUL-123 :

mul-123-fix-login-redirect

MUL-123 Fix the redirect after login

Multica ignore la casse et ne reconnaît que le préfixe de tâche de l'espace de travail courant. Une même PR peut être associée à plusieurs tâches.

Si l'identifiant n'apparaît que dans la description de la PR, vous devez utiliser l'un des mots-clés de clôture de GitHub :

Closes MUL-123
Fixes MUL-123
Resolves MUL-123

Une simple mention dans la description, comme Related to MUL-123, n'associe pas du tout la PR à cette tâche. Les messages de commit et les commentaires de PR ne déclenchent pas non plus l'association.

Voir les PR d'une tâche

Une fois associées, les PR apparaissent dans le bloc Pull requests du détail de la tâche. Chaque entrée affiche :

• le dépôt, le numéro, le titre et l'auteur ;
• l'état Ouverte, Brouillon, Fusionnée ou Fermée ;
• le nombre de lignes ajoutées et supprimées, et le nombre de fichiers modifiés ;
• le statut CI : toutes les vérifications ont réussi (avec leur nombre), certaines sont en échec (avec le nom des vérifications concernées) ou certaines sont en cours ; les PR sans vérification configurée n'affichent pas cet élément — « aucune vérification » n'est jamais considéré comme une réussite ;
• la possibilité de fusion : « Prête à fusionner » (uniquement lorsque GitHub signale un état de fusion propre), « Conflits de fusion », « Bloquée » ou « En retard sur la base ».

Le statut CI et la possibilité de fusion proviennent d'instantanés que Multica récupère depuis l'API GitHub, et les deux sont indépendants ; les PR fusionnées ou fermées n'affichent plus ni l'un ni l'autre. Lorsque GitHub est momentanément indisponible, la carte conserve le dernier instantané et le signale comme périmé au lieu de se vider.

Cliquez sur une entrée pour ouvrir la PR sur GitHub. Désactiver la Barre latérale des pull requests masque seulement ce bloc ; cela ne déconnecte rien.

Quand une PR fusionnée fait passer une tâche à Terminé

Une PR fusionnée ne signifie pas forcément que la tâche est terminée. Multica ne fait passer une tâche à Terminé que lorsque toutes les conditions suivantes sont réunies :

1. au moins une PR associée et fusionnée a utilisé un mot-clé de clôture immédiatement suivi de l'identifiant, comme Closes MUL-123 (les formes avec des mots intercalés, comme Closes login MUL-123, ne comptent pas) ;
2. la tâche n'a aucune autre PR associée encore Ouverte ou en Brouillon ;
3. la tâche n'est pas actuellement done ou cancelled.

Ainsi, écrire MUL-123 uniquement dans le nom de branche ou le titre établit l'association, mais ne déclenche pas à lui seul la clôture de la tâche. Une PR fermée sans fusion ne termine pas non plus la tâche.

Le changement de statut est inscrit dans l'activité de la tâche comme une action système, et les membres abonnés à la tâche sont notifiés.

Plusieurs espaces de travail

Une même installation de la GitHub App peut être connectée à plusieurs espaces de travail Multica. Les événements GitHub parviennent à chaque espace de travail séparément et sont comparés au préfixe de tâche propre à chacun.

Par exemple, une PR qui référence à la fois MUL-1 et ENG-2 peut être associée dans deux espaces de travail aux préfixes différents. Les espaces de travail ne voient jamais les tâches les uns des autres.

Déconnecter

Cliquer sur Déconnecter dans Paramètres → GitHub supprime seulement la relation entre l'espace de travail Multica courant et l'installation ; cela ne désinstalle pas l'App de GitHub à votre place. Les enregistrements de PR existants sont conservés, et les nouveaux événements cessent d'arriver dans cet espace de travail.

Pour révoquer l'autorisation d'accès aux dépôts côté GitHub, désinstallez l'App ou ajustez son périmètre de dépôts depuis la page des installations de GitHub Apps de votre compte personnel ou de votre organisation. Après la désinstallation, tous les espaces de travail Multica liés à cette installation cessent de recevoir des événements.

Configuration en auto-hébergement

Multica Cloud n'a pas besoin de cette section. En auto-hébergement, vous devez d'abord créer votre propre GitHub App.

1. Créer une GitHub App

Créez l'App dans Developer settings → GitHub Apps sur GitHub et renseignez :

Permissions de dépôt (Repository permissions) :

Abonnez-vous à ces événements :

• Pull request ;
• Check suite, Check run et Status, qui déclenchent l'actualisation de la CI et de la possibilité de fusion.

Si vous n'avez pas besoin d'afficher la CI dans Multica, vous pouvez vous passer des permissions Checks et Commit statuses ainsi que de leurs événements. Contents reste obligatoire : sans elle, la requête d'instantané échoue complètement et la carte de PR perd aussi l'état de fusion.

2. Définir les variables d'environnement

Récupérez le slug dans l'URL publique de l'App. Par exemple, le slug de https://github.com/apps/multica-acme est multica-acme.

GITHUB_APP_SLUG=multica-acme
GITHUB_WEBHOOK_SECRET=<the webhook secret you entered when creating the App>
FRONTEND_ORIGIN=https://multica.example.com

Si GITHUB_APP_SLUG ou GITHUB_WEBHOOK_SECRET manque, le bouton de connexion est désactivé et le point de terminaison du webhook refuse de traiter les événements.

Les deux variables suivantes sont nécessaires pour que la carte de PR affiche le statut CI et la possibilité de fusion — Multica s'en sert pour s'authentifier en tant qu'App et récupérer les instantanés :

GITHUB_APP_ID=<the GitHub App's numeric ID>
GITHUB_APP_PRIVATE_KEY=<full PEM private key, keeping the BEGIN/END lines and newlines>

Générez la clé privée dans Private keys → Generate a private key de la GitHub App. Sans ces variables, l'intégration fonctionne en mode dégradé : les PR sont toujours reflétées, les tâches sont toujours associées automatiquement et passent à Terminé à la fusion — la carte de PR n'affiche simplement ni CI ni état de fusion.

3. Mettre à jour la base de données et connecter

Lors de la mise à niveau d'un déploiement existant, exécutez d'abord les migrations habituelles de la base de données :

make migrate-up

Redémarrez le serveur API, puis effectuez la connexion dans Paramètres → GitHub.

Dépannage

• Bouton de connexion désactivé : vérifiez que GITHUB_APP_SLUG et GITHUB_WEBHOOK_SECRET parviennent bien au processus de l'API.
• Le webhook renvoie 401 : vérifiez que la GitHub App et l'API utilisent le même secret de webhook, puis relancez la livraison depuis Recent Deliveries sur GitHub.
• PR non associée : vérifiez que le dépôt fait partie du périmètre autorisé de l'App, que l'association automatique est activée et que l'identifiant appartient à l'espace de travail courant.
• Identifiant dans la description, mais PR non associée : utilisez plutôt Closes MUL-123, ou placez l'identifiant dans le nom de branche ou le titre de la PR.
• Aucun statut CI : vérifiez que GITHUB_APP_ID et GITHUB_APP_PRIVATE_KEY sont configurées, et que l'App dispose des permissions Contents, Checks et Commit statuses en lecture seule, avec les événements correspondants souscrits. Sans Contents, tout l'instantané échoue : la carte de PR n'affiche alors ni CI ni état de fusion. Après l'ajout de permissions à une App déjà installée, le propriétaire de chaque installation doit aussi les approuver sur GitHub pour qu'elles prennent effet.
• Tâche non terminée après la fusion de la PR : vérifiez que la PR a utilisé un mot-clé de clôture, et si d'autres PR associées sont encore Ouvertes ou en Brouillon.

Étapes suivantes

• Tâches — le lien entre les transitions de statut et le passage à Terminé à la fusion.
• Ressources de projet — les dépôts utilisés par les agents lors des exécutions.
• Variables d'environnement — la configuration complète de la GitHub App en auto-hébergement.