הפניה
מתכון: Jira
חיבור דרישות Holarch לבעיות Jira עם ה-REST API, והפיכת בעיות Jira לשינויים סקורים ב-Holarch דרך Claude; הגדרה, סקריפט סנכרון, דוגמה מעובדת ופתרון בעיות.
בדף זה
סקירה כללית
המתכון הזה שומר על הקשר בין עבודת ההנדסה ב-Jira לבין הדרישות ב-Holarch. יש לו שני חלקים:
- מ-Holarch ל-Jira (REST API): סקריפט יוצר issue אחד ב-Jira לכל דרישה מאושרת. כל issue מקשר בחזרה לדרישה ב-Holarch. אפשר להריץ אותו שוב בכל עת: הוא מדלג על דרישות שכבר יש להן issue.
- מ-Jira ל-Holarch (MCP, דרך Claude): Claude קורא issue של Jira, כגון בקשת שינוי של לקוח, ומציע את שינויי הדרישות המתאימים ב-Holarch. שום דבר אינו משתנה עד שסוקרים ומחילים את ההצעה ב-Holarch.
ל-Holarch אין מחבר Jira מובנה. המתכון משתמש בREST API וב-MCP, כך שאפשר להתאים כל שלב.
דרישות מקדימות
- תוכנית עם ה-API ו-MCP: Individual או Team, או תקופת הניסיון של Individual. בתוכנית Free, גם לחשבון עם כתובת דוא״ל אקדמית מאומתת או בארגון כיתה פעיל יש אותם (תוכניות ומגבלות).
- פרויקט Holarch שאת/ה עורך/ת או בעלים שלו. הצעות דורשות את תפקיד העורך.
- אסימון גישה אישי: הגדרות החשבון ← אסימוני API ← אסימון חדש. לסקריפט מ-Holarch ל-Jira משתמשים בקריאה בלבד ומגבילים אותו לפרויקט (יצירת אסימון).
- Jira Cloud: פרויקט Jira שבו אפשר ליצור issues, ואסימון API של Atlassian (הגדרות חשבון Atlassian ← Security ← API tokens). Jira Data Center משתמש במקום זאת בנתיבים
/rest/api/2/ובאסימון גישה אישי; יש לבדוק את מדריך ה-API שלו. - Python 3.9 ואילך עם החבילה
requests(python3 -m pip install requests) עבור הסקריפט. - לחלק של Claude: Claude מחובר ל-Holarch (חיבור Holarch ל-Claude). Claude קורא issues של Jira בעצמו רק כשיש לו גם מחבר Jira; אחרת מדביקים את טקסט ה-issue בשיחה.
איך להשתמש בה
מתי ולמה
הדרישות נמצאות ב-Holarch; העבודה לבנות ולבדוק אותן מתוכננת לרוב ב-Jira. קישור בין השניים עונה על שתי שאלות: "איזו עבודה ב-Jira מממשת את הדרישה הזו?" ו-"באילו דרישות בקשת השינוי הזו נוגעת?". מריצים את הסנכרון אחרי כל סקירת דרישות, כשדרישות חדשות מגיעות ל-Approved.
הגדרת הסנכרון
- ב-Holarch, יש ליצור אסימון קריאה בלבד שמוגבל לפרויקט. מעתיקים אותו.
- יש למצוא את מזהה הפרויקט:
GET /api/v1/projectsמפרט את הפרויקטים שלך עם ה-idשלהם.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- יש להגדיר את משתני הסביבה שהסקריפט קורא:
HOLARCH_TOKEN: האסימון של Holarch.HOLARCH_PROJECT: מזהה הפרויקט.JIRA_URL: אתר ה-Jira שלך, כגוןhttps://your-site.atlassian.net.JIRA_EMAILו-JIRA_API_TOKEN: כתובת הדוא״ל שאיתה נכנסים ל-Atlassian ואסימון ה-API.JIRA_PROJECT: מפתח פרויקט ה-Jira, כגוןEO.
- יש לשמור את הסקריפט שלמטה כ-
holarch_to_jira.py.
יצירת issues ב-Jira מדרישות מאושרות
הסקריפט קורא כל דרישה דרך ה-REST API, מדלג על אלה שכבר יש להן issue ב-Jira, ויוצר Task לכל דרישה שנותרה שה-Status שלה הוא 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}")
- יש להריץ
python3 holarch_to_jira.py.מוצגת שורה אחת לכל issue חדש, כגון
2.1 Pointing Accuracy -> EO-12.
איך זה עובד:
GET /api/v1/projects/<project>/entities?class=Requirementמפרט את הדרישות, 500 בכל פעם.GET /api/v1/projects/<project>/entities/<id>נותן את המאפיינים של כל דרישה (כאן Status) ואת ה-urlשלה, הקישור שפותח אותה ב-Holarch.- כל issue מקבל את תוויות ה-Jira
holarchו-holarch-<id>. ההרצה הבאה מוצאת אותן בחיפוש Jira ומדלגת על הדרישות האלה. - הדרישות רק נקראות. הסקריפט אינו משנה דבר ב-Holarch.
שמירת מפתח ה-Jira ב-Holarch (אופציונלי)
כדי לראות את מפתח ה-Jira על הדרישה ב-Holarch, מוסיפים מאפיין טקסט וכותבים לתוכו את המפתח.
- ב-Holarch, יש לפתוח את הגדרות ← סכמה, ללחוץ על Requirement, ולהוסיף מאפיין בשם Jira Key מסוג טקסט קצר (הוספת מאפיין למחלקה).
- יש ליצור לסקריפט אסימון קריאה וכתיבה במקום אסימון הקריאה בלבד.
- בסוף הלולאה האחרונה של הסקריפט, אחרי השורה
print(…), יש להוסיף:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
השינוי נכתב כמו עריכה באפליקציה: הוא נרשם תחת השם שלך וכל מי שהפרויקט פתוח אצלו רואה אותו. הגדרת המאפיין הזה אינה מחזירה דרישה מאושרת לסקירה. כשהפרויקט משתמש בבקרת תצורה, דרישות מאושרות דוחות שינויים ישירים (409 change-control); אפשר לשמור את המפתח ב-Jira בלבד, או לבצע את השינוי דרך בקשת שינוי.
הפיכת issue של Jira להצעה ב-Holarch עם Claude
משתמשים בזה כש-issue של Jira מבקש שינוי בדרישה, כגון בקשה של לקוח להדק ערך.
- יש לפתוח את Claude, מחובר ל-Holarch עם גישת קריאה והצעת שינויים.
- אפשר לשאול, למשל: "קרא את ה-issue של Jira EO-31. מצא את דרישות ה-Holarch בפרויקט CubeSat שהוא משפיע עליהן, והצע את השינויים שהוא מבקש. ציין את EO-31 בסיכום ההצעה."
בלי מחבר Jira, מדביקים במקום זאת את התקציר והתיאור של ה-issue בהודעה.
- Claude קורא את הפרויקט עם
list_projects,search_entitiesו-get_entity. הוא מוסיף כל שינוי להצעה עםupdate_entity(אוcreate_entityו-relateלדרישות חדשות), ואז שולח אותה עםpropose_changes.Claude עונה עם הכותרת של ההצעה וקישור לסקירה שלה.
- ב-Holarch, יש לפתוח את ✦ AI ▾ ← סקירת “<title>”…, או את ההתראה מתחת לפעמון.
- יש לבדוק כל שינוי. מבטלים את הסימון של מה שאינו רצוי, ואז לוחצים על החלת הנבחרים.
השינויים מוחלים, וביטול פעולה אחד מחזיר הכול לאחור. טקסט דרישה ששונה מסמן את קישורי העקיבות שלה לבדיקה, ודרישה מאושרת חוזרת ל-In Review, כמו בכל עריכה.
סקריפטים יכולים ליצור את אותה הצעה בלי Claude: POST /api/v1/projects/<project>/proposal/changes פעם אחת לכל שינוי, ואז POST /api/v1/projects/<project>/proposal עם title ו-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
דוגמה מעשית: הדגמת CubeSat EO-1
- יוצרים את ההדגמה עם ניהול פרויקטים ← קובצי פרויקט ▾ ← פרויקט הדגמה חדש.
- יש ליצור אסימון קריאה בלבד שמוגבל לפרויקט ההדגמה, ולהריץ את
holarch_to_jira.pyמול פרויקט Jira לבדיקה.כל דרישה מאושרת מקבלת issue, כגון 2.1 Pointing Accuracy עם הטקסט "The ADCS shall point the payload boresight within 0.1 degrees of the commanded target." והקישור לדרישה.
- יש להריץ את הסקריפט שוב.
הוא אינו מדפיס דבר: לכל דרישה מאושרת כבר יש issue.
- ב-Jira, יש ליצור issue EO-31 שמבקש 0.08 מעלות במקום 0.1 מעלות. מבקשים מ-Claude להציע את השינוי, כמו למעלה.
- ב-Holarch, סוקרים את ההצעה. היא משנה את הטקסט של 2.1 Pointing Accuracy, והרשימה השפעה שלה מציגה את TC-04 Pointing Accuracy Test, שמאמת אותה.
טיפים
- כדאי לתת לסקריפט הסנכרון אסימון קריאה בלבד משלו, מוגבל לפרויקט, ול-Claude חיבור נפרד.
- אסימונים שומרים במאגר הסודות או בסביבה שלך, אף פעם לא בסקריפט.
- אפשר לחפש ב-Jira את הדרישות שמאחורי ספרינט עם התווית
holarch. - מספרי דרישות יכולים להשתנות; התווית
holarch-<id>לא. כדאי להתאים לפי התווית, לא לפי המספר בתקציר.
פתרון בעיות
| הודעה או תסמין | סיבה ותיקון |
|---|---|
Holarch answered 401 token-invalid | האסימון שגוי, בוטל או שתוקפו פג. יש ליצור אסימון חדש תחת הגדרות החשבון ← אסימוני API. |
Holarch answered 403 plan-api | התוכנית של החשבון אינה כוללת את ה-API ו-MCP. יש להתחיל את תקופת הניסיון של Individual או לבחור תוכנית; האסימון יפעל אז שוב. |
Holarch answered 403 org-policy | הארגון של הפרויקט כיבה את גישת ה-API. יש לפנות למנהל ארגון. |
Holarch answered 403 read-only-token | הכתיבה של Jira Key דורשת אסימון קריאה וכתיבה. |
Holarch answered 400 unknown-attribute | לפרויקט אין מאפיין Jira Key עבור Requirement. יש להוסיף אותו בהגדרות ← סכמה, או לוותר על השלב האופציונלי. |
Holarch answered 409 change-control | הדרישה נמצאת תחת בקרת תצורה. יש לשנות אותה דרך בקשת שינוי, או לשמור את המפתח ב-Jira בלבד. |
Holarch answered 429 rate-limited | יותר מ-600 בקשות או 120 שינויים בדקה. יש להמתין את מספר השניות שב-Retry-After, ואז להריץ שוב; issues שכבר הושלמו מדולגים. |
| Jira עונה 400 | Jira דחה את שדות ה-issue, למשל סוג issue שאין בפרויקט. יש להשתמש באחד מסוגי ה-issue של הפרויקט במקום Task. |
| Jira עונה 401 או 403 | יש לבדוק את JIRA_EMAIL, את JIRA_API_TOKEN ואת ההרשאה שלך ליצור issues בפרויקט ה-Jira. |
| Claude אינו מציג את כלי הכתיבה של Holarch | החיבור הוא לקריאה בלבד. יש להתחבר שוב עם קריאה והצעת שינויים, ואז להתחיל שיחה חדשה. |