GitHub

La integracion con GitHub permite conectar tus repositorios de codigo con Almirant para vincular pull requests y commits con work items, ver actividad de desarrollo directamente desde el tablero y dar contexto a los agentes de IA sobre el codigo del proyecto.

Requisitos previos

La integracion de GitHub esta controlada por un feature flag. Para que este disponible en tu instancia de Almirant, la variable de entorno NEXT_PUBLIC_FEATURE_GITHUB debe estar activada.

Conectar GitHub

La conexion se realiza mediante una instalacion de OAuth App de GitHub a nivel de organizacion:

1. Accede a Configuracion > Integraciones > GitHub.
2. Haz clic en Conectar GitHub.
3. GitHub te pedira autorizar a Almirant como OAuth App.
4. Selecciona la organizacion o cuenta donde quieres instalar la aplicacion.
5. Elige los repositorios a los que Almirant tendra acceso (todos o seleccionados).
6. Confirma la instalacion.

Una vez completado, veras el estado de la conexion y los repositorios disponibles en la configuracion de integraciones.

Repositorios seleccionados

Recomendamos dar acceso solo a los repositorios que vas a vincular con proyectos en Almirant, en lugar de dar acceso a todos. Puedes modificar los permisos despues desde la configuracion de GitHub.

Vincular repositorios a un proyecto

Una vez conectado GitHub, puedes vincular uno o mas repositorios a cada proyecto:

1. Accede al proyecto donde quieres vincular repositorios.
2. Ve a la seccion Repositorios.
3. Haz clic en Vincular repositorio.
4. Selecciona el repositorio de la lista de repositorios disponibles.
5. Confirma la vinculacion.

El repositorio queda asociado al proyecto y toda su actividad sera visible desde Almirant.

Pull requests y work items

Una de las funcionalidades mas utiles de la integracion es la vinculacion automatica entre pull requests y work items.

Como vincular un PR a un work item

Incluye el identificador del work item (por ejemplo A-T-42) en el titulo o descripcion del pull request en GitHub. Almirant detectara la referencia y vinculara el PR automaticamente.

Ejemplo de titulo de PR:

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

Ejemplo en descripcion del PR:

## Descripcion
Implementa el sistema de notificaciones push.

Relacionado con: A-T-42

Ver PRs desde Almirant

Desde el detalle de un work item, puedes ver todos los pull requests vinculados con:

• Estado del PR (abierto, cerrado, mergeado).
• Autor y fecha de creacion.
• Enlace directo al PR en GitHub.

Ver commits asociados

Ademas de pull requests, Almirant muestra los commits asociados al work item, proporcionando trazabilidad completa del codigo vinculado a cada tarea.

Actividad de desarrollo

En la vista del proyecto, la seccion de repositorios muestra un resumen de la actividad reciente de desarrollo:

• Ultimos commits en las ramas principales.
• Pull requests abiertos y su estado.
• Actividad de los miembros del equipo en los repositorios.

Contexto para agentes de IA

Cuando un repositorio esta vinculado a un proyecto, los agentes de IA pueden acceder al contexto del codigo para:

• Entender la estructura del proyecto al implementar nuevas features.
• Revisar codigo existente durante un code review.
• Generar tests basados en la implementacion actual.
• Responder preguntas tecnicas con conocimiento del codebase real.

Desconectar GitHub

Para desconectar la integracion de GitHub:

1. Accede a Configuracion > Integraciones > GitHub.
2. Haz clic en Desconectar.
3. Confirma la desconexion.

aviso

Desconectar GitHub eliminara la vinculacion de repositorios con los proyectos. Los work items mantendran las referencias historicas a PRs y commits, pero no se actualizaran con nueva informacion.

Para Developers

Variables de entorno

Variable	Descripcion	Obligatoria
NEXT_PUBLIC_FEATURE_GITHUB	Feature flag que activa la integracion de GitHub en el frontend	Si
GITHUB_CLIENT_ID	Client ID de la OAuth App de GitHub	Si
GITHUB_CLIENT_SECRET	Client Secret de la OAuth App de GitHub	Si

Arquitectura de la integracion

La integracion se compone de:

• Frontend: Dominio github en frontend/src/domains/github/ con hooks para la instalacion OAuth y vinculacion de repositorios.
• Backend: Rutas en backend/api/src/routes/ para gestionar instalaciones y repositorios.
• Base de datos: Tablas githubInstallations y repositories en el schema.
• Webhooks: Endpoint que recibe eventos de GitHub (push, PR) y actualiza la informacion en Almirant.