Referenz
Rezept: Jira
Verbinden Sie Holarch-Anforderungen über die REST-API mit Jira-Issues und machen Sie über Claude aus Jira-Issues geprüfte Holarch-Änderungen; Einrichtung, ein Synchronisationsskript, ein durchgearbeitetes Beispiel und Fehlerbehebung.
Überblick
Dieses Rezept hält die Entwicklungsarbeit in Jira mit den Anforderungen in Holarch verbunden. Es hat zwei Teile:
- Holarch nach Jira (REST-API): Ein Skript erstellt für jede genehmigte Anforderung ein Jira-Issue. Jedes Issue verlinkt zurück zur Anforderung in Holarch. Führen Sie es jederzeit erneut aus: Es überspringt Anforderungen, die bereits ein Issue haben.
- Jira nach Holarch (MCP, über Claude): Claude liest ein Jira-Issue, etwa einen Änderungsantrag eines Kunden, und schlägt die passenden Anforderungsänderungen in Holarch vor. Nichts ändert sich, bis Sie den Vorschlag in Holarch prüfen und anwenden.
Holarch hat keinen eingebauten Jira-Konnektor. Das Rezept verwendet die REST-API und MCP, sodass Sie jeden Schritt anpassen können.
Voraussetzungen
- Ein Tarif mit API und MCP: Individual oder Team oder die Testphase Individual. Im Tarif Free hat auch ein Konto mit einer bestätigten akademischen E-Mail-Adresse oder in einer aktiven Kursorganisation sie (Tarife und Grenzen).
- Ein Holarch-Projekt, in dem Sie Bearbeiter oder Eigentümer sind. Vorschläge erfordern die Rolle Bearbeiter.
- Ein persönliches Zugriffstoken: Kontoeinstellungen → API-Token → Neues Token. Verwenden Sie Nur lesen für das Skript von Holarch nach Jira und beschränken Sie es auf das Projekt (Ein Token erstellen).
- Jira Cloud: ein Jira-Projekt, in dem Sie Issues erstellen können, und ein Atlassian-API-Token (Atlassian-Kontoeinstellungen → Security → API tokens). Jira Data Center verwendet stattdessen die Pfade
/rest/api/2/und ein persönliches Zugriffstoken; prüfen Sie dessen API-Referenz. - Python 3.9 oder neuer mit dem Paket
requests(python3 -m pip install requests) für das Skript. - Für den Teil mit Claude: Claude mit Holarch verbunden (Holarch mit Claude verbinden). Claude liest Jira-Issues nur selbst, wenn es auch einen Jira-Konnektor hat; andernfalls fügen Sie den Text des Issues in das Gespräch ein.
So setzen Sie es ein
Wann und warum
Anforderungen liegen in Holarch; die Arbeit, sie umzusetzen und zu testen, wird oft in Jira geplant. Die Verknüpfung beider beantwortet zwei Fragen: „Welche Jira-Arbeit setzt diese Anforderung um?“ und „Welche Anforderungen berührt dieser Änderungsantrag?“. Führen Sie die Synchronisierung nach jedem Anforderungsreview aus, wenn neue Anforderungen Approved erreichen.
Die Synchronisierung einrichten
- Erstellen Sie in Holarch ein Token mit Nur lesen, beschränkt auf das Projekt. Kopieren Sie es.
- Ermitteln Sie die Projekt-ID:
GET /api/v1/projectslistet Ihre Projekte mit ihrerid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- Setzen Sie die Umgebungsvariablen, die das Skript liest:
HOLARCH_TOKEN: das Holarch-Token.HOLARCH_PROJECT: die Projekt-ID.JIRA_URL: Ihre Jira-Site, etwahttps://your-site.atlassian.net.JIRA_EMAILundJIRA_API_TOKEN: Ihre Atlassian-Anmelde-E-Mail und Ihr API-Token.JIRA_PROJECT: der Schlüssel des Jira-Projekts, etwaEO.
- Speichern Sie das folgende Skript als
holarch_to_jira.py.
Jira-Issues aus genehmigten Anforderungen erstellen
Das Skript liest jede Anforderung über die REST-API, überspringt die, die bereits ein Jira-Issue haben, und erstellt für jede verbleibende Anforderung, deren Status Approved ist, einen Task.
# holarch_to_jira.py: one Jira issue per approved Holarch requirement. Safe to run again.
import os
import requests
HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
JIRA = os.environ["JIRA_URL"].rstrip("/")
JIRA_AUTH = (os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"])
JIRA_PROJECT = os.environ["JIRA_PROJECT"]
def holarch(method, path, **kw):
r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
if r.status_code >= 400:
d = r.json()
raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
return r.json()
def requirements():
offset = 0
while True:
page = holarch("GET", f"/projects/{PROJECT}/entities",
params={"class": "Requirement", "limit": 500, "offset": offset})
yield from page["entities"]
offset += page["limit"]
if offset >= page["total"]:
return
def linked_in_jira():
"""The Jira labels holarch-<requirement id> already on issues of the Jira project."""
seen, token = set(), None
while True:
params = {"jql": f'project = "{JIRA_PROJECT}" AND labels = holarch', "fields": "labels", "maxResults": 100}
if token:
params["nextPageToken"] = token
r = requests.get(JIRA + "/rest/api/3/search/jql", params=params, auth=JIRA_AUTH, timeout=60)
r.raise_for_status()
d = r.json()
for issue in d.get("issues", []):
seen.update(x for x in issue["fields"]["labels"] if x.startswith("holarch-"))
token = d.get("nextPageToken")
if not token:
return seen
seen = linked_in_jira()
for req in requirements():
if "holarch-" + req["id"] in seen:
continue
e = holarch("GET", f"/projects/{PROJECT}/entities/{req['id']}")["entity"]
if e["attributes"].get("Status") != "Approved":
continue
text = (e["description"] + "\n\n" if e["description"] else "") + "Requirement in Holarch: " + e["url"]
fields = {
"project": {"key": JIRA_PROJECT},
"issuetype": {"name": "Task"},
"summary": f"{e['number']} {e['name']}".strip(),
"labels": ["holarch", "holarch-" + e["id"]],
"description": {"type": "doc", "version": 1, "content": [
{"type": "paragraph", "content": [{"type": "text", "text": text}]}]},
}
issue = requests.post(JIRA + "/rest/api/3/issue", json={"fields": fields}, auth=JIRA_AUTH, timeout=60)
issue.raise_for_status()
key = issue.json()["key"]
print(f"{e['number']} {e['name']} -> {key}")
- Führen Sie
python3 holarch_to_jira.pyaus.Sie sehen eine Zeile pro neuem Issue, etwa
2.1 Pointing Accuracy -> EO-12.
So funktioniert es:
GET /api/v1/projects/<project>/entities?class=Requirementlistet die Anforderungen, jeweils 500.GET /api/v1/projects/<project>/entities/<id>liefert die Attribute jeder Anforderung (hier Status) und ihreurl, den Link, der sie in Holarch öffnet.- Jedes Issue erhält die Jira-Labels
holarchundholarch-<id>. Der nächste Lauf findet sie mit einer Jira-Suche und überspringt diese Anforderungen. - Anforderungen werden nur gelesen. Das Skript ändert nichts in Holarch.
Den Jira-Schlüssel in Holarch aufbewahren (optional)
Um den Jira-Schlüssel an der Anforderung in Holarch zu sehen, fügen Sie ein Textattribut hinzu und schreiben Sie den Schlüssel hinein.
- Öffnen Sie in Holarch Einstellungen → Schema, klicken Sie auf Requirement und fügen Sie ein Attribut mit dem Namen Jira Key und dem Typ Kurzer Text hinzu (Einer Klasse ein Attribut hinzufügen).
- Erstellen Sie für das Skript statt des Tokens mit Nur-Lesen-Zugriff ein Token mit Lesen und schreiben.
- Fügen Sie am Ende der letzten Schleife des Skripts, nach der Zeile
print(…), Folgendes hinzu:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
Die Änderung wird wie eine Bearbeitung in der App geschrieben: Sie wird unter Ihrem Namen erfasst, und jeder, der das Projekt geöffnet hat, sieht sie. Das Setzen dieses Attributs schickt eine genehmigte Anforderung nicht zurück ins Review. Wenn das Projekt Konfigurationsmanagement verwendet, lehnen genehmigte Anforderungen direkte Änderungen ab (409 change-control); bewahren Sie den Schlüssel nur in Jira auf oder nehmen Sie die Änderung über einen Änderungsantrag vor.
Ein Jira-Issue mit Claude in einen Holarch-Vorschlag umwandeln
Verwenden Sie dies, wenn ein Jira-Issue eine Anforderungsänderung verlangt, etwa die Bitte eines Kunden, einen Wert zu verschärfen.
- Öffnen Sie Claude, mit Holarch verbunden mit dem Zugriff Lesen und Änderungen vorschlagen.
- Fragen Sie zum Beispiel: „Lies das Jira-Issue EO-31. Finde die Holarch-Anforderungen im CubeSat-Projekt, die es betrifft, und schlage die Änderungen vor, die es verlangt. Erwähne EO-31 in der Zusammenfassung des Vorschlags.“
Ohne Jira-Konnektor fügen Sie stattdessen die Zusammenfassung und die Beschreibung des Issues in die Nachricht ein.
- Claude liest das Projekt mit
list_projects,search_entitiesundget_entity. Es fügt jede Änderung mitupdate_entity(odercreate_entityundrelatefür neue Anforderungen) einem Vorschlag hinzu und sendet ihn dann mitpropose_changes.Claude antwortet mit dem Titel des Vorschlags und einem Link, um ihn zu prüfen.
- Öffnen Sie in Holarch ✦ KI ▾ → „<title>“ prüfen… oder die Benachrichtigung unter der Glocke.
- Prüfen Sie jede Änderung. Entfernen Sie den Haken bei allem, was Sie nicht wollen, und klicken Sie dann auf Auswahl anwenden.
Die Änderungen werden angewendet, und ein einziges Rückgängigmachen nimmt alles zurück. Geänderter Anforderungstext markiert ihre Trace-Links zur Prüfung, und eine genehmigte Anforderung geht zurück auf In Review, wie bei jeder Bearbeitung.
Skripte können denselben Vorschlag ohne Claude machen: POST /api/v1/projects/<project>/proposal/changes einmal pro Änderung, dann POST /api/v1/projects/<project>/proposal mit title und summary.
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
-d '{"op": "update", "entity": "<requirement id>", "description": "The ADCS shall point the payload boresight within 0.08 degrees of the commanded target."}' \
https://app.holarch.app/api/v1/projects/<project>/proposal/changes
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
-d '{"title": "EO-31: tighter pointing", "summary": "Customer request EO-31 tightens pointing accuracy to 0.08 degrees."}' \
https://app.holarch.app/api/v1/projects/<project>/proposal
Durchgehendes Beispiel: die CubeSat-EO-1-Demo
- Erstellen Sie die Demo mit Projekte verwalten → Projektdateien ▾ → Neues Demoprojekt.
- Erstellen Sie ein Token mit Nur-Lesen-Zugriff, beschränkt auf das Demoprojekt, und führen Sie
holarch_to_jira.pygegen ein Jira-Testprojekt aus.Jede genehmigte Anforderung erhält ein Issue, etwa 2.1 Pointing Accuracy mit dem Text „The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.“ und dem Link zur Anforderung.
- Führen Sie das Skript erneut aus.
Es gibt nichts aus: Jede genehmigte Anforderung hat bereits ihr Issue.
- Erstellen Sie in Jira ein Issue EO-31, das 0,08 Grad statt 0,1 Grad verlangt. Bitten Sie Claude wie oben, die Änderung vorzuschlagen.
- Prüfen Sie den Vorschlag in Holarch. Er ändert den Text von 2.1 Pointing Accuracy, und seine Liste Auswirkung zeigt TC-04 Pointing Accuracy Test, der sie verifiziert.
Tipps
- Geben Sie dem Sync-Skript ein eigenes Token mit Nur-Lesen-Zugriff, beschränkt auf das Projekt. Geben Sie Claude eine eigene Verbindung.
- Bewahren Sie Token in Ihrem Geheimnisspeicher oder Ihrer Umgebung auf, nie im Skript.
- Suchen Sie in Jira mit dem Label
holarchnach den Anforderungen hinter einem Sprint. - Anforderungsnummern können sich ändern; das Label
holarch-<id>nicht. Gleichen Sie über das Label ab, nicht über die Nummer in der Zusammenfassung.
Fehlerbehebung
| Meldung oder Symptom | Ursache und Behebung |
|---|---|
Holarch answered 401 token-invalid | Das Token ist falsch, widerrufen oder abgelaufen. Erstellen Sie ein neues unter Kontoeinstellungen → API-Token. |
Holarch answered 403 plan-api | Der Tarif des Kontos enthält API und MCP nicht. Beginnen Sie die Testphase Individual oder wählen Sie einen Tarif; das Token funktioniert dann wieder. |
Holarch answered 403 org-policy | Die Organisation des Projekts hat den API-Zugriff ausgeschaltet. Fragen Sie einen Organisationsadmin. |
Holarch answered 403 read-only-token | Das Schreiben des Jira Key erfordert ein Token mit Lesen und schreiben. |
Holarch answered 400 unknown-attribute | Das Projekt hat für Requirement kein Attribut Jira Key. Fügen Sie es in Einstellungen → Schema hinzu oder lassen Sie den optionalen Schritt weg. |
Holarch answered 409 change-control | Die Anforderung unterliegt dem Konfigurationsmanagement. Ändern Sie sie über einen Änderungsantrag oder bewahren Sie den Schlüssel nur in Jira auf. |
Holarch answered 429 rate-limited | Mehr als 600 Anfragen oder 120 Änderungen pro Minute. Warten Sie die Sekunden in Retry-After und führen Sie es dann erneut aus; fertige Issues werden übersprungen. |
| Jira antwortet mit 400 | Jira hat die Issue-Felder abgelehnt, zum Beispiel einen Issue-Typ, den das Projekt nicht hat. Verwenden Sie statt Task einen der Issue-Typen des Projekts. |
| Jira antwortet mit 401 oder 403 | Prüfen Sie JIRA_EMAIL, JIRA_API_TOKEN und Ihre Berechtigung, im Jira-Projekt Issues zu erstellen. |
| Claude zeigt die Holarch-Schreibwerkzeuge nicht an | Die Verbindung hat nur Lesezugriff. Verbinden Sie erneut mit Lesen und Änderungen vorschlagen und beginnen Sie dann ein neues Gespräch. |