Referencja
Przepis: Jira
Połącz wymagania Holarch ze zgłoszeniami Jira przez REST API i zamieniaj zgłoszenia Jira w przejrzane zmiany Holarch za pośrednictwem Claude; konfiguracja, skrypt synchronizacji, przykład krok po kroku i rozwiązywanie problemów.
Przegląd
Ten przepis wiąże prace inżynierskie w Jira z wymaganiami w Holarch. Ma dwie części:
- Z Holarch do Jira (REST API): skrypt tworzy jedno zgłoszenie Jira dla każdego zatwierdzonego wymagania. Każde zgłoszenie zawiera łącze zwrotne do wymagania w Holarch. Można go uruchomić ponownie w dowolnej chwili: pomija wymagania, które mają już zgłoszenie.
- Z Jira do Holarch (MCP, przez Claude): Claude odczytuje zgłoszenie Jira, np. wniosek klienta o zmianę, i proponuje odpowiadające mu zmiany wymagań w Holarch. Nic się nie zmienia, dopóki nie przejrzysz i nie zastosujesz propozycji w Holarch.
Holarch nie ma wbudowanego konektora Jira. Przepis korzysta z REST API i MCP, więc każdy krok można dostosować.
Wymagania wstępne
- Plan z API i MCP: Individual lub Team albo okres próbny Individual. W planie Free mają je też konta ze zweryfikowanym akademickim adresem e-mail lub w aktywnej organizacji zajęć (Plany i limity).
- Projekt Holarch, którego jesteś edytorem lub właścicielem. Propozycje wymagają roli edytora.
- Osobisty token dostępu: Ustawienia konta → Tokeny API → Nowy token. Dla skryptu z Holarch do Jira użyj Tylko do odczytu i ogranicz token do projektu (Tworzenie tokenu).
- Jira Cloud: projekt Jira, w którym możesz tworzyć zgłoszenia, oraz token API Atlassian (ustawienia konta Atlassian → Security → API tokens). Jira Data Center używa zamiast tego ścieżek
/rest/api/2/i osobistego tokenu dostępu; sprawdź jej dokumentację API. - Python 3.9 lub nowszy z pakietem
requests(python3 -m pip install requests) dla skryptu. - Dla części z Claude: Claude połączony z Holarch (Podłączanie Holarch do Claude). Claude sam odczytuje zgłoszenia Jira tylko wtedy, gdy ma też konektor Jira; w przeciwnym razie wklej tekst zgłoszenia do rozmowy.
Jak z niego korzystać
Kiedy i dlaczego
Wymagania znajdują się w Holarch; prace nad ich realizacją i testowaniem są często planowane w Jira. Powiązanie obu odpowiada na dwa pytania: “które prace w Jira realizują to wymaganie?” i “których wymagań dotyczy ten wniosek o zmianę?”. Uruchamiaj synchronizację po każdym przeglądzie wymagań, gdy nowe wymagania osiągną status Approved.
Konfiguracja synchronizacji
- W Holarch utwórz token Tylko do odczytu ograniczony do projektu. Skopiuj go.
- Znajdź id projektu:
GET /api/v1/projectswymienia Twoje projekty z ichid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- Ustaw zmienne środowiskowe odczytywane przez skrypt:
HOLARCH_TOKEN: token Holarch.HOLARCH_PROJECT: id projektu.JIRA_URL: Twoja witryna Jira, np.https://your-site.atlassian.net.JIRA_EMAILiJIRA_API_TOKEN: e-mail logowania Atlassian i token API.JIRA_PROJECT: klucz projektu Jira, np.EO.
- Zapisz poniższy skrypt jako
holarch_to_jira.py.
Tworzenie zgłoszeń Jira z zatwierdzonych wymagań
Skrypt odczytuje każde wymaganie przez REST API, pomija te, które mają już zgłoszenie Jira, i tworzy Task dla każdego pozostałego wymagania, którego Status to Approved.
# 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}")
- Uruchom
python3 holarch_to_jira.py.Pojawia się jeden wiersz na nowe zgłoszenie, np.
2.1 Pointing Accuracy -> EO-12.
Jak to działa:
GET /api/v1/projects/<project>/entities?class=Requirementwymienia wymagania, po 500 naraz.GET /api/v1/projects/<project>/entities/<id>podaje atrybuty każdego wymagania (tu Status) i jegourl, łącze otwierające je w Holarch.- Każde zgłoszenie otrzymuje etykiety Jira
holarchiholarch-<id>. Następne uruchomienie znajduje je wyszukiwaniem w Jira i pomija te wymagania. - Wymagania są tylko odczytywane. Skrypt niczego nie zmienia w Holarch.
Przechowywanie klucza Jira w Holarch (opcjonalnie)
Aby widzieć klucz Jira przy wymaganiu w Holarch, dodaj atrybut tekstowy i zapisz w nim klucz.
- W Holarch otwórz Ustawienia → Schemat, kliknij Requirement i dodaj atrybut o nazwie Jira Key typu Krótki tekst (Dodawanie atrybutu do klasy).
- Utwórz dla skryptu token Odczyt i zapis zamiast tokenu tylko do odczytu.
- Na końcu ostatniej pętli skryptu, po wierszu
print(…), dodaj:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
Zmiana jest zapisywana jak edycja w aplikacji: jest rejestrowana pod Twoim nazwiskiem i widzi ją każdy, kto ma projekt otwarty. Ustawienie tego atrybutu nie odsyła zatwierdzonego wymagania z powrotem do przeglądu. Gdy projekt używa kontroli konfiguracji, zatwierdzone wymagania odrzucają bezpośrednie zmiany (409 change-control); przechowuj klucz tylko w Jira albo wprowadź zmianę przez wniosek o zmianę.
Zamiana zgłoszenia Jira w propozycję Holarch za pomocą Claude
Użyj tego, gdy zgłoszenie Jira wymaga zmiany wymagania, np. wniosek klienta o zaostrzenie wartości.
- Otwórz Claude połączony z Holarch z dostępem Odczyt i proponowanie zmian.
- Zapytaj na przykład: “Przeczytaj zgłoszenie Jira EO-31. Znajdź wymagania Holarch w projekcie CubeSat, których dotyczy, i zaproponuj zmiany, o które prosi. Wymień EO-31 w podsumowaniu propozycji.”
Bez konektora Jira wklej zamiast tego do wiadomości podsumowanie i opis zgłoszenia.
- Claude odczytuje projekt za pomocą
list_projects,search_entitiesiget_entity. Dodaje każdą zmianę do propozycji za pomocąupdate_entity(lubcreate_entityirelatedla nowych wymagań), a następnie wysyła ją za pomocąpropose_changes.Claude odpowiada tytułem propozycji i łączem do jej przeglądu.
- W Holarch otwórz ✦ AI ▾ → Przejrzyj “<title>”… albo powiadomienie pod dzwonkiem.
- Sprawdź każdą zmianę. Odznacz to, czego nie chcesz, a następnie kliknij Zastosuj zaznaczone.
Zmiany zostają zastosowane, a jedno polecenie Cofnij wycofuje całość. Zmieniony tekst wymagania oznacza jego powiązania śledzenia do przeglądu, a zatwierdzone wymaganie wraca do In Review, jak przy każdej edycji.
Skrypty mogą utworzyć tę samą propozycję bez Claude: POST /api/v1/projects/<project>/proposal/changes raz na każdą zmianę, a następnie POST /api/v1/projects/<project>/proposal z title i 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
Przykład: demo CubeSat EO-1
- Utwórz projekt demonstracyjny poleceniem Zarządzaj projektami → Pliki projektów ▾ → Nowy projekt demonstracyjny.
- Utwórz token tylko do odczytu ograniczony do projektu demonstracyjnego i uruchom
holarch_to_jira.pyna testowym projekcie Jira.Każde zatwierdzone wymaganie otrzymuje zgłoszenie, np. 2.1 Pointing Accuracy z tekstem “The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.” i łączem do wymagania.
- Uruchom skrypt ponownie.
Nic nie wypisuje: każde zatwierdzone wymaganie ma już swoje zgłoszenie.
- W Jira utwórz zgłoszenie EO-31 z prośbą o 0,08 stopnia zamiast 0,1 stopnia. Poproś Claude o zaproponowanie zmiany, jak powyżej.
- W Holarch przejrzyj propozycję. Zmienia ona tekst 2.1 Pointing Accuracy, a jej lista Wpływ pokazuje TC-04 Pointing Accuracy Test, który ją weryfikuje.
Wskazówki
- Daj skryptowi synchronizacji własny token tylko do odczytu, ograniczony do projektu. Daj Claude osobne połączenie.
- Przechowuj tokeny w magazynie sekretów lub w środowisku, nigdy w skrypcie.
- Wyszukuj w Jira wymagania stojące za sprintem za pomocą etykiety
holarch. - Numery wymagań mogą się zmieniać; etykieta
holarch-<id>nie. Dopasowuj według etykiety, a nie według numeru w podsumowaniu.
Rozwiązywanie problemów
| Komunikat lub objaw | Przyczyna i rozwiązanie |
|---|---|
Holarch answered 401 token-invalid | Token jest błędny, unieważniony lub wygasł. Utwórz nowy w Ustawienia konta → Tokeny API. |
Holarch answered 403 plan-api | Plan konta nie obejmuje API i MCP. Rozpocznij okres próbny Individual lub wybierz plan; token znów zadziała. |
Holarch answered 403 org-policy | Organizacja projektu wyłączyła dostęp przez API. Zwróć się do administratora organizacji. |
Holarch answered 403 read-only-token | Zapis Jira Key wymaga tokenu Odczyt i zapis. |
Holarch answered 400 unknown-attribute | Projekt nie ma atrybutu Jira Key dla Requirement. Dodaj go w Ustawienia → Schemat lub pomiń krok opcjonalny. |
Holarch answered 409 change-control | Wymaganie podlega kontroli konfiguracji. Zmień je przez wniosek o zmianę lub przechowuj klucz tylko w Jira. |
Holarch answered 429 rate-limited | Ponad 600 żądań lub 120 zmian na minutę. Odczekaj liczbę sekund podaną w Retry-After, a następnie uruchom ponownie; gotowe zgłoszenia są pomijane. |
| Jira odpowiada 400 | Jira odrzuciła pola zgłoszenia, na przykład typ zgłoszenia, którego projekt nie ma. Zamiast Task użyj jednego z typów zgłoszeń projektu. |
| Jira odpowiada 401 lub 403 | Sprawdź JIRA_EMAIL, JIRA_API_TOKEN i swoje uprawnienie do tworzenia zgłoszeń w projekcie Jira. |
| Claude nie pokazuje narzędzi zapisu Holarch | Połączenie jest tylko do odczytu. Połącz ponownie z dostępem Odczyt i proponowanie zmian, a następnie rozpocznij nową rozmowę. |