GitHub

L'intégration GitHub permet de connecter vos dépôts de code à Almirant afin de lier des pull requests et des commits aux work items, d'afficher l'activité de développement directement depuis le tableau et de fournir aux agents IA du contexte sur le code du projet.

Prérequis

L'intégration GitHub est contrôlée par un feature flag. Pour qu'elle soit disponible dans votre instance Almirant, la variable d'environnement NEXT_PUBLIC_FEATURE_GITHUB doit être activée.

Connecter GitHub

La connexion s'effectue par une installation de GitHub OAuth App au niveau de l'organisation :

1. Accédez à Configuration > Intégrations > GitHub.
2. Cliquez sur Connecter GitHub.
3. GitHub vous demandera d'autoriser Almirant en tant qu'OAuth App.
4. Sélectionnez l'organisation ou le compte où vous souhaitez installer l'application.
5. Choisissez les dépôts auxquels Almirant aura accès (tous ou une sélection).
6. Confirmez l'installation.

Une fois l'opération terminée, vous verrez l'état de la connexion et les dépôts disponibles dans la configuration des intégrations.

Dépôts sélectionnés

Nous recommandons de n'accorder l'accès qu'aux dépôts que vous allez lier à des projets dans Almirant, plutôt qu'à tous les dépôts. Vous pouvez modifier les permissions ultérieurement depuis la configuration GitHub.

Lier des dépôts à un projet

Une fois GitHub connecté, vous pouvez lier un ou plusieurs dépôts à chaque projet :

1. Accédez au projet auquel vous souhaitez lier des dépôts.
2. Accédez à la section Dépôts.
3. Cliquez sur Lier un dépôt.
4. Sélectionnez le dépôt dans la liste des dépôts disponibles.
5. Confirmez le lien.

Le dépôt est associé au projet et toute son activité sera visible dans Almirant.

Pull requests et work items

L'une des fonctionnalités les plus utiles de l'intégration est la liaison automatique entre les pull requests et les work items.

Lier une PR à un work item

Incluez l'identifiant du work item (par exemple, A-T-42) dans le titre ou la description de la pull request dans GitHub. Almirant détectera la référence et liera automatiquement la PR.

Exemple de titre de PR :

feat: Implementar sistema de notificaciones [A-T-42]

Exemple dans la description de la PR :

## Descripcion
Implementa el sistema de notificaciones push.

Relacionado con: A-T-42

Voir les PR depuis Almirant

Depuis le détail d'un work item, vous pouvez voir toutes les pull requests liées avec :

• L'état de la PR (ouverte, fermée, merged).
• L'auteur et la date de création.
• Un lien direct vers la PR dans GitHub.

Voir les commits associés

En plus des pull requests, Almirant affiche les commits associés au work item, ce qui fournit une traçabilité complète du code lié à chaque tâche.

Activité de développement

Dans la vue du projet, la section des dépôts affiche un résumé de l'activité de développement récente :

• Les derniers commits sur les branches principales.
• Les pull requests ouvertes et leur état.
• L'activité des membres de l'équipe dans les dépôts.

Contexte pour les agents IA

Lorsqu'un dépôt est lié à un projet, les agents IA peuvent accéder au contexte du code pour :

• Comprendre la structure du projet lors de l'implémentation de nouvelles features.
• Réviser le code existant lors d'un code review.
• Générer des tests à partir de l'implémentation actuelle.
• Répondre à des questions techniques en connaissant le codebase réel.

Déconnecter GitHub

Pour déconnecter l'intégration GitHub :

1. Accédez à Configuration > Intégrations > GitHub.
2. Cliquez sur Déconnecter.
3. Confirmez la déconnexion.

attention

Déconnecter GitHub supprimera le lien entre les dépôts et les projets. Les work items conserveront les références historiques aux PRs et commits, mais ils ne seront plus mis à jour avec de nouvelles informations.

Pour les développeurs

Variables d'environnement

Variable	Description	Obligatoire
NEXT_PUBLIC_FEATURE_GITHUB	Feature flag qui active l'intégration GitHub dans le frontend	Oui
GITHUB_CLIENT_ID	Client ID de l'OAuth App GitHub	Oui
GITHUB_CLIENT_SECRET	Client Secret de l'OAuth App GitHub	Oui

Architecture de l'intégration

L'intégration se compose des éléments suivants :

• Frontend : Domaine github dans frontend/src/domains/github/ avec des hooks pour l'installation OAuth et la liaison des dépôts.
• Backend : Routes dans backend/api/src/routes/ pour gérer les installations et les dépôts.
• Base de données : Tables githubInstallations et repositories dans le schema.
• Webhooks : Endpoint qui reçoit les événements GitHub (push, PR) et met à jour les informations dans Almirant.