Intégration GitHub

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

trackica 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, les mêmes changements de statut à la fusion et le même affichage de la CI. Le point d'entrée est Paramètres → Intégrations → Hébergement Git ; voir Fournisseurs Git auto-hébergés. trackica 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’intégration 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 trackica 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 propose les réglages suivants :

Ce réglage de statut s’applique à tous les hébergeurs Git, y compris aux hébergeurs auto-hébergés, où le même réglage est disponible.

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

trk-123-fix-login-redirect

TRK-123 Fix the redirect after login

trackica 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 TRK-123
Fixes TRK-123
Resolves TRK-123

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

Vous pouvez aussi associer une PR manuellement : dans le bloc Pull requests, cliquez sur + et collez son URL. Pour retirer une PR, ouvrez son menu ⋯ → Retirer de la tâche ; trackica ne la réassociera pas à partir du titre ou du nom de 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 trackica 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 les PR fusionnées changent le statut d’une tâche

Dans Paramètres → Intégrations → GitHub → Après la fusion des PR, déplacer la tâche vers, choisissez Terminé (valeur par défaut des nouveaux espaces), un autre statut commencé ou terminé, y compris un statut personnalisé, ou Ne pas modifier. Les espaces existants conservent leur comportement : si les fusions ne terminaient pas systématiquement leurs tâches, leur réglage initial est Ne pas modifier.

Une tâche passe au statut choisi lorsque ces conditions sont réunies :

1. toutes les PR associées sont Fusionnées ; une PR ouverte, en brouillon ou fermée sans fusion bloque le changement tant qu’elle reste associée ;
2. la tâche n’est ni done, ni cancelled, ni en triage ; elle n’a pas déjà le statut cible et l’option Pull requests → ⋯ → Conserver le statut à la fusion des PR n’est pas activée.

Le mode d’association ne change pas cette règle : titre, branche et Closes TRK-123 dans la description sont équivalents. Si une PR ne livre qu’une partie du travail, ou si une publication ou une vérification doit suivre, conservez le statut depuis le menu Pull requests de cette tâche.

La vérification s’exécute lorsqu’une PR associée fusionne, lorsqu’une PR est associée ou lorsqu’une association est retirée. Rouvrir une tâche ne la déplace pas immédiatement ; la prochaine fusion associée déclenche la vérification. Modifier le réglage ne déplace pas rétroactivement les tâches dont les PR ont déjà fusionné.

Le changement apparaît dans l’activité comme une action système qui nomme les PR ; les abonnés à la tâche sont notifiés. Sous la liste des PR, une ligne indique le prochain changement ou la PR fermée sans fusion qui le bloque. Elle est absente si le statut est conservé ou si la tâche a déjà le statut cible.

Plusieurs espaces de travail

Une même installation de la GitHub App peut être connectée à plusieurs espaces de travail trackica. 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 TRK-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 un identifiant correspond à une tâche dans plusieurs espaces connectés partageant le même préfixe, trackica ne l’associe automatiquement dans aucun d’eux. Associez la PR manuellement dans le bon espace pour éviter de terminer une tâche sans rapport.

Déconnecter

Choisir Déconnecter dans le menu ⋯ de la ligne GitHub, sur Paramètres → Code, supprime seulement la relation entre l'espace de travail trackica 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 trackica liés à cette installation cessent de recevoir des événements.

Configuration en auto-hébergement

L’administrateur du déploiement privé doit d’abord créer et configurer une 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.

Les instantanés de PR utilisent les API REST Pull requests, Checks et Commit statuses. La permission Contents n'est pas nécessaire.

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/trackica-acme est trackica-acme.

GITHUB_APP_SLUG=trackica-acme
GITHUB_WEBHOOK_SECRET=<the webhook secret you entered when creating the App>
FRONTEND_ORIGIN=https://trackica.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 — trackica 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 changent de statut à la fusion selon le réglage — 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 → Code.

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 TRK-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 Pull requests, Checks et Commit statuses en lecture seule, avec les événements correspondants souscrits. La permission Contents n'est pas nécessaire. Après l'ajout de permissions à une App déjà installée, le propriétaire de chaque installation doit les approuver sur GitHub pour qu'elles prennent effet.
• Tâche non terminée après la fusion de la PR : consultez la ligne sous la liste des PR : elle indique les PR ouvertes ou fermées sans fusion, ou la conservation du statut. Une ligne absente signifie que le réglage conserve le statut ou que le statut cible est déjà atteint.

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