Jira
Agenten starten, wenn in Jira Cloud Issues angelegt oder geändert oder Kommentare geschrieben werden, und ihre Ergebnisse als Kommentar oder neues Issue posten.
Auf dieser Seite
| Modi | Inbound, Outbound |
| YAML-Typ | jira |
| Zugangsdaten | Ein Kontozugang (Connection) vom Typ jira mit Site-URL, Konto-E-Mail und API-Token eines Atlassian-Kontos |
| Sites | Jira Cloud. Jira Data Center und Server werden nicht unterstützt. |
| Bridge | Nicht unterstützt |
| Custom Domain | Nicht unterstützt |
| Verknüpfte Agenten | Einer oder mehrere. Jedes passende Event startet alle verknüpften Agenten. |
| Während der Pause | Events erhalten 200 und starten keine Runs; der Webhook bleibt in Jira bestehen. Outbound sendet nichts. |
Einrichtung
Erstelle ein API-Token ohne Scopes für das Atlassian-Konto, als das deine Agenten handeln. Für Inbound-Verbindungen braucht das Konto die globale Berechtigung Jira verwalten (Administer Jira).
Öffne den Agenten. Klicke im Connector Flow für Issue-Events auf Add inbound connector oder für Kommentare und Issues auf Add outbound connector. Klicke dann auf Create New Connector und wähle Jira.
Wähle den Modus. Unter Connection wählst du einen gespeicherten Kontozugang oder legst einen mit Site URL, Account email und API token an.
Gib bei Inbound die Events ein, eines pro Zeile, und den JQL filter. Gib bei Outbound den Project key und den Issue type ein.
Klicke auf Create. Eine Inbound-Verbindung registriert ihren Webhook in Jira. Bei Outbound legst du danach fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.
Im Code
Deklariere die Verbindung in connectors/*.yaml. connection nennt den Kontozugang mit der Site und dem API-Token des Kontos.
type: jira
mode: inbound
connection: acme-jira # Kontozugang mit Site, Konto-E-Mail und API-Token
config:
events:
- jira:issue_created
- comment_created
jql: project = SUP
agents:
- support-triagetype: jira
mode: outbound
connection: acme-jira
config:
project_key: SUP
issue_type: Task
agents:
- name: support-triage
outbound: { usage: automatic }Konfiguration
Die Felder einer Jira-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.
| Feld | Typ | Status | Beschreibung |
|---|---|---|---|
| type | string | Required | jira. |
| mode | string | Required | inbound oder outbound. Dashboard: Mode. |
| connection | string | Required | Name oder ID eines Kontozugangs vom Typ jira. Siehe Atlassian-Konto. Dashboard: Connection. |
| config | object | Required | Einstellungen der Jira-Verbindung. |
| events | string[] | Required | Inbound. Die Events, die Runs starten: jira:issue_created, jira:issue_updated und comment_created. Dashboard: Events, eines pro Zeile, vorausgefüllt mit jira:issue_created. |
| jql | string | Required | Inbound. Nur Events von Issues, die zu dieser JQL passen, starten Runs, etwa project = SUP oder project = SUP AND issuetype = Bug. Dashboard: JQL filter. |
| project_key | string | Required | Outbound. Das Projekt für neue Issues, etwa SUP. Dashboard: Project key. |
| issue_type | string | Required | Outbound. Der Issue-Typ neuer Issues, so benannt wie im Projekt, etwa Task oder Bug. Dashboard: Issue type.Default: Task |
Site-URL, Konto-E-Mail und API-Token gehören zum Kontozugang, nicht zur Verbindung. Beim Anlegen oder Speichern einer Verbindung prüft connic sie bei Jira, bei Outbound auch Projekt und Issue-Typ.
Agent-Input
Modi: Inbound
Eine Inbound-Verbindung startet für jeden verknüpften Agenten einen Run, sobald eines ihrer Events bei einem Issue eintritt, das zu ihrem JQL-Filter passt. Events, die das Konto des Kontozugangs selbst auslöst, etwa die eigenen Kommentare und Issues des Agenten, werden ignoriert, damit sich Agenten nicht selbst starten. Der Run erhält:
{
"event": "comment_created",
"issue_key": "SUP-42",
"project": "SUP",
"conversation_id": "jira:acme.atlassian.net/10042",
"summary": "Checkout schlägt bei EUR-Bestellungen fehl",
"text": "Tritt nach dem letzten Deployment weiterhin auf.",
"url": "https://acme.atlassian.net/browse/SUP-42?focusedCommentId=10310",
"author": "Jane Doe",
"author_account_id": "5b10ac8d82e05b22cc7d4ef5",
"raw": { ... }
}eventist der Event-Name von Jira, etwacomment_created.issue_key,projectundsummarybeschreiben das Issue, auch bei Kommentaren.conversation_idbleibt für alle Events eines Issues gleich, auch nachdem es in ein anderes Projekt verschoben wurde. Soll der Agent die früheren Events als Verlauf bekommen, setzsession.key: input.conversation_idin seiner YAML; die Verbindung schaltet Sessions nicht von selbst ein.textist beicomment_createdder Kommentar, sonst die Beschreibung des Issues, so wie Jira sie sendet.urlverlinkt auf das Issue oder den Kommentar.authorundauthor_account_idnennen die Person, die das Issue angelegt oder geändert oder den Kommentar geschrieben hat.rawist die vollständige Event-Payload von Jira, beijira:issue_updatedmit dem Änderungsprotokoll.
Stellt Jira ein Event erneut zu, startet es keinen weiteren Run. Inbound antwortet nicht von selbst: Damit der Agent das Issue kommentiert, verknüpf ihn mit einer Outbound-Jira-Verbindung, die denselben Kontozugang nutzt; siehe Outbound-Zustellung.
Atlassian-Konto
Verbindungen lesen und schreiben in Jira als das Konto des Kontozugangs. Nimm dafür ein eigenes Konto nur für deine Agenten: Events, die dieses Konto auslöst, starten nie Runs. Nutzt der Kontozugang dein eigenes Konto, erreichen deine eigenen Kommentare die Agenten also nicht.
| Feld im Kontozugang | Beschreibung |
|---|---|
| Site URL | Deine Jira-Cloud-Site, etwa https://acme.atlassian.net. |
| Account email | Die E-Mail-Adresse des Atlassian-Kontos, zu dem das API-Token gehört. Verbindungen lesen und schreiben in Jira als dieses Konto. |
| API token | Ein API-Token dieses Kontos, ohne Scopes erstellt. |
Melde dich mit diesem Konto an, öffne in den Einstellungen des Atlassian-Kontos die API-Tokens und wähle API-Token erstellen, nicht die Variante mit Scopes. Tokens mit Scopes lehnt Jira über die Site-URL und beim Registrieren von Webhooks ab. Atlassian lässt API-Tokens höchstens 365 Tage gelten; siehe API-Tokens für dein Atlassian-Konto verwalten. Erstelle vor dem Ablauf ein neues Token und trag es unter Projekt-Settings → Connections im Kontozugang ein. Alle Verbindungen mit diesem Kontozugang übernehmen es.
Inbound-Verbindungen brauchen die globale Berechtigung Jira verwalten (Administer Jira), weil connic beim Speichern einen Webhook auf der Site registriert. Jede Inbound-Verbindung hat ihren eigenen Webhook, benannt mit connic connector und der ID der Verbindung, in Jira unter System → WebHooks. Änderst du die Events oder den JQL-Filter, ändert sich der Webhook mit; löschst du die Verbindung, verschwindet er. connic prüft die Signatur jedes Events mit einem Secret, das es für den Webhook erzeugt hat. Outbound-Verbindungen brauchen im Projekt die Berechtigungen, es zu durchsuchen, Kommentare hinzuzufügen und Issues zu erstellen.
Outbound-Zustellung
Modi: Outbound
Eine Outbound-Jira-Verbindung postet einmal pro Nutzung: wenn der Run eines verknüpften Agenten endet, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. Wohin, entscheidet die erste Regel, die zutrifft:
- Setzt die Ausgabe oder Payload
issue_key, kommentiert sie dieses Issue. - Kam der Run über eine Inbound-Jira-Verbindung mit demselben Kontozugang, kommentiert sie das Issue, mit dem der Run begann.
- Sonst legt sie im Projekt der Verbindung ein Issue ihres Issue-Typs an. Die Zusammenfassung ist
summaryaus der Ausgabe oder Payload, sonst die erste Zeile des Texts.
Der Text wird als Klartext zum Kommentar oder zur Beschreibung des Issues: Eine Leerzeile beginnt einen neuen Absatz, ein Zeilenumbruch bleibt ein Zeilenumbruch.
Automatische Ausgabe
Eine automatische Verknüpfung postet die finale Ausgabe des Runs. Klartext wird zum Text. Ein JSON-Objekt nimmt den Text aus body, text, message, response oder output, in dieser Reihenfolge, und kann summary und issue_key setzen.
{
"summary": "EUR-Beträge werden im Checkout doppelt gerundet",
"body": "Seit 2.14.0 weichen Bestellungen in EUR um einen Cent ab.\n\nDer Betrag wird im Warenkorb und noch einmal bei der Zahlung gerundet."
}Payload für Agent-Tool und Middleware
Modell oder Middleware übergeben body, das Pflicht ist und nicht leer sein darf, und optional summary und issue_key. Andere Felder werden abgelehnt.
{
"body": "Reproduziert: Der Betrag wird im Warenkorb und noch einmal bei der Zahlung gerundet.",
"issue_key": "SUP-42"
}Zustellung und Wiederholungen
Drosselt Jira die Anfrage für einen Kommentar oder ein Issue, wartet connic und sendet sie erneut. Die Runs der Verbindung zeigen jede Zustellung mit dem Link zum Issue oder mit dem Fehler.
Limits und Fehler
| Limit | Wert |
|---|---|
| API-Token | Läuft nach 1 bis 365 Tagen ab, festgelegt beim Erstellen, vorgegeben von Atlassian. Ersetze es vorher im Kontozugang. |
| Antwort an Jira | connic antwortet sofort und startet die Agenten danach. |
| Fehlgeschlagene Zustellungen | Jira wiederholt ein Event bis zu fünfmal im Abstand von 5 bis 15 Minuten, wenn connic mit 429 oder 5xx antwortet oder nicht erreichbar ist. |
| Schreibzugriffe pro Issue | 20 pro 2 Sekunden und 100 pro 30 Sekunden, von Jira vorgegeben. Drosselt Jira die Anfragen, wartet connic und stellt erneut zu. |
| Zusammenfassung | 255 Zeichen. Eine längere Zusammenfassung wird gekürzt. |
Anfragen mit fehlender oder falscher Signatur erhalten 401. Eine Verbindung lässt sich nicht anlegen, wenn Jira Konto-E-Mail und API-Token ablehnt, etwa ein Token mit Scopes oder ein abgelaufenes, wenn dem Konto einer Inbound-Verbindung die globale Berechtigung Jira verwalten fehlt oder wenn Projekt oder Issue-Typ einer Outbound-Verbindung nicht existieren. Eine Zustellung schlägt fehl, wenn Jira sie ablehnt, etwa weil das Issue nicht existiert oder das Konto es nicht kommentieren darf.
Ein abgelaufenes Token hält keine Events auf, aber Zustellungen und das Speichern von Verbindungen schlagen fehl, bis du es ersetzt. Ist Jira beim Löschen einer Verbindung nicht erreichbar oder lehnt das Token ab, wird die Verbindung trotzdem gelöscht; entferne ihren Webhook dann in Jira unter System → WebHooks.