Riferimento
Ricetta: GitHub
Eseguire i Controlli del modello di Holarch da GitHub Actions e seguire i rilievi come issue di GitHub, e lasciare che Claude Code proponga casi di test per i requisiti implementati da un ramo; configurazione, un file di workflow, un esempio svolto e risoluzione dei problemi.
In questa pagina
Panoramica
Questa ricetta collega un repository GitHub a un progetto Holarch. Si compone di due parti:
- Controlli del modello in GitHub Actions (REST API): un workflow pianificato esegue i controlli del modello di Holarch sui requisiti del progetto. Scrive i rilievi nel riepilogo dell'esecuzione e mantiene aggiornata con essi una issue di GitHub.
- Requisiti nella revisione del codice (MCP, tramite Claude Code): Claude Code legge il ramo su cui si sta lavorando, trova in Holarch i requisiti che implementa e propone casi di test che li verificano. Si esamina la proposta in Holarch prima che cambi qualcosa.
Holarch non ha un'app GitHub integrata. La ricetta usa la REST API e MCP, quindi ogni passaggio si può adattare.
Prerequisiti
- Un piano con l'API e MCP: Individual o Team, oppure la prova di Individual. Nel piano Free, li ha anche un account con un indirizzo email accademico verificato o in un'organizzazione di classe attiva (Piani e limiti).
- Un progetto Holarch. Il workflow si limita a leggerlo; le proposte di Claude Code richiedono il ruolo di editor o proprietario.
- Un repository GitHub in cui si possono aggiungere secret e variabili di Actions e in cui Actions può creare issue.
- Per la parte con Claude: Claude Code, connesso a Holarch con accesso Lettura e proposta di modifiche (Connettere Holarch a Claude).
Come usarlo
Quando e perché
I controlli del modello trovano lacune nel modello, come requisiti senza un caso di test che li verifica. Eseguirli secondo una pianificazione e seguire i rilievi dove il team già lavora mantiene visibili le lacune tra una revisione e l'altra. Claude Code chiude il cerchio dall'altro lato: quando il codice implementa un requisito, prepara la bozza del caso di test che lo verifica.
Configurare il repository
- In Holarch, creare un token Sola lettura limitato al progetto: Impostazioni account → Token API → Nuovo token (Creare un token).
- Trovare l'id del progetto:
GET /api/v1/projectselenca i propri progetti con il loroid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- In GitHub, aprire Settings → Secrets and variables → Actions del repository:
- In Secrets, aggiungere
HOLARCH_TOKENcon il token. - In Variables, aggiungere
HOLARCH_PROJECTcon l'id del progetto.
- In Secrets, aggiungere
- In Issues → Labels, creare l'etichetta
holarch. Il workflow la usa per trovare la sua issue.
Eseguire i controlli del modello secondo una pianificazione
Salvare questo file come .github/workflows/holarch-checks.yml ed eseguirne il 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
Per eseguirlo subito, aprire Actions → Holarch model checks → Run workflow.
Si vedono i rilievi nel riepilogo dell'esecuzione, una riga per rilievo, come Requirement.10 <number> <name>: Leaf requirements with no verifying test case. La issue Holarch Model Checks findings contiene lo stesso elenco. Quando i rilievi vengono risolti, l'esecuzione successiva la chiude.
Come funziona:
GET /api/v1/projects/<project>/model-checks?class=Requirementesegue i controlli con le impostazioni delle regole del progetto e restituisce i rilievi:rule,heading,entity(id,number,name) e gli elementi correlati. I risultati vengono restituiti, non memorizzati.curl --fail-with-bodyfa fallire il passaggio in caso di errore e stampa il messaggio di Holarch, come{"error": "…", "code": "token-invalid"}.ghejqsono inclusi nei runner Ubuntu di GitHub.
Varianti:
- Altre regole: cambiare
class=Requirementin un'altra classe (Test Case,Asset,Customper i propri set di regole), oppure indicare una regola conrule=Requirement.10. - Qualità dei requisiti:
GET /api/v1/projects/<project>/qualityassegna un punteggio a ogni requisito sui nove attributi di qualità. Elencare allo stesso modo i requisiti il cuiscoreè sotto la propria soglia. - Far fallire l'esecuzione in presenza di rilievi: aggiungere
test "$total" -eq 0come ultima riga, per esempio nei controlli di un ramo di rilascio.
Proporre casi di test per un ramo con Claude Code
Usare questa procedura prima di aprire una pull request, così i requisiti che una modifica implementa ricevono un caso di test che li verifica.
- Connettere una sola volta Claude Code a Holarch:
claude mcp add --transport http holarch https://app.holarch.app/mcp
Poi digitare /mcp, scegliere holarch → Authenticate, accedere a Holarch e fare clic su Consenti con Lettura e proposta di modifiche.
- Nel repository, sul proprio ramo, chiedere a Claude Code, per esempio: “Confronta questo ramo con main. Trova i requisiti del progetto Holarch CubeSat che la modifica implementa e proponi un caso di test per ciascuno che non ha un caso di test di verifica. Indica il ramo nel riepilogo della proposta.”
- Claude Code legge il diff con git. In Holarch usa
search_entitieseget_entityper trovare i requisiti, erun_model_checkscon la regolaRequirement.10per vedere quali non hanno un caso di test di verifica. Aggiunge ogni caso di test concreate_entitye la sua relazione verifies, poi invia la proposta conpropose_changes.Claude Code risponde con il titolo della proposta e un link per esaminarla.
- In Holarch, aprire ✦ IA ▾ → Rivedi “<title>”…, oppure la notifica sotto la campanella.
- Modificare nomi e descrizioni se necessario, quindi fare clic su Applica selezionati.
I casi di test vengono creati con il proprio nome nella cronologia, e un solo annullamento revoca tutto. L'esecuzione pianificata successiva del workflow non elenca più quei requisiti.
Incollare il link del requisito nella descrizione della pull request: get_entity e la REST API lo restituiscono come url. Apre il requisito per chiunque sia membro del progetto.
Esempio pratico: la demo CubeSat EO-1
- Creare la demo con Gestisci progetti → File di progetto ▾ → Nuovo progetto demo e usarne l'id come
HOLARCH_PROJECT. - Eseguire il workflow con Run workflow.
Il riepilogo elenca i requisiti segnalati dai controlli del modello, per esempio requisiti foglia senza un caso di test di verifica. La issue Holarch Model Checks findings elenca gli stessi.
- Su un ramo che modifica il codice di controllo d'assetto, chiedere a Claude Code di proporre casi di test per i requisiti che il ramo implementa.
I requisiti per quel codice sono 2.1 Pointing Accuracy e 2.2 Pointing Stability. Entrambi sono già verificati da TC-04 Pointing Accuracy Test, quindi non richiedono un nuovo caso di test.
- Chiedergli invece di proporre un caso di test per un requisito nell'elenco della issue, quindi esaminare e applicare la proposta in Holarch.
- Eseguire di nuovo il workflow.
Quel requisito non è più elencato.
Suggerimenti
- Dare al workflow il proprio token di sola lettura, limitato al progetto. Revocarlo in Impostazioni account → Token API quando si rimuove il workflow.
- Il workflow pianificato usa le impostazioni delle regole di Holarch: disattivare una regola o cambiarne il livello nei controlli del modello, e l'esecuzione successiva si adegua.
- Un token scade alla data scelta. Per un workflow scegliere un anno o mai, e annotare la data.
Risoluzione dei problemi
| Messaggio o sintomo | Causa e soluzione |
|---|---|
"code": "token-required" | Il secret HOLARCH_TOKEN è vuoto o mancante. Aggiungerlo in Settings → Secrets and variables → Actions. |
"code": "token-invalid" | Il token è errato, revocato o scaduto. Crearne uno nuovo e aggiornare il secret. |
"code": "plan-api" | Il piano dell'account non include l'API e MCP. Avviare la prova di Individual o scegliere un piano; il token torna allora a funzionare. |
"code": "org-policy" | L'organizzazione del progetto ha disattivato l'accesso API. Rivolgersi a un amministratore dell'organizzazione. |
"code": "not-found" | HOLARCH_PROJECT non è un progetto che il token può usare. Controllare l'id e l'impostazione Progetti del token. |
"code": "rate-limited" | Più di 600 richieste al minuto con questo token. Eseguire il workflow meno spesso, oppure dare agli altri script i propri token. |
gh issue create non riesce: etichetta non trovata | Creare l'etichetta holarch nel repository. |
gh risponde HTTP 403 | Il workflow richiede permissions: issues: write e le impostazioni di Actions del repository devono consentirlo. |
| Claude Code non offre gli strumenti di scrittura di Holarch | La connessione è di sola lettura. Eseguire /mcp, riconnettere holarch con Lettura e proposta di modifiche, quindi avviare una nuova conversazione. |