Intégration GitHub

Une fois GitHub connecté, Clowld Space 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.

Clowld Space 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. Clowld Space Cloud ne propose pas ce point d'entrée.

Les réglages de clôture automatique des PR, exceptions par tâche et exclusions d’association sont disponibles depuis 1.2.4 avec le serveur et le client correspondants.

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 Clowld Space 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 :

Dans Paramètres → Intégrations → GitHub ou la page Git auto-hébergé, choisissez le statut après fusion : Terminé par défaut, un statut de catégorie en cours ou terminé (personnalisé compris), ou aucun changement. Bloqué est exclu. Le réglage est commun à tous les fournisseurs.

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 CS-123 :

cs-123-fix-login-redirect

CS-123 Fix the redirect after login

Clowld Space 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 CS-123
Fixes CS-123
Resolves CS-123

Une simple mention dans la description, comme Related to CS-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.

Pour associer manuellement une PR, utilisez + dans Pull requests et collez son URL. Dans le menu ⋯ d’une ligne, Retirer l’association empêche aussi les événements suivants de la recréer automatiquement à partir du titre ou de la branche.

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 Clowld Space 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é

Dans Paramètres → Intégrations → GitHub ou la page Git auto-hébergé, choisissez le statut après fusion : Terminé par défaut, un statut de catégorie en cours ou terminé (personnalisé compris), ou aucun changement. Bloqué est exclu. Le réglage est commun à tous les fournisseurs.

La tâche passe au statut choisi uniquement si toutes les conditions suivantes sont réunies :

1. au moins une PR associée et fusionnée contenait, dans son titre ou sa description au moment de la fusion, un mot-clé immédiatement suivi de l’identifiant, comme Closes CS-123 ; les mots intercalés et les noms de branche ne comptent pas ;
2. la tâche n'a aucune autre PR associée encore Ouverte ou en Brouillon ;
3. la tâche est acceptée, ni terminée ni annulée, pas déjà dans le statut cible, et son option de conservation du statut après fusion est désactivée.

Un identifiant dans le titre ou la branche ne fait que créer un lien. Le mot-clé doit être présent à la fusion ; l’ajouter ensuite ne déclenche pas de transition. Une PR fermée sans fusion reste dans l’historique et ne bloque pas la transition.

Seuls les événements de PR (fusion, fermeture, association ou retrait) déclenchent la décision. Modifier le réglage ou rouvrir une tâche n’a pas d’effet rétroactif. Les espaces existants gardent leur comportement activé ou désactivé. Le changement est journalisé sans démarrer un agent.

Plusieurs espaces de travail

Une même installation de la GitHub App peut être connectée à plusieurs espaces de travail Clowld Space. 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 CS-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. Si le même identifiant existe dans plusieurs espaces connectés, aucun lien automatique n’est créé : associez manuellement la PR dans le bon espace.

Déconnecter

Cliquer sur Déconnecter dans Paramètres → GitHub supprime seulement la relation entre l'espace de travail Clowld Space 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 Clowld Space liés à cette installation cessent de recevoir des événements.

Configuration en auto-hébergement

Clowld Space 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 Clowld Space, 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/clowld-acme est clowld-acme.

GITHUB_APP_SLUG=clowld-acme
GITHUB_WEBHOOK_SECRET=<the webhook secret you entered when creating the App>
FRONTEND_ORIGIN=https://clowld.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 — Clowld Space 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 CS-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 topic — 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.

• Livraison et reprise