הפניה
מתכון: GitHub
הרצת בדיקות המודל של Holarch מ-GitHub Actions ומעקב אחר הממצאים כ-issue ב-GitHub, ומתן אפשרות ל-Claude Code להציע מקרי בדיקה לדרישות שענף מממש; הגדרה, קובץ workflow, דוגמה מעובדת ופתרון בעיות.
בדף זה
סקירה כללית
המתכון הזה מחבר מאגר GitHub לפרויקט Holarch. יש לו שני חלקים:
- בדיקות המודל ב-GitHub Actions (REST API): תהליך עבודה מתוזמן מריץ את בדיקות המודל של Holarch על הדרישות של הפרויקט. הוא כותב את הממצאים לסיכום של ההרצה ושומר issue אחד ב-GitHub מעודכן בהם.
- דרישות בסקירת קוד (MCP, דרך Claude Code): Claude Code קורא את הענף שעובדים עליו, מוצא ב-Holarch את הדרישות שהוא מממש, ומציע מקרי בדיקה שמאמתים אותן. סוקרים את ההצעה ב-Holarch לפני ששום דבר משתנה.
ל-Holarch אין אפליקציית GitHub מובנית. המתכון משתמש בREST API וב-MCP, כך שאפשר להתאים כל שלב.
דרישות מקדימות
- תוכנית עם ה-API ו-MCP: Individual או Team, או תקופת הניסיון של Individual. בתוכנית Free, גם לחשבון עם כתובת דוא״ל אקדמית מאומתת או בארגון כיתה פעיל יש אותם (תוכניות ומגבלות).
- פרויקט Holarch. תהליך העבודה רק קורא אותו; הצעות מ-Claude Code דורשות את תפקיד העורך או הבעלים.
- מאגר GitHub שבו אפשר להוסיף סודות ומשתנים של Actions, ושבו Actions יכולים ליצור issues.
- לחלק של Claude: Claude Code, מחובר ל-Holarch עם גישת קריאה והצעת שינויים (חיבור Holarch ל-Claude).
איך להשתמש בה
מתי ולמה
בדיקות המודל מוצאות פערים במודל, כגון דרישות בלי מקרה בדיקה מאמת. הרצה שלהן לפי לוח זמנים ומעקב אחר הממצאים במקום שבו הצוות כבר עובד שומרים את הפערים גלויים בין סקירות. Claude Code סוגר את המעגל מהצד השני: כשקוד מממש דרישה, הוא מנסח את מקרה הבדיקה שמאמת אותה.
הגדרת המאגר
- ב-Holarch, יש ליצור אסימון קריאה בלבד שמוגבל לפרויקט: הגדרות החשבון ← אסימוני API ← אסימון חדש (יצירת אסימון).
- יש למצוא את מזהה הפרויקט:
GET /api/v1/projectsמפרט את הפרויקטים שלך עם ה-idשלהם.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- ב-GitHub, יש לפתוח את Settings → Secrets and variables → Actions של המאגר:
- תחת Secrets, מוסיפים
HOLARCH_TOKENעם האסימון. - תחת Variables, מוסיפים
HOLARCH_PROJECTעם מזהה הפרויקט.
- תחת Secrets, מוסיפים
- תחת Issues → Labels, יוצרים את התווית
holarch. תהליך העבודה משתמש בה כדי למצוא את ה-issue שלו.
הרצת בדיקות המודל לפי לוח זמנים
יש לשמור את הקובץ הזה כ-.github/workflows/holarch-checks.yml ולבצע לו commit.
# Holarch Model Checks: requirement findings in the run summary and in one GitHub issue.
name: Holarch model checks
on:
schedule:
- cron: "0 6 * * 1-5" # weekdays at 06:00 UTC
workflow_dispatch:
permissions:
issues: write
jobs:
checks:
runs-on: ubuntu-latest
env:
HOLARCH_TOKEN: ${{ secrets.HOLARCH_TOKEN }}
HOLARCH_PROJECT: ${{ vars.HOLARCH_PROJECT }}
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
steps:
- name: Run Model Checks
run: |
curl -sS --fail-with-body -H "Authorization: Bearer $HOLARCH_TOKEN" \
"https://app.holarch.app/api/v1/projects/$HOLARCH_PROJECT/model-checks?class=Requirement" > checks.json
jq -r '"Holarch Model Checks: \(.total) requirement findings\n",
(.issues[] | "- [ ] \(.rule) \(.entity.number) \(.entity.name): \(.heading)")' checks.json > findings.md
cat findings.md >> "$GITHUB_STEP_SUMMARY"
- name: Update the tracking issue
run: |
total=$(jq .total checks.json)
issue=$(gh issue list --label holarch --state open --json number --jq '.[0].number')
if [ "$total" -gt 0 ] && [ -z "$issue" ]; then
gh issue create --title "Holarch Model Checks findings" --label holarch --body-file findings.md
elif [ "$total" -gt 0 ]; then
gh issue edit "$issue" --body-file findings.md
elif [ -n "$issue" ]; then
gh issue close "$issue" --comment "Holarch Model Checks find no requirement issues."
fi
כדי להריץ אותו עכשיו, פותחים את Actions → Holarch model checks → Run workflow.
הממצאים מוצגים בסיכום של ההרצה, שורה אחת לכל ממצא, כגון Requirement.10 <number> <name>: Leaf requirements with no verifying test case. ה-issue Holarch Model Checks findings מכיל את אותה רשימה. כשהממצאים מתוקנים, ההרצה הבאה סוגרת אותו.
איך זה עובד:
GET /api/v1/projects/<project>/model-checks?class=Requirementמריץ את הבדיקות עם הגדרות הכללים של הפרויקט עצמו ומחזיר את הממצאים:rule,heading,entity(id,number,name) והפריטים הקשורים. התוצאות מוחזרות, לא נשמרות.curl --fail-with-bodyמכשיל את השלב בשגיאה ומדפיס את ההודעה של Holarch, כגון{"error": "…", "code": "token-invalid"}.ghו-jqמגיעים עם ה-runners של Ubuntu ב-GitHub.
וריאציות:
- כללים אחרים: משנים את
class=Requirementלמחלקה אחרת (Test Case,Asset,Customלערכות הכללים שלך), או מציינים כלל אחד עםrule=Requirement.10. - איכות הדרישות:
GET /api/v1/projects/<project>/qualityנותן ציון לכל דרישה בתשעת מאפייני האיכות. באותה דרך מפרטים את הדרישות שה-scoreשלהן מתחת לסף שלך. - הכשלת ההרצה כשיש ממצאים: מוסיפים
test "$total" -eq 0כשורה האחרונה, למשל בבדיקות של ענף שחרור.
הצעת מקרי בדיקה לענף עם Claude Code
משתמשים בזה לפני שפותחים pull request, כדי שהדרישות ששינוי מממש יקבלו מקרה בדיקה מאמת.
- מחברים את Claude Code ל-Holarch פעם אחת:
claude mcp add --transport http holarch https://app.holarch.app/mcp
אחר כך מקלידים /mcp, בוחרים holarch ← אימות, נכנסים ל-Holarch ולוחצים על אישור עם קריאה והצעת שינויים.
- במאגר, בענף שלך, אפשר לשאול את Claude Code, למשל: "השווה את הענף הזה ל-main. מצא את הדרישות בפרויקט CubeSat ב-Holarch שהשינוי מממש, והצע מקרה בדיקה לכל אחת שאין לה מקרה בדיקה מאמת. ציין את הענף בסיכום ההצעה."
- Claude Code קורא את ה-diff עם git. ב-Holarch הוא משתמש ב-
search_entitiesוב-get_entityכדי למצוא את הדרישות, וב-run_model_checksעם הכללRequirement.10כדי לראות לאילו אין מקרה בדיקה מאמת. הוא מוסיף כל מקרה בדיקה עםcreate_entityועם הקשר verifies שלו, ואז שולח את ההצעה עםpropose_changes.Claude Code עונה עם הכותרת של ההצעה וקישור לסקירה שלה.
- ב-Holarch, יש לפתוח את ✦ AI ▾ ← סקירת “<title>”…, או את ההתראה מתחת לפעמון.
- אם צריך, עורכים את השמות והתיאורים, ואז לוחצים על החלת הנבחרים.
מקרי הבדיקה נוצרים עם השם שלך בהיסטוריה, וביטול פעולה אחד מחזיר הכול לאחור. ההרצה המתוזמנת הבאה של תהליך העבודה כבר אינה מפרטת את הדרישות האלה.
כדאי להדביק את הקישור של הדרישה בתיאור ה-pull request: get_entity וה-REST API מחזירים אותו כ-url. הוא פותח את הדרישה לכל מי שחבר בפרויקט.
דוגמה מעשית: הדגמת CubeSat EO-1
- יוצרים את ההדגמה עם ניהול פרויקטים ← קובצי פרויקט ▾ ← פרויקט הדגמה חדש, ומשתמשים במזהה שלה כ-
HOLARCH_PROJECT. - מריצים את תהליך העבודה עם Run workflow.
הסיכום מפרט את הדרישות שבדיקות המודל מסמנות, למשל דרישות עלה בלי מקרה בדיקה מאמת. ה-issue Holarch Model Checks findings מפרט את אותן.
- בענף שמשנה את קוד בקרת הגישה (attitude control), מבקשים מ-Claude Code להציע מקרי בדיקה לדרישות שהענף מממש.
הדרישות של הקוד הזה הן 2.1 Pointing Accuracy ו-2.2 Pointing Stability. שתיהן כבר מאומתות על ידי TC-04 Pointing Accuracy Test, כך שאינן צריכות מקרה בדיקה חדש.
- במקום זאת מבקשים ממנו להציע מקרה בדיקה לדרישה מהרשימה של ה-issue, ואז סוקרים ומחילים את ההצעה ב-Holarch.
- מריצים שוב את תהליך העבודה.
הדרישה הזו כבר אינה מופיעה ברשימה.
טיפים
- כדאי לתת לתהליך העבודה אסימון קריאה בלבד משלו, מוגבל לפרויקט. כשמסירים את תהליך העבודה, מבטלים את האסימון תחת הגדרות החשבון ← אסימוני API.
- תהליך העבודה המתוזמן משתמש בהגדרות הכללים של Holarch: מכבים כלל או משנים את הרמה שלו בבדיקות המודל, וההרצה הבאה פועלת בהתאם.
- תוקפו של אסימון פג בתאריך שבחרת. לתהליך עבודה כדאי לבחור שנה אחת או אף פעם, ולרשום את התאריך.
פתרון בעיות
| הודעה או תסמין | סיבה ותיקון |
|---|---|
"code": "token-required" | הסוד HOLARCH_TOKEN ריק או חסר. יש להוסיף אותו תחת Settings → Secrets and variables → Actions. |
"code": "token-invalid" | האסימון שגוי, בוטל או שתוקפו פג. יש ליצור אסימון חדש ולעדכן את הסוד. |
"code": "plan-api" | התוכנית של החשבון אינה כוללת את ה-API ו-MCP. יש להתחיל את תקופת הניסיון של Individual או לבחור תוכנית; האסימון יפעל אז שוב. |
"code": "org-policy" | הארגון של הפרויקט כיבה את גישת ה-API. יש לפנות למנהל ארגון. |
"code": "not-found" | HOLARCH_PROJECT אינו פרויקט שהאסימון יכול להשתמש בו. יש לבדוק את המזהה ואת ההגדרה פרויקטים של האסימון. |
"code": "rate-limited" | יותר מ-600 בקשות בדקה עם האסימון הזה. יש להריץ את תהליך העבודה בתדירות נמוכה יותר, או לתת לסקריפטים אחרים אסימונים משלהם. |
gh issue create נכשל: התווית לא נמצאה | יש ליצור את התווית holarch במאגר. |
gh עונה HTTP 403 | תהליך העבודה צריך permissions: issues: write, והגדרות ה-Actions של המאגר חייבות להתיר זאת. |
| Claude Code אינו מציע את כלי הכתיבה של Holarch | החיבור הוא לקריאה בלבד. יש להריץ /mcp, לחבר מחדש את holarch עם קריאה והצעת שינויים, ואז להתחיל שיחה חדשה. |