Commits automatisch mit Karten verknüpfen

Wer einen Kartenschlüssel in den Commit schreibt, hat die Arbeit eigentlich schon dokumentiert — sie steht nur an der falschen Stelle. Diese Anleitung richtet einen post-commit-Hook ein, der jeden Commit automatisch an die passende Karte hängt: mit Autor, SHA, Branch und Nachricht. Die Git-Integration ist im Developer-Plan enthalten.

Was du brauchst

• Den Developer-Plan — dort liegen Git-Integration und API-Zugriff. Siehe Preise.
• git und curl auf dem Rechner.
• Ein Repository — egal ob GitHub, GitLab, Gitea oder selbst gehostet.

1. Plan und Werkzeuge prüfen

Der Hook spricht mit der Zuuna-API. Beides — Git-Integration und API-Zugriff — gehört zum Developer-Plan; in niedrigeren Plänen antwortet die Schnittstelle nicht.

2. API-Token erstellen

Öffne die Developer-Konsole in Zuuna und erstelle ein Token. Gib ihm nur den Scope, den der Hook wirklich braucht: git:write. Der Token beginnt mit zk_live_ und wird dir genau einmal angezeigt — danach ist nur noch sein Präfix sichtbar.

3. CLI installieren

Im Wurzelverzeichnis deines Repositories:

curl -o zuuna https://app.zuuna.de/zuuna.sh && chmod +x zuuna

4. Repository verbinden

./zuuna init https://app.zuuna.de zk_live_dein_token [gruppen-id]

Das schreibt .git/zuuna.conf und installiert einen post-commit-Hook. Ab jetzt schickt jeder Commit zwei Ereignisse an Zuuna: den Commit selbst und den Branch, auf dem er entstanden ist. Beides landet in .git/ und damit nicht im Repository — dein Token wird nicht mitversioniert.

5. Ersten Commit mit Kartenschlüssel schreiben

Und hier kommt der Teil, den kaum ein Werkzeug erklärt: wo der Kartenschlüssel steht, entscheidet, was passiert.

Wo der Schlüssel steht	Bedeutung	Wirkung
Betreffzeile oder Branch-Name	Arbeit	verknüpft und löst Automatisierungen aus
Body, nach fix, fixes, closes, resolves, implements	Arbeit	verknüpft und löst aus
Body, nach ref, see, part of, related to, via	Referenz	verknüpft nur — keine Automatisierung
Body als Fließtext, ohne Schlüsselwort	—	gar nichts

Diese Unterscheidung gibt es aus einem konkreten Grund: Ein Commit mit „notiert als ZNA-248 für später“ im Body hat einmal vier unangetastete Backlog-Karten auf „Git committed“ gezogen. Das Board behauptete Arbeit, die nie stattgefunden hatte. Nennt man dieselbe Karte an beiden Stellen, gewinnt Arbeit vor Referenz.

Ein sauberer Commit sieht also so aus:

ZNA-164: Sprint-Auswahl im Backlog ergänzt

Setzt die Auswahl auf den aktiven Sprint vor.
ref ZNA-165

ZNA-164 zählt als Arbeit und bewegt die Karte, ZNA-165 wird nur verlinkt.

6. Ergebnis auf der Karte prüfen

Öffne die Karte. Im Development-Bereich stehen jetzt Commit, Autor, SHA und Branch. Damit ist die Frage „was gehört eigentlich zu diesem Ticket?“ nicht mehr eine Suche im Git-Log, sondern eine Zeile auf der Karte.

Wenn es nicht klappt

• Nichts passiert. Prüf zuerst, ob der Hook läuft: .git/hooks/post-commit muss existieren und ausführbar sein. Ein Klon des Repositories bringt ihn nicht mit.
• Der Commit ist verknüpft, aber die Karte bewegt sich nicht. Dann stand der Schlüssel im Body ohne Schlüsselwort oder hinter einem Referenz-Schlüsselwort. Siehe die Tabelle oben — das ist Absicht, kein Fehler.
• Falsches Präfix. Der Schlüssel muss dem Kartenpräfix der Gruppe entsprechen und wird groß geschrieben ausgewertet.
• 401 oder 403 im Hook-Log. Token abgelaufen, widerrufen, oder ohne git:write. Neu erstellen und zuuna init erneut ausführen.

Nächste Schritte

• GitHub Pull Requests mit dem Board verbinden — der nächste Schritt nach Commits.
• Karten automatisch durch Git bewegen — aus Ereignissen Regeln machen.
• Git auf dem Board und Projektmanagement für Entwickler.