Referenz
Rezept: GitHub
Führen Sie Holarch-Modellprüfungen aus GitHub Actions aus und verfolgen Sie die Befunde als GitHub-Issue, und lassen Sie Claude Code Testfälle für die Anforderungen vorschlagen, die ein Branch umsetzt; Einrichtung, eine Workflow-Datei, ein durchgearbeitetes Beispiel und Fehlerbehebung.
Auf dieser Seite
Überblick
Dieses Rezept verbindet ein GitHub-Repository mit einem Holarch-Projekt. Es hat zwei Teile:
- Modellprüfungen in GitHub Actions (REST-API): Ein geplanter Workflow führt Holarchs Modellprüfungen für die Anforderungen des Projekts aus. Er schreibt die Befunde in die Zusammenfassung des Laufs und hält ein GitHub-Issue damit aktuell.
- Anforderungen im Code-Review (MCP, über Claude Code): Claude Code liest den Branch, an dem Sie arbeiten, findet die Anforderungen in Holarch, die er umsetzt, und schlägt Testfälle vor, die sie verifizieren. Sie prüfen den Vorschlag in Holarch, bevor sich etwas ändert.
Holarch hat keine eingebaute GitHub-App. 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. Der Workflow liest es nur; Vorschläge von Claude Code erfordern die Rolle Bearbeiter oder Eigentümer.
- Ein GitHub-Repository, in dem Sie Actions-Secrets und -Variablen hinzufügen können und in dem Actions Issues erstellen kann.
- Für den Teil mit Claude: Claude Code, mit Holarch verbunden mit dem Zugriff Lesen und Änderungen vorschlagen (Holarch mit Claude verbinden).
So setzen Sie es ein
Wann und warum
Modellprüfungen finden Lücken im Modell, etwa Anforderungen ohne verifizierenden Testfall. Sie nach Zeitplan auszuführen und die Befunde dort zu verfolgen, wo das Team ohnehin arbeitet, hält die Lücken zwischen Reviews sichtbar. Claude Code schließt den Kreis von der anderen Seite: Wenn Code eine Anforderung umsetzt, entwirft es den Testfall, der sie verifiziert.
Das Repository einrichten
- Erstellen Sie in Holarch ein Token mit Nur lesen, beschränkt auf das Projekt: Kontoeinstellungen → API-Token → Neues Token (Ein Token erstellen).
- 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
- Öffnen Sie in GitHub Settings → Secrets and variables → Actions des Repositorys:
- Fügen Sie unter Secrets
HOLARCH_TOKENmit dem Token hinzu. - Fügen Sie unter Variables
HOLARCH_PROJECTmit der Projekt-ID hinzu.
- Fügen Sie unter Secrets
- Erstellen Sie unter Issues → Labels das Label
holarch. Der Workflow findet sein Issue darüber.
Modellprüfungen nach Zeitplan ausführen
Speichern Sie diese Datei als .github/workflows/holarch-checks.yml und committen Sie sie.
# 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
Um ihn jetzt auszuführen, öffnen Sie Actions → Holarch model checks → Run workflow.
Sie sehen die Befunde in der Zusammenfassung des Laufs, eine Zeile pro Befund, etwa Requirement.10 <number> <name>: Leaf requirements with no verifying test case. Das Issue Holarch Model Checks findings enthält dieselbe Liste. Wenn die Befunde behoben sind, schließt der nächste Lauf es.
So funktioniert es:
GET /api/v1/projects/<project>/model-checks?class=Requirementführt die Prüfungen mit den eigenen Regeleinstellungen des Projekts aus und gibt die Befunde zurück:rule,heading,entity(id,number,name) und die zugehörigen Elemente. Ergebnisse werden zurückgegeben, nicht gespeichert.curl --fail-with-bodylässt den Schritt bei einem Fehler fehlschlagen und gibt die Meldung von Holarch aus, etwa{"error": "…", "code": "token-invalid"}.ghundjqsind in den Ubuntu-Runnern von GitHub enthalten.
Varianten:
- Andere Regeln: Ändern Sie
class=Requirementin eine andere Klasse (Test Case,Asset,Customfür Ihre Regelsätze) oder nennen Sie eine Regel mitrule=Requirement.10. - Anforderungsqualität:
GET /api/v1/projects/<project>/qualitybewertet jede Anforderung nach den neun Qualitätsattributen. Listen Sie auf dieselbe Weise die Anforderungen auf, derenscoreunter Ihrem Schwellenwert liegt. - Den Lauf bei Befunden fehlschlagen lassen: Fügen Sie
test "$total" -eq 0als letzte Zeile hinzu, zum Beispiel in den Prüfungen eines Release-Branches.
Mit Claude Code Testfälle für einen Branch vorschlagen
Verwenden Sie dies, bevor Sie einen Pull Request öffnen, damit die Anforderungen, die eine Änderung umsetzt, einen verifizierenden Testfall erhalten.
- Verbinden Sie Claude Code einmalig mit Holarch:
claude mcp add --transport http holarch https://app.holarch.app/mcp
Geben Sie dann /mcp ein, wählen Sie holarch → Authentifizieren, melden Sie sich bei Holarch an und klicken Sie mit Lesen und Änderungen vorschlagen auf Zulassen.
- Fragen Sie im Repository auf Ihrem Branch Claude Code zum Beispiel: „Vergleiche diesen Branch mit main. Finde die Anforderungen im Holarch-CubeSat-Projekt, die die Änderung umsetzt, und schlage für jede, die keinen verifizierenden Testfall hat, einen Testfall vor. Nenne den Branch in der Zusammenfassung des Vorschlags.“
- Claude Code liest den Diff mit git. In Holarch verwendet es
search_entitiesundget_entity, um die Anforderungen zu finden, undrun_model_checksmit der RegelRequirement.10, um zu sehen, welche keinen verifizierenden Testfall haben. Es fügt jeden Testfall mitcreate_entityund seiner Beziehung verifies hinzu und sendet dann den Vorschlag mitpropose_changes.Claude Code 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.
- Bearbeiten Sie bei Bedarf die Namen und Beschreibungen und klicken Sie dann auf Auswahl anwenden.
Die Testfälle werden mit Ihrem Namen im Verlauf erstellt, und ein einziges Rückgängigmachen nimmt alles zurück. Der nächste geplante Workflow-Lauf listet diese Anforderungen nicht mehr.
Fügen Sie den Link der Anforderung in die Beschreibung des Pull Requests ein: get_entity und die REST-API geben ihn als url zurück. Er öffnet die Anforderung für jeden, der Mitglied des Projekts ist.
Durchgehendes Beispiel: die CubeSat-EO-1-Demo
- Erstellen Sie die Demo mit Projekte verwalten → Projektdateien ▾ → Neues Demoprojekt und verwenden Sie ihre ID als
HOLARCH_PROJECT. - Führen Sie den Workflow mit Run workflow aus.
Die Zusammenfassung listet die Anforderungen, die die Modellprüfungen markieren, zum Beispiel Blattanforderungen ohne verifizierenden Testfall. Das Issue Holarch Model Checks findings listet dieselben.
- Bitten Sie Claude Code auf einem Branch, der den Code der Lageregelung ändert, Testfälle für die Anforderungen vorzuschlagen, die der Branch umsetzt.
Die Anforderungen für diesen Code sind 2.1 Pointing Accuracy und 2.2 Pointing Stability. Beide werden bereits von TC-04 Pointing Accuracy Test verifiziert, sie brauchen also keinen neuen Testfall.
- Bitten Sie es stattdessen, einen Testfall für eine Anforderung aus der Liste des Issues vorzuschlagen, und prüfen und wenden Sie den Vorschlag dann in Holarch an.
- Führen Sie den Workflow erneut aus.
Diese Anforderung wird nicht mehr aufgeführt.
Tipps
- Geben Sie dem Workflow ein eigenes Token mit Nur-Lesen-Zugriff, beschränkt auf das Projekt. Widerrufen Sie es unter Kontoeinstellungen → API-Token, wenn Sie den Workflow entfernen.
- Der geplante Workflow verwendet die Regeleinstellungen von Holarch: Schalten Sie in den Modellprüfungen eine Regel aus oder ändern Sie ihre Stufe, und der nächste Lauf folgt.
- Ein Token läuft an dem von Ihnen gewählten Datum ab. Wählen Sie für einen Workflow ein Jahr oder nie und notieren Sie das Datum.
Fehlerbehebung
| Meldung oder Symptom | Ursache und Behebung |
|---|---|
"code": "token-required" | Das Secret HOLARCH_TOKEN ist leer oder fehlt. Fügen Sie es unter Settings → Secrets and variables → Actions hinzu. |
"code": "token-invalid" | Das Token ist falsch, widerrufen oder abgelaufen. Erstellen Sie ein neues und aktualisieren Sie das Secret. |
"code": "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. |
"code": "org-policy" | Die Organisation des Projekts hat den API-Zugriff ausgeschaltet. Fragen Sie einen Organisationsadmin. |
"code": "not-found" | HOLARCH_PROJECT ist kein Projekt, das das Token verwenden kann. Prüfen Sie die ID und die Einstellung Projekte des Tokens. |
"code": "rate-limited" | Mehr als 600 Anfragen pro Minute mit diesem Token. Führen Sie den Workflow seltener aus oder geben Sie anderen Skripten eigene Token. |
gh issue create schlägt fehl: Label nicht gefunden | Erstellen Sie das Label holarch im Repository. |
gh antwortet mit HTTP 403 | Der Workflow braucht permissions: issues: write, und die Actions-Einstellungen des Repositorys müssen es erlauben. |
| Claude Code bietet die Holarch-Schreibwerkzeuge nicht an | Die Verbindung hat nur Lesezugriff. Führen Sie /mcp aus, verbinden Sie holarch erneut mit Lesen und Änderungen vorschlagen und beginnen Sie dann ein neues Gespräch. |