Jira Cloud-Verbindung#
Eine Jira-Cloud-Verbindung speichert Zugangsdaten und Gültigkeitsbereich für ein Jira-Projekt. OakCore nutzt sie, um Issues aus diesem Projekt mit Spezifikationsknoten zu verknüpfen — siehe Jira Issues.
Eine Connection pro Jira-Projekt#
Wie bei GitHub gilt: eine Connection = ein Gültigkeitsbereich. Mehrere Jira-Projekte am selben OakCore-Projekt → mehrere Connections. Derselbe API-Token kann in mehreren Connections wiederverwendet werden, solange er auf alle Zielprojekte Zugriff hat.
Voraussetzungen#
- Projekt in OakCore öffnen → Einstellungen → Integrationen.
- Pro Ziel-Jira-Projekt eine Connection anlegen.
- In Jira benötigen Sie (nur für Issue-Bindings):
- Ein dediziertes URL-Custom-Field auf dem Issue-Bildschirm für OakCore-Backlinks (Anzeigename des Felds, z. B.
OakCore link). Bereits belegte Feldwerte lässt OakCore unverändert und verwendet dann einen verwalteten Kommentar. - Berechtigung zum Lesen und Bearbeiten von Issues im Zielprojekt (Backlinks).
- Admin-Zugriff auf das Jira-Projekt für Webhooks (empfohlen).
Connection hinzufügen#
Unter Einstellungen → Integrationen auf Hinzufügen → Jira Cloud project klicken.
Label#
Kurzer Name nur in OakCore, um Connections zu unterscheiden.
| Gut | Vermeiden |
|---|---|
Platform backlog |
PROJ (das ist der Projekt-Key) |
Kundenportal Bugs |
jira |
Site-URL#
Ihre Jira-Cloud-Basis-URL — nur die Origin, ohne Pfade.
Für https://acme.atlassian.net/jira/software/projects/PROJ/boards/1: https://acme.atlassian.net
Muss https:// verwenden.
Projekt-Key#
Das Kurzpräfix auf Issue-Keys — z. B. PROJ in PROJ-42.
Nur Issues aus diesem Projekt können über diese Connection gebunden werden.
Account-E-Mail#
Die Atlassian-Konto-E-Mail für den API-Token. Jira Cloud REST API nutzt Basic-Authentifizierung mit {email}:{api_token}.
Backlink-Feld#
Name oder ID eines dedizierten URL-Custom-Fields, in das OakCore den Landing-Link schreiben kann. Systemfelder und andere Custom-Field-Typen werden nicht unterstützt.
Tragen Sie den Anzeigenamen Ihres URL-Custom-Fields ein (z. B. OakCore link). OakCore löst ihn beim Speichern oder bei Test in die technische ID auf (customfield_…).
Das Feld muss auf dem Issue-Bearbeiten- / Anzeige-Bildschirm des Zielprojekts liegen.
API-Token#
Atlassian-API-Token, verschlüsselt gespeichert; nach dem Speichern nicht erneut anzeigbar.
- Atlassian-Kontosicherheit → API-Tokens.
- API-Token erstellen, einmal kopieren, in OakCore einfügen.
Das Konto braucht Lese- und Bearbeitungsrechte für Issues im Zielprojekt sowie Berechtigung zum Kommentieren (Fallback-Backlink, falls das Custom Field nicht beschreibbar ist).
Webhook-Secret (optional im Formular, für Webhooks erforderlich)#
Gemeinsames Passwort, das Jira Automation im Request-Header X-OakCore-Webhook-Secret sendet. OakCore prüft eingehende Jira-Updates gegen diesen Wert.
- Leer lassen beim Testen — Sync per Polling funktioniert weiter, Live-Updates verzögert.
- Secret setzen für Produktion (empfohlen).
openssl rand -hex 32
Denselben Wert in OakCore und im Request-Header X-OakCore-Webhook-Secret der Jira-Automation verwenden.
Connection testen#
Nach dem Speichern Test auf der Connection-Karte. OakCore prüft Token-Zugriff auf das konfigurierte Jira-Projekt.
Jira-Webhook einrichten (empfohlen)#
Webhooks liefern Updates innerhalb von Sekunden. Ohne Webhook aktualisiert OakCore per Zeitplan — Verzögerung möglich.
In Jira eine Automation-Regel erstellen, die bei aktualisierten oder gelöschten Issues eine Web-Anfrage sendet.
| Feld | Wert |
|---|---|
| URL | Aus der Connection-Karte kopieren |
| Header | X-OakCore-Webhook-Secret: {webhook_secret} |
| Auslöser | Issue updated, Issue deleted |
Die URL muss Ihren OakCore-API-Host verwenden (/api/v1/...), öffentlich erreichbar für Atlassian.
Mehrere Projekte#
Jedes Jira-Projekt braucht eine eigene Connection. Beim Binden die passende Connection wählen.
Fehlerbehebung#
| Symptom | Prüfen |
|---|---|
| Test schlägt fehl | Site-URL, Projekt-Key, E-Mail; Token abgelaufen; fehlende Projektberechtigung |
| Bind abgelehnt | Issue-Key gehört zu anderem Projekt |
| Kein Backlink | Anzeigename des Backlink-Felds; Feld auf Issue-Screen; Token darf Issues bearbeiten |
| Jira-Änderungen fehlen | Automation sendet den korrekten X-OakCore-Webhook-Secret; Auslöser gewählt; API-URL erreichbar |