Referencja
Przepis: GitHub
Uruchamiaj Kontrole modelu Holarch z GitHub Actions i śledź ustalenia jako zgłoszenie GitHub oraz pozwól Claude Code proponować przypadki testowe dla wymagań implementowanych przez gałąź; konfiguracja, plik przepływu pracy, przykład krok po kroku i rozwiązywanie problemów.
Na tej stronie
Przegląd
Ten przepis łączy repozytorium GitHub z projektem Holarch. Ma dwie części:
- Kontrole modelu w GitHub Actions (REST API): zaplanowany przepływ pracy uruchamia kontrole modelu Holarch na wymaganiach projektu. Zapisuje ustalenia w podsumowaniu przebiegu i utrzymuje z nimi aktualne jedno zgłoszenie GitHub.
- Wymagania w przeglądzie kodu (MCP, przez Claude Code): Claude Code odczytuje gałąź, nad którą pracujesz, znajduje w Holarch realizowane przez nią wymagania i proponuje weryfikujące je przypadki testowe. Przeglądasz propozycję w Holarch, zanim cokolwiek się zmieni.
Holarch nie ma wbudowanej aplikacji GitHub. 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. Przepływ pracy tylko go odczytuje; propozycje z Claude Code wymagają roli edytora lub właściciela.
- Repozytorium GitHub, w którym możesz dodawać sekrety i zmienne Actions i w którym Actions mogą tworzyć zgłoszenia.
- Dla części z Claude: Claude Code połączony z Holarch z dostępem Odczyt i proponowanie zmian (Podłączanie Holarch do Claude).
Jak z niego korzystać
Kiedy i dlaczego
Kontrole modelu znajdują luki w modelu, np. wymagania bez weryfikującego przypadku testowego. Uruchamianie ich według harmonogramu i śledzenie ustaleń tam, gdzie zespół już pracuje, utrzymuje luki widoczne między przeglądami. Claude Code zamyka pętlę od drugiej strony: gdy kod realizuje wymaganie, przygotowuje projekt weryfikującego je przypadku testowego.
Konfiguracja repozytorium
- W Holarch utwórz token Tylko do odczytu ograniczony do projektu: Ustawienia konta → Tokeny API → Nowy token (Tworzenie tokenu).
- Znajdź id projektu:
GET /api/v1/projectswymienia Twoje projekty z ichid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- W GitHub otwórz Settings → Secrets and variables → Actions repozytorium:
- W sekcji Secrets dodaj
HOLARCH_TOKENz tokenem. - W sekcji Variables dodaj
HOLARCH_PROJECTz id projektu.
- W sekcji Secrets dodaj
- W Issues → Labels utwórz etykietę
holarch. Przepływ pracy używa jej do znalezienia swojego zgłoszenia.
Uruchamianie kontroli modelu według harmonogramu
Zapisz ten plik jako .github/workflows/holarch-checks.yml i zatwierdź go (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
Aby uruchomić go teraz, otwórz Actions → Holarch model checks → Run workflow.
Ustalenia widać w podsumowaniu przebiegu, jeden wiersz na ustalenie, np. Requirement.10 <number> <name>: Leaf requirements with no verifying test case. Zgłoszenie Holarch Model Checks findings zawiera tę samą listę. Gdy ustalenia zostaną naprawione, następny przebieg je zamyka.
Jak to działa:
GET /api/v1/projects/<project>/model-checks?class=Requirementwykonuje kontrole z własnymi ustawieniami reguł projektu i zwraca ustalenia:rule,heading,entity(id,number,name) i powiązane elementy. Wyniki są zwracane, a nie zapisywane.curl --fail-with-bodyprzerywa krok przy błędzie i wypisuje komunikat Holarch, np.{"error": "…", "code": "token-invalid"}.ghijqsą dostępne w maszynach Ubuntu GitHub.
Warianty:
- Inne reguły: zmień
class=Requirementna inną klasę (Test Case,Asset,Customdla własnych zestawów reguł) lub wskaż jedną regułę przezrule=Requirement.10. - Jakość wymagań:
GET /api/v1/projects/<project>/qualityocenia każde wymaganie według dziewięciu atrybutów jakości. W ten sam sposób wyświetl wymagania, którychscorejest poniżej Twojego progu. - Przerywanie przebiegu przy ustaleniach: dodaj
test "$total" -eq 0jako ostatni wiersz, na przykład w kontrolach gałęzi wydania.
Proponowanie przypadków testowych dla gałęzi za pomocą Claude Code
Użyj tego przed otwarciem pull requesta, aby wymagania realizowane przez zmianę otrzymały weryfikujący przypadek testowy.
- Połącz Claude Code z Holarch jeden raz:
claude mcp add --transport http holarch https://app.holarch.app/mcp
Następnie wpisz /mcp, wybierz holarch → Authenticate, zaloguj się do Holarch i kliknij Zezwól z dostępem Odczyt i proponowanie zmian.
- W repozytorium, na swojej gałęzi, poproś Claude Code na przykład: “Porównaj tę gałąź z main. Znajdź w projekcie Holarch CubeSat wymagania realizowane przez tę zmianę i zaproponuj przypadek testowy dla każdego, które nie ma weryfikującego przypadku testowego. Podaj nazwę gałęzi w podsumowaniu propozycji.”
- Claude Code odczytuje różnice za pomocą git. W Holarch używa
search_entitiesiget_entity, aby znaleźć wymagania, orazrun_model_checksz regułąRequirement.10, aby sprawdzić, które nie mają weryfikującego przypadku testowego. Dodaje każdy przypadek testowy za pomocącreate_entitywraz z relacją verifies, a następnie wysyła propozycję za pomocąpropose_changes.Claude Code odpowiada tytułem propozycji i łączem do jej przeglądu.
- W Holarch otwórz ✦ AI ▾ → Przejrzyj “<title>”… albo powiadomienie pod dzwonkiem.
- W razie potrzeby edytuj nazwy i opisy, a następnie kliknij Zastosuj zaznaczone.
Przypadki testowe zostają utworzone z Twoim nazwiskiem w historii, a jedno polecenie Cofnij wycofuje całość. Następny zaplanowany przebieg przepływu pracy przestaje wymieniać te wymagania.
Wklej łącze do wymagania w opisie pull requesta: get_entity i REST API zwracają je jako url. Otwiera ono wymaganie dla każdego członka projektu.
Przykład: demo CubeSat EO-1
- Utwórz projekt demonstracyjny poleceniem Zarządzaj projektami → Pliki projektów ▾ → Nowy projekt demonstracyjny i użyj jego id jako
HOLARCH_PROJECT. - Uruchom przepływ pracy przyciskiem Run workflow.
Podsumowanie wymienia wymagania oznaczone przez kontrole modelu, na przykład wymagania liście bez weryfikującego przypadku testowego. Zgłoszenie Holarch Model Checks findings wymienia to samo.
- Na gałęzi zmieniającej kod sterowania orientacją poproś Claude Code o zaproponowanie przypadków testowych dla wymagań realizowanych przez gałąź.
Wymagania dla tego kodu to 2.1 Pointing Accuracy i 2.2 Pointing Stability. Oba są już weryfikowane przez TC-04 Pointing Accuracy Test, więc nie potrzebują nowego przypadku testowego.
- Poproś zamiast tego o zaproponowanie przypadku testowego dla wymagania z listy zgłoszenia, a następnie przejrzyj i zastosuj propozycję w Holarch.
- Uruchom przepływ pracy ponownie.
To wymaganie nie jest już wymienione.
Wskazówki
- Daj przepływowi pracy własny token tylko do odczytu, ograniczony do projektu. Unieważnij go w Ustawienia konta → Tokeny API po usunięciu przepływu pracy.
- Zaplanowany przepływ pracy używa ustawień reguł Holarch: wyłącz regułę lub zmień jej poziom w Kontrolach modelu, a następny przebieg to uwzględni.
- Token wygasa w wybranym dniu. Dla przepływu pracy wybierz rok lub nigdy i zanotuj datę.
Rozwiązywanie problemów
| Komunikat lub objaw | Przyczyna i rozwiązanie |
|---|---|
"code": "token-required" | Sekret HOLARCH_TOKEN jest pusty lub go brak. Dodaj go w Settings → Secrets and variables → Actions. |
"code": "token-invalid" | Token jest błędny, unieważniony lub wygasł. Utwórz nowy i zaktualizuj sekret. |
"code": "plan-api" | Plan konta nie obejmuje API i MCP. Rozpocznij okres próbny Individual lub wybierz plan; token znów zadziała. |
"code": "org-policy" | Organizacja projektu wyłączyła dostęp przez API. Zwróć się do administratora organizacji. |
"code": "not-found" | HOLARCH_PROJECT nie jest projektem, którego token może używać. Sprawdź id i ustawienie Projekty tokenu. |
"code": "rate-limited" | Ponad 600 żądań na minutę z tym tokenem. Uruchamiaj przepływ pracy rzadziej lub daj innym skryptom własne tokeny. |
gh issue create kończy się błędem: nie znaleziono etykiety | Utwórz w repozytorium etykietę holarch. |
gh odpowiada HTTP 403 | Przepływ pracy wymaga permissions: issues: write, a ustawienia Actions repozytorium muszą na to pozwalać. |
| Claude Code nie oferuje narzędzi zapisu Holarch | Połączenie jest tylko do odczytu. Uruchom /mcp, połącz ponownie holarch z dostępem Odczyt i proponowanie zmian, a następnie rozpocznij nową rozmowę. |