GitHub

Die GitHub-Integration ermöglicht es dir, deine Code-Repositories mit Almirant zu verbinden, um Pull Requests und Commits mit Work Items zu verknüpfen, Entwicklungsaktivitäten direkt im Board anzuzeigen und KI-Agenten Kontext zum Projektcode zu geben.

Voraussetzungen

Die GitHub-Integration wird durch einen Feature-Schalter gesteuert. Damit sie in deiner Almirant-Instanz verfügbar ist, muss die Umgebungsvariable NEXT_PUBLIC_FEATURE_GITHUB aktiviert sein.

GitHub verbinden

Die Verbindung erfolgt über eine organisationweite Installation einer GitHub OAuth App:

1. Gehe zu Einstellungen > Integrationen > GitHub.
2. Klicke auf GitHub verbinden.
3. GitHub fordert dich auf, Almirant als OAuth App zu autorisieren.
4. Wähle die Organisation oder das Konto aus, in der bzw. dem du die Anwendung installieren möchtest.
5. Wähle die Repositories aus, auf die Almirant zugreifen darf (alle oder ausgewählte).
6. Bestätige die Installation.

Nach dem Abschluss siehst du den Verbindungsstatus und die verfügbaren Repositories in der Integrationskonfiguration.

Ausgewählte Repositories

Wir empfehlen, nur Zugriff auf die Repositories zu gewähren, die du mit Projekten in Almirant verknüpfen möchtest, statt Zugriff auf alle zu geben. Du kannst die Berechtigungen später in der GitHub-Konfiguration ändern.

Repositories mit einem Projekt verknüpfen

Sobald GitHub verbunden ist, kannst du mit jedem Projekt ein oder mehrere Repositories verknüpfen:

1. Gehe zu dem Projekt, mit dem du Repositories verknüpfen möchtest.
2. Gehe zum Abschnitt Repositorys.
3. Klicke auf Repository verknüpfen.
4. Wähle das Repository aus der Liste der verfügbaren Repositories aus.
5. Bestätige die Verknüpfung.

Das Repository wird mit dem Projekt verknüpft und seine gesamte Aktivität ist über Almirant sichtbar.

Pull Requests und Work Items

Eine der nützlichsten Funktionen der Integration ist die automatische Verknüpfung von Pull Requests und Work Items.

Einen PR mit einem Work Item verknüpfen

Füge die Kennung des Work Items (zum Beispiel A-T-42) in den Titel oder die Beschreibung des Pull Requests in GitHub ein. Almirant erkennt die Referenz und verknüpft den PR automatisch.

Beispiel für einen PR-Titel:

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

Beispiel in der PR-Beschreibung:

## Descripcion
Implementa el sistema de notificaciones push.

Relacionado con: A-T-42

PRs über Almirant anzeigen

In den Details eines Work Items kannst du alle verknüpften Pull Requests anzeigen, einschließlich:

• PR-Status (offen, geschlossen, gemergt).
• Autor und Erstellungsdatum.
• Direkter Link zum PR in GitHub.

Verknüpfte Commits anzeigen

Neben Pull Requests zeigt Almirant die mit dem Work Item verknüpften Commits an und stellt damit die vollständige Nachverfolgbarkeit des jeder Aufgabe zugeordneten Codes bereit.

Entwicklungsaktivität

In der Projektansicht zeigt der Repository-Abschnitt eine Zusammenfassung der aktuellen Entwicklungsaktivität:

• Neueste Commits in den Haupt-Branches.
• Offene Pull Requests und ihr Status.
• Aktivitäten der Teammitglieder in den Repositories.

Kontext für KI-Agenten

Wenn ein Repository mit einem Projekt verknüpft ist, können die KI-Agenten auf den Code-Kontext zugreifen, um:

• die Projektstruktur bei der Implementierung neuer Features zu verstehen.
• bestehenden Code während eines Code Reviews zu prüfen.
• Tests auf Grundlage der aktuellen Implementierung zu generieren.
• technische Fragen mit Kenntnis der tatsächlichen Codebasis zu beantworten.

GitHub trennen

So trennst du die GitHub-Integration:

1. Gehe zu Einstellungen > Integrationen > GitHub.
2. Klicke auf Trennen.
3. Bestätige die Trennung.

Warnung

Durch das Trennen von GitHub wird die Repository-Verknüpfung mit den Projekten entfernt. Work Items behalten die historischen Referenzen auf PRs und Commits, werden aber nicht mit neuen Informationen aktualisiert.

Für Entwickler

Umgebungsvariablen

Variable	Beschreibung	Erforderlich
NEXT_PUBLIC_FEATURE_GITHUB	Feature-Schalter, der die GitHub-Integration im Frontend aktiviert	Ja
GITHUB_CLIENT_ID	Client-ID der GitHub OAuth-App	Ja
GITHUB_CLIENT_SECRET	Client-Geheimnis der GitHub OAuth-App	Ja

Architektur der Integration

Die Integration besteht aus:

• Frontend: Domäne github in frontend/src/domains/github/ mit Hooks für die OAuth-Installation und Repository-Verknüpfung.
• Backend: Routen in backend/api/src/routes/ zur Verwaltung von Installationen und Repositories.
• Datenbank: Tabellen githubInstallations und repositories im Schema.
• Webhooks: Endpunkt, der GitHub-Ereignisse (Push, PR) empfängt und die Informationen in Almirant aktualisiert.