Jira und GitLab verbinden

Viele Teams planen in Jira und halten ihren Code in GitLab. kanman unterstützt diese Kombination: Stories kommen aus einem Jira-Projekt, Codeänderungen gehen als Merge Requests nach GitLab, und GitLab-Pipelines sind die CI, mit der kanman jede Änderung prüft.

Du kannst Jira auch mit GitHub-Code kombinieren oder GitLab-Issues als Tracker nutzen. Die Regeln unten sind dieselben.

Ein Team, das auf seinem eigenen kanman-Board begonnen hat, kann Jira, GitHub oder GitLab später verbinden und seine vorhandenen Stories verknüpfen, statt sie zu kopieren. Siehe kanman ohne Tracker nutzen.

Jira

Was kanman mit Jira tut

Der kanman-Benutzer

kanman handelt in Jira als normaler Benutzer, sodass du in der Jira-Historie siehst, was es getan hat. Wir empfehlen ein eigenes Jira-Konto, zum Beispiel [email protected] mit dem Anzeigenamen “kanman”, mit Zugriff auf das Projekt und den Rechten, Issues anzuzeigen, anzulegen, zu bearbeiten, zu überführen und zu kommentieren.

Verbinden

Jira ist eines der Systeme unter Workspace-Einstellungen > Verbindungen (siehe Verbindungen). Inhaber und Admins verbinden es dort oder direkt in der Team-Einrichtung: Verbinden auf der Jira-Karte im ersten Schritt öffnet dasselbe Formular an Ort und Stelle.

1. Wähle, wo dein Jira läuft:
   • Jira Cloud: deine Site-URL, zum Beispiel https://acme.atlassian.net, die E-Mail-Adresse des kanman-Benutzers und ein API-Token dieses Benutzers. Das Token erstellst du im Atlassian-Konto unter Sicherheit > API-Token.
   • Jira Data Center: die Adresse deines Jira, zum Beispiel https://jira.acme.de, und ein persönliches Zugriffstoken des kanman-Benutzers, erstellt im Jira-Profil unter Persönliche Zugriffstoken.
2. Für ein Jira Data Center, das nur dein Firmennetz erreicht, schalte Über unseren Runner erreichen ein. Die kanman Cloud kontaktiert dein Jira dann nie: Dein selbst gehosteter Runner übernimmt jedes Lesen und Schreiben. In einem Workspace, der alles auf seinen Runnern ausführt, ist das immer so.
3. Wähle Verbinden. kanman speichert das Token als Secret deines Workspaces (es wird nie wieder angezeigt), testet dann die Verbindung und zeigt, was es nutzen darf: Issues, Sprints, Kommentare und, bei Jira Cloud, Jira Product Discovery. Über den Runner läuft der Test, sobald dein Runner online ist.

Ohne Runner muss dein Jira über https aus dem Internet erreichbar sein.

Wenn du ein Team auf dieser Verbindung einrichtest, schlägt der Schritt Projekt und Repositories die Projekte deines Jira vor. Wähle den Projektschlüssel, dann liest kanman die Workflow-Status des Projekts, übernimmt sie als Spalten des Teams und ordnet jedem eine Rolle zu. Der Probelauf am Ende der Einrichtung zeigt das Ergebnis.

Änderungen in Jira erreichen kanman innerhalb weniger Minuten. Für sofortige Aktualisierungen legt eine Jira-Administratorin oder ein Administrator unter System > WebHooks einen Webhook für Issue- und Kommentar-Ereignisse an, mit der URL und dem Secret, die du von kanman erhältst. kanman weist Zustellungen ohne gültige Signatur ab.

Was kanman in Jira tun darf

Auf der Seite Team > Verbindungen des Teams listet der Eintrag Jira alles, was kanman in Jira ändern kann, mit je einer Einstellung: Aus, Erst fragen oder Automatisch.

Beim Verbinden ändert sich nichts von selbst: Was kanman schon für das Team erledigt hat, bleibt Automatisch, alles Neue startet mit Aus. Erwähnungen von Personen ohne Zugang zum Team werden nie zu Arbeit.

Stufst du eine Aktion auf Erst fragen herunter, gilt: kanman fragt im Chat des Teams (“Darf ich das in Jira tun? SBX-12 in Review verschieben”) und handelt nach einem Tipp auf Ja, mach das. Löst eine Person die Änderung selbst aus, etwa indem sie Stories freigibt oder eine Story auf dem Board verschiebt, gilt ihre Handlung als Freigabe. Nur die Teamleitungen ändern diese Einstellungen, und was der Jira-Benutzer nicht darf oder dein Workspace begrenzt, ist nicht wählbar. Jede Änderung, die kanman vornimmt, steht mit einem Link zum Issue in der Aktivität des Teams.

Neben Änderungen an Issues kann kanman dein Jira lesen, wenn es plant und antwortet: Issues und ihre Historie, Kommentare, den aktiven und den nächsten Sprint, Releases und, bei Jira Cloud, Ideen in Jira Product Discovery. Es liest nur, und was es liest, gilt nie als Anweisung.

Status den Spaltenrollen zuordnen

Jira-Status unterscheiden sich je Projekt. Die Team-Einrichtung ordnet jeden Status für dich einer der Rollen von kanman zu: zuerst nach seinem Namen, dann nach seiner Jira-Statuskategorie (siehe Spalten), und zeigt das Ergebnis im Probelauf. Ändern kannst du es in der Zeile Tracker unter Team > Repositories (Ändern im Probelauf bringt dich dorthin, sobald das Team angelegt ist); dort füllt Rollen vorschlagen die Rollen erneut anhand der Statusnamen. Die Einstellungen zeigen die Zuordnung als Diagramm: jeden Jira-Status mit einem Pfeil zum Schritt von kanman, zu dem er führt, und daneben kanmans Schritte mit der Zahl der Status, die dorthin führen; ein Schritt, zu dem kein Status führt, trägt eine Warnung.

Boards mit deutschen Statusnamen werden standardmäßig so zugeordnet:

Weitere gängige Namen werden ebenfalls erkannt, zum Beispiel “Zu erledigen” (backlog), “Bereit zur Entwicklung” (ready), “In Prüfung” (review) und “Erledigt” (done). Prüfe die Zuordnung im Probelauf. Ein Status ohne Rolle bleibt unberührt: kanman verschiebt nie ein Issue in ihn hinein.

In beide Richtungen arbeiten

In der Zeile Tracker eines Teams mit Jira (Team > Repositories) legen zwei weitere Einstellungen fest, wie kanman und dein Jira-Projekt zusammenarbeiten.

Übernahme aus Jira. Wähle, was ein Issue zu kanman bringt:

• Status: ein Issue, das in einen der gewählten Status wechselt.
• Labels: ein Issue, das eines dieser Labels bekommt.
• Erwähnungen: ein Teammitglied schreibt @kanman in einen Kommentar. Es zählen nur Mitglieder deines Workspaces, deren Jira-Konto ihnen an der Jira-Verbindung zugeordnet ist; Erwähnungen von anderen werden nie zu Anweisungen.

kanman liest das Issue, entscheidet, ob es das Issue übernimmt, und sagt es vor dem Start in einem kurzen Kommentar in eigenen Worten: “Ich übernehme das; Plan: …” oder “Ich übernehme das nicht, weil …”. Übernimmt kanman das Issue, legt es eine Story an und verknüpft sie mit dem Issue. Jeder Status, jedes Label und jeder Kommentar bringt ein Issue nur einmal zu kanman. Issues, die schon mit einer Story verknüpft sind, folgen stattdessen dieser Story.

Mit Mit einem Issue testen prüfst du die Regel an einem Issue-Schlüssel, bevor du dich darauf verlässt. Der Test liest das Issue nur: Es wird nichts gespeichert, kommentiert oder gestartet.

Jira folgt der Story. Wähle für jeden Schritt einer Story (Ready, In Arbeit, Review, Done) den einen Jira-Status, in den das Issue wechselt, oder Nicht verschieben. kanman verschiebt das Issue nur in den gewählten Status. Done wartet, bis der Merge bestätigt ist. Merge Request und Browser-Nachweis werden am Issue als Links ergänzt.

Jeder Kommentar, den kanman in Jira schreibt, endet mit einer Zeile, die ihn als von KI geschrieben kennzeichnet. Die Übernahme per Status und Label braucht den oben beschriebenen Jira-Webhook; Erwähnungen kommen auch ohne ihn an, innerhalb weniger Minuten.

GitLab

Was kanman mit GitLab tut

Verbinden

GitLab wird einmal für den Workspace verbunden, von einem Inhaber oder Admin, unter Workspace-Einstellungen > Verbindungen: Öffne GitLab und klicke auf GitLab verbinden. Jedes Team nutzt diese Verbindung für seine Repositories. Wähle, wie kanman sich anmeldet:

• gitlab.com: Wähle Anmelden, speichere und klicke auf Autorisieren; bestätige in GitLab, und die Verbindung zeigt Autorisiert als mit deinem GitLab-Konto. Auch für gitlab.com funktioniert ein Zugriffstoken.
• Dein eigenes GitLab: Gib die Adresse deines GitLab ein, zum Beispiel https://gitlab.acme.de, und ein Zugriffstoken als Token oder Schlüssel.

Aus der kanman Cloud erreicht muss dein GitLab-Server wie Jira über https aus dem Internet erreichbar sein. Ein GitLab, das nur dein Firmennetz erreicht, verbindest du über deinen Runner.

Das Token kann ein persönliches, ein Gruppen- oder ein Projekt-Zugriffstoken sein. Es braucht den Scope api, damit kanman klonen, die Run-Branches pushen, Merge Requests öffnen und Pipelines lesen kann. Warum nicht nur write_repository: Neben dem Pushen öffnet und aktualisiert kanman Merge Requests, liest ihre Pipelines und Freigaben, beantwortet Review-Threads und merged, wenn dein Team es erlaubt, und GitLab erlaubt das nur mit api. Das Coding-Werkzeug bekommt das Token nie: Er arbeitet auf einer lokalen Kopie, und kanman pusht. Nimm am besten ein Projekt- oder Gruppen-Zugriffstoken mit Ablaufdatum. Verbindung testen prüft die Verbindung und zeigt, was kanman damit tun darf; eine Verbindung mit abgelaufenem Token ist mit Braucht Aufmerksamkeit markiert.

Über den Runner verbinden

Für ein GitLab, das nur dein Firmennetz erreicht, wähle beim Verbinden unter Erreicht aus Dein Runner (in deinem Netz). Die kanman Cloud nimmt dann nie Kontakt zu deinem GitLab auf. Der eigene Self-hosted Runner deines Workspaces erledigt mit dem Token die ganze Arbeit: Klonen, Pushen, Merge Requests, Reviews, Merges und alles, was kanman aus GitLab liest, und Verbindung testen prüft das Token auf dem Runner. Ist kein Runner online, wartet der Test, bis einer online ist. In einem Workspace, der alles auf seinen Runnern ausführt, werden Verbindungen immer vom Runner erreicht.

1. Öffne Workspace-Einstellungen > Verbindungen, öffne GitLab und klicke auf GitLab verbinden.
2. Gib die Adresse deines GitLab und das Token als Token oder Schlüssel ein.
3. Wähle unter Erreicht aus Dein Runner (in deinem Netz) und speichere.

Welches Konto. Wir empfehlen ein Dienstkonto der GitLab-Gruppe, in der das Team arbeitet (ein Gruppen-Zugriffstoken oder ein persönliches Zugriffstoken eines Dienstkonto-Benutzers):

Lesen aus deinem GitLab während eines Runs. Das Coding-Werkzeug bekommt das Token nie. Muss es während eines Runs aus deinem GitLab lesen, zum Beispiel um private Module abzurufen, liest es über deinen Runner, der nur Lesen erlaubt. Ein eigenes Lese-Token brauchst du dafür nicht.

Repositories. Die kanman Cloud kann die Projekte eines GitLab, das über den Runner verbunden ist, nicht auflisten. Tipp in der Team-Einrichtung stattdessen den Pfad jedes Repositorys, zum Beispiel platform/payments/api.

Wurde dein Runner mit einem eigenen GITLAB_TOKEN gestartet, tritt die Verbindung an dessen Stelle; das Token des Runners wird nur genutzt, wenn keine Verbindung besteht. Die ganze Einrichtung für ein GitLab in deinem Netz beschreibt GitLab hinter VPN oder Firewall.

Repositories wählen

Ist dein Tracker Jira, wähle in der Team-Einrichtung im Schritt Projekt und Repositories GitLab als Code-Host. kanman listet die Projekte, die dein GitLab-Konto erreicht. Wähle sie aus der Liste oder tipp ihren Pfad, zum Beispiel platform/payments/api; Untergruppen werden unterstützt. Die Repositories des Teams werden als GitLab-Repositories gespeichert, und kanman klont und pusht sie auf deinem GitLab-Server.

Weitere Repositories fügst du später unter Team > Repositories hinzu. Neue Repositories nutzen den Code-Host des Teams.

Selbst betriebenes GitLab

kanman arbeitet mit selbst betriebenen GitLab-Instanzen genauso wie mit gitlab.com. Verbinde dich wie oben beschrieben mit einem Zugriffstoken und der Adresse deiner Instanz. Direkt verbunden muss deine Instanz über https aus dem Internet erreichbar sein. Ist sie nur in deinem Netz erreichbar, verbinde sie über den Runner; GitLab hinter VPN oder Firewall beschreibt die ganze Einrichtung.

Prüfungen und Merge arbeiten auf deiner Instanz genauso: kanman liest das Pipeline-Ergebnis des Merge Requests, der unabhängige Reviewer veröffentlicht sein Review daran, und kanman mergt, wenn beides bestanden ist. Links in kanman zeigen auf deine Instanz.

Geschützte Branches und Freigaben

Die geschützten Branches und Freigaberegeln für Merge Requests in GitLab gelten für kanman wie für alle anderen. Erlaube Pushes auf kanman/*-Branches und lass den Ziel-Branch geschützt.

Fehlerbehebung