Git-Integration#

Verbinde jedes Hinata-Projekt mit einem oder mehreren Repositories auf GitHub, GitLab oder Bitbucket — und deine Vorgänge bekommen eine lebendige Entwicklungs-Timeline: Branches, Commits, Pull-/Merge-Requests und CI-Builds, die einen Vorgangsschlüssel referenzieren, erscheinen direkt am jeweiligen Vorgang. Dazu kommen Smart Commits (einen Vorgang direkt aus der Commit-Nachricht heraus bearbeiten) und Status-Automatisierung (echte Git-Ereignisse bewegen Vorgänge durch deinen Workflow).

Alles hier ist echt — nichts wird emuliert oder vorgetäuscht. Der Server wickelt einen tatsächlichen OAuth-Flow mit dem Anbieter ab, registriert einen signierten Webhook und speichert ein Ereignis erst, nachdem dessen Signatur gegen das beim Verbinden hinterlegte Secret verifiziert wurde.

Was du am Vorgang bekommst#

Sobald ein Projekt verbunden ist, zeigt jeder Vorgang ein Dev-Info-Panel, das aus verifizierten Webhook-Ereignissen aufgebaut wird:

Du kannst einen verknüpften PR/MR auch direkt aus dem Vorgang bearbeiten, ohne Hinata zu verlassen:

POST /api/v1/issues/{key}/dev-info/prs/{number}/merge   → mergen
POST /api/v1/issues/{key}/dev-info/prs/{number}/ready    → als bereit zur Review markieren
GET  /api/v1/issues/{key}/dev-info                        → das Panel lesen

Das Lesen von Dev-Infos oder das Bearbeiten eines PR erfordert Projektmitgliedschaft; das Ändern der Verbindung eines Projekts erfordert die Rolle Project Lead oder Admin.

Betreiber-Einrichtung (einmalig, plattformweit)#

Die Git-Integration wird einmal pro Plattform konfiguriert, nicht pro Projekt. Du registrierst eine OAuth-App pro Anbieter und gibst dem Server ihre Zugangsdaten; danach kann jeder Project Lead darüber Repos verbinden.

1. OAuth-App-Zugangsdaten hinterlegen#

Registriere bei jedem gewünschten Anbieter eine OAuth-App (GitHub / GitLab) bzw. einen OAuth-Consumer (Bitbucket) und gib Hinata Client-ID + Secret — entweder im Adminbereich → Git-Integration der App (in MongoDB gespeichert, ohne Neustart wirksam) oder per Umgebungsvariablen. Wie überall in Hinata überschreibt die Datenbank die Umgebung, und Secrets sind in der Admin-API write-only — sie werden nie zurückgegeben.

2. Öffentliche API-Basis setzen#

Sowohl der OAuth-Callback als auch die Webhooks müssen vom Anbieter aus erreichbar sein, deshalb muss Hinata seine eigene öffentliche API-Basis kennen. Setze dafür HINATA_GIT_WEBHOOK_BASE_URL, z. B.:

HINATA_GIT_WEBHOOK_BASE_URL=https://api.track.example.com/api/v1

Bleibt sie leer, leitet Hinata sie aus HINATA_BASE_URL + /api/v1 ab.

3. OAuth-Callback registrieren#

Trage bei jedem Anbieter als Autorisierungs-Callback-URL der OAuth-App den öffentlichen Callback des Servers ein:

<öffentliche-api-basis>/git/oauth/callback

Mit der Basis von oben ist das https://api.track.example.com/api/v1/git/oauth/callback.

Der OAuth-Flow (serverseitig vermittelt)#

Das Verbinden eines Repos durchläuft einen echten dreibeinigen OAuth-Flow, den der Server vermittelt, damit die App nie das Client-Secret des Anbieters hält. Der nicht erratbare, kurzlebige state (in MongoDB mit 15-Minuten-TTL gespeichert) verbindet den Browser-Umweg wieder mit dem Projekt:

App   POST /projects/{id}/git/oauth/start   (Anbieter)
        │
        ▼
Server  baut Authorize-URL des Anbieters, speichert Session-State (Mongo, TTL 15m)
        │  liefert { authorizeUrl, state }
        ▼
Nutzer  öffnet die Authorize-URL im Browser und stimmt zu
        │
        ▼
Anbieter  GET /git/oauth/callback?code&state   (öffentlich, kein Bearer-Token)
        │
        ▼
Server  tauscht code → Access-Token, speichert es AES-GCM-verschlüsselt
        │  markiert die Session als AUTHORIZED
        ▼
App     pollt GET /git/oauth/session/{state}  → AUTHORIZED
        │
        ▼
App     GET  /projects/{id}/git/owners        → Owner/Org wählen
        App  GET  /projects/{id}/git/repos     → Repository wählen
        App  POST /projects/{id}/git/connect   → verbinden (registriert den Webhook)

Der Callback-Endpunkt ist öffentlich — der Anbieter leitet den Browser des Nutzers ohne Bearer-Token dorthin — seine Sicherheit ruht daher vollständig auf dem nicht erratbaren state. Er liefert eine kleine HTML-Seite zurück, die dem Nutzer sagt, dass er den Tab schließen und zu Hinata zurückkehren kann.

Selbst betriebene Server (Enterprise / Data Center)#

Selbst gehostete Instanzen von GitHub Enterprise, GitLab (self-managed) und Bitbucket Data Center überspringen den OAuth-Tanz komplett. Verbinde sie stattdessen mit einer Repo-URL und einem Personal Access Token:

POST /api/v1/projects/{id}/git/connect-token
{ "repoUrl": "https://git.example.com/team/app.git", "token": "<personal-access-token>" }

Der Token wird genau wie ein OAuth-Token AES-GCM-verschlüsselt gespeichert, und dieselbe Webhook-Registrierung und dieselben Verknüpfungsregeln gelten.

Webhooks#

Beim Verbinden registriert der Server einen Hook (für push, Branch-create, PR/MR und CI-Ereignisse), der auf einen öffentlichen, signaturgeprüften Empfänger zeigt und mit einem projektspezifischen Secret signiert wird, das beim Verbinden erzeugt wird. Jede eingehende Zustellung wird verifiziert, bevor irgendetwas gespeichert wird:

Der Empfänger findet über das Repository im Payload das Projekt (und das exakt verbundene Repo), verifiziert das Secret dieser Verbindung und verknüpft das Ereignis erst dann mit Vorgangsschlüsseln. Ein unbekanntes Repository wird stillschweigend mit 200 ignoriert; ein bekanntes Repository, dessen Signatur nicht verifiziert, wird als nicht autorisiert abgewiesen.

Verknüpfungsregeln#

Die Regeln sind bewusst streng, damit deine Vorgänge ehrlich bleiben:

• Branch → verknüpft über den Vorgangsschlüssel im Branch-Namen.
• Commit → verknüpft nur über den/die Vorgangsschlüssel in der Commit-Nachricht. Er wird nie nur deshalb verknüpft, weil er auf dem Branch eines Vorgangs liegt.
• PR / MR → verknüpft über den/die Vorgangsschlüssel in Titel oder Quell-Branch.
• Ein Schlüssel verknüpft nur mit einem echten Vorgang, der zum Projekt dieses Repos gehört — ein Schlüssel, der auf einen nicht existierenden Vorgang oder einen Vorgang in einem anderen Projekt zeigt, wird ignoriert.

Automatisierung#

Die Automatisierung wird pro Projekt gegen die eigenen Workflow-Status dieses Projekts konfiguriert und verbindet echte Git-Ereignisse mit Status-Übergängen:

Smart Commits#

Trailer in einer Commit-Nachricht wirken direkt auf den referenzierten Vorgang. Smart Commits müssen in den Automatisierungs-Einstellungen des Projekts aktiviert sein; dann gilt für einen Vorgangsschlüssel in der Nachricht:

ASTA-42 #comment Nullpointer bei leerer Suche behoben #time 45m #in-review

Dieser eine Commit fügt einen Kommentar hinzu, bucht 45 Minuten und bewegt ASTA-42 nach In Review. Ein unbekanntes #word (kein passender Status) oder ein Schlüssel ohne echten Vorgang wird stillschweigend übersprungen — der Rest der Nachricht greift trotzdem.

Mehrere Repositories pro Projekt#

Ein Projekt kann mehrere Repositories verbinden — etwa ein App-Repo und ein Server-Repo, die dasselbe Team betreut. Was projektweit geteilt und was pro Repo ist:

• Projektweit geteilt: die Automatisierungsregeln und die Branch-Vorlage (Standard {key}-{summary}, um aus einem Vorgang einen Branch-Namen vorzuschlagen).
• Pro Repository: der eigene Zugriffs-Token, der eigene Webhook samt Signatur-Secret und der eigene Default-Branch.

Nur Arbeit, die in ein verbundenes Repo gepusht wird, erscheint an den Vorgängen des Projekts. Verwalte die zusätzlichen Repos neben dem primären; Trennen oder erneutes Synchronisieren kann ein einzelnes Repo per ID ansprechen:

POST   /api/v1/projects/{id}/git/connect         → Repo hinzufügen (OAuth)
POST   /api/v1/projects/{id}/git/connect-token   → selbst betriebenes Repo hinzufügen (PAT)
POST   /api/v1/projects/{id}/git/resync?repoId=… → Status eines Repos neu laden
DELETE /api/v1/projects/{id}/git?repoId=…        → ein Repo trennen (repoId weglassen = alle)
PATCH  /api/v1/projects/{id}/git/branch-template → geteilte Branch-Vorlage setzen

Sicherheit#

• Verschlüsselung im Ruhezustand: Access-Tokens und verbindungseigene Webhook-Secrets werden mit HINATA_GIT_TOKEN_SECRET AES-GCM-verschlüsselt und nie von der API zurückgegeben (Secrets sind im Adminbereich write-only).
• Signaturgeprüfte Aufnahme: Kein Webhook-Ereignis wird gespeichert, wenn seine Signatur (HMAC / Token / Query-Secret) nicht gegen das hinterlegte projektspezifische Secret verifiziert. Unbekannte Repos werden ignoriert; falsche Signaturen abgewiesen.
• Least Privilege: Dev-Infos lesen oder einen PR bearbeiten erfordert Projektmitgliedschaft; Verbinden, Trennen oder Ändern der Automatisierung erfordert die Rolle Project Lead oder Admin.
• Begrenzter Zustand: Commits und Builds pro Vorgang sind gedeckelt und werden getrimmt, damit ein aktives Repo kein unbegrenztes Panel wachsen lässt.

Verwandte Seiten#

• Projekte & Teams — Vorgangsschlüssel, Workflows und Mitgliedschaft.
• Vorgänge & Hierarchie — wo das Dev-Info-Panel erscheint.
• Adminbereich — wo OAuth-App-Zugangsdaten zur Laufzeit liegen.
• Konfigurationsreferenz — der vollständige HINATA_GIT_*-Satz.