Référence
Recette : GitHub
Exécutez les contrôles du modèle Holarch depuis GitHub Actions et suivez les constats dans un ticket GitHub, et laissez Claude Code proposer des cas de test pour les exigences qu'une branche met en œuvre ; configuration, fichier de workflow, exemple complet et dépannage.
Sur cette page
Vue d'ensemble
Cette recette relie un dépôt GitHub à un projet Holarch. Elle comporte deux parties :
- Contrôles du modèle dans GitHub Actions (API REST) : un workflow planifié exécute les Contrôles du modèle de Holarch sur les exigences du projet. Il écrit les constats dans le résumé de l'exécution et tient un ticket GitHub à jour avec eux.
- Les exigences dans la revue de code (MCP, par Claude Code) : Claude Code lit la branche sur laquelle vous travaillez, trouve dans Holarch les exigences qu'elle met en œuvre et propose des cas de test qui les vérifient. Vous examinez la proposition dans Holarch avant que quoi que ce soit change.
Holarch n'a pas d'application GitHub intégrée. La recette utilise l'API REST et MCP : vous pouvez donc adapter chaque étape.
Prérequis
- Une offre avec l'API et MCP : Individual ou Team, ou l'essai Individual. Avec l'offre Free, un compte doté d'une adresse e-mail académique vérifiée ou appartenant à une organisation de cours active en dispose aussi (Offres et limites).
- Un projet Holarch. Le workflow ne fait que le lire ; les propositions de Claude Code nécessitent le rôle d'éditeur ou de propriétaire.
- Un dépôt GitHub dans lequel vous pouvez ajouter des secrets et des variables Actions, et dans lequel Actions peut créer des tickets.
- Pour la partie Claude : Claude Code, connecté à Holarch avec l'accès Lire et proposer des modifications (Connecter Holarch à Claude).
Mode d'emploi
Quand et pourquoi
Les Contrôles du modèle trouvent les lacunes du modèle, comme les exigences sans cas de test qui les vérifie. Les exécuter selon un planning et suivre les constats là où l'équipe travaille déjà garde les lacunes visibles entre les revues. Claude Code boucle la boucle de l'autre côté : lorsque du code met en œuvre une exigence, il rédige le cas de test qui la vérifie.
Configurer le dépôt
- Dans Holarch, créez un jeton Lecture seule limité au projet : Paramètres du compte → Jetons API → Nouveau jeton (Créer un jeton).
- Trouvez l'id du projet :
GET /api/v1/projectsliste vos projets avec leurid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- Dans GitHub, ouvrez Settings → Secrets and variables → Actions du dépôt :
- Sous Secrets, ajoutez
HOLARCH_TOKENavec le jeton. - Sous Variables, ajoutez
HOLARCH_PROJECTavec l'id du projet.
- Sous Secrets, ajoutez
- Sous Issues → Labels, créez l'étiquette
holarch. Le workflow l'utilise pour trouver son ticket.
Exécuter les Contrôles du modèle selon un planning
Enregistrez ce fichier sous .github/workflows/holarch-checks.yml et validez-le (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
Pour l'exécuter maintenant, ouvrez Actions → Holarch model checks → Run workflow.
Vous voyez les constats dans le résumé de l'exécution, une ligne par constat, comme Requirement.10 <number> <name>: Leaf requirements with no verifying test case. Le ticket Holarch Model Checks findings contient la même liste. Lorsque les constats sont corrigés, l'exécution suivante le ferme.
Fonctionnement :
GET /api/v1/projects/<project>/model-checks?class=Requirementexécute les contrôles avec les paramètres de règles propres au projet et renvoie les constats :rule,heading,entity(id,number,name) et les éléments associés. Les résultats sont renvoyés, pas stockés.curl --fail-with-bodyfait échouer l'étape en cas d'erreur et affiche le message de Holarch, comme{"error": "…", "code": "token-invalid"}.ghetjqsont fournis avec les runners Ubuntu de GitHub.
Variantes :
- Autres règles : remplacez
class=Requirementpar une autre classe (Test Case,Asset,Custompour vos jeux de règles), ou nommez une seule règle avecrule=Requirement.10. - Qualité des exigences :
GET /api/v1/projects/<project>/qualitynote chaque exigence selon les neuf attributs de qualité. Listez de la même façon les exigences dont lescoreest inférieur à votre seuil. - Faire échouer l'exécution en cas de constats : ajoutez
test "$total" -eq 0comme dernière ligne, par exemple dans les contrôles d'une branche de publication.
Proposer des cas de test pour une branche avec Claude Code
Utilisez ceci avant d'ouvrir une pull request, pour que les exigences mises en œuvre par une modification reçoivent un cas de test qui les vérifie.
- Connectez Claude Code à Holarch une fois :
claude mcp add --transport http holarch https://app.holarch.app/mcp
Saisissez ensuite /mcp, choisissez holarch → Authenticate, connectez-vous à Holarch et cliquez sur Autoriser avec Lire et proposer des modifications.
- Dans le dépôt, sur votre branche, demandez par exemple à Claude Code : « Compare cette branche avec main. Trouve les exigences du projet Holarch CubeSat que la modification met en œuvre, et propose un cas de test pour chacune de celles qui n'ont pas de cas de test qui les vérifie. Nomme la branche dans le résumé de la proposition. »
- Claude Code lit le diff avec git. Dans Holarch, il utilise
search_entitiesetget_entitypour trouver les exigences, etrun_model_checksavec la règleRequirement.10pour voir lesquelles n'ont pas de cas de test qui les vérifie. Il ajoute chaque cas de test aveccreate_entityet sa relation verifies, puis envoie la proposition avecpropose_changes.Claude Code répond avec le titre de la proposition et un lien pour l'examiner.
- Dans Holarch, ouvrez ✦ IA ▾ → Examiner « <title> »…, ou la notification sous la cloche.
- Modifiez les noms et les descriptions si nécessaire, puis cliquez sur Appliquer la sélection.
Les cas de test sont créés avec votre nom dans l'historique, et une seule annulation défait le tout. L'exécution planifiée suivante du workflow ne liste plus ces exigences.
Collez le lien de l'exigence dans la description de la pull request : get_entity et l'API REST le renvoient sous url. Il ouvre l'exigence pour toute personne membre du projet.
Exemple complet : la démo CubeSat EO-1
- Créez la démonstration avec Gérer les projets → Fichiers de projet ▾ → Nouveau projet de démonstration, et utilisez son id comme
HOLARCH_PROJECT. - Exécutez le workflow avec Run workflow.
Le résumé liste les exigences que les Contrôles du modèle signalent, par exemple les exigences terminales sans cas de test qui les vérifie. Le ticket Holarch Model Checks findings liste les mêmes.
- Sur une branche qui modifie le code de contrôle d'attitude, demandez à Claude Code de proposer des cas de test pour les exigences que la branche met en œuvre.
Les exigences de ce code sont 2.1 Pointing Accuracy et 2.2 Pointing Stability. Toutes deux sont déjà vérifiées par TC-04 Pointing Accuracy Test : elles n'ont donc pas besoin de nouveau cas de test.
- Demandez-lui plutôt de proposer un cas de test pour une exigence de la liste du ticket, puis examinez et appliquez la proposition dans Holarch.
- Exécutez de nouveau le workflow.
Cette exigence n'est plus listée.
Conseils
- Donnez au workflow son propre jeton en lecture seule, limité au projet. Révoquez-le sous Paramètres du compte → Jetons API lorsque vous retirez le workflow.
- Le workflow planifié utilise les paramètres de règles de Holarch : désactivez une règle ou modifiez son niveau dans les Contrôles du modèle, et l'exécution suivante en tient compte.
- Un jeton expire à la date que vous avez choisie. Choisissez un an ou jamais pour un workflow, et notez la date.
Dépannage
| Message ou symptôme | Cause et solution |
|---|---|
"code": "token-required" | Le secret HOLARCH_TOKEN est vide ou absent. Ajoutez-le sous Settings → Secrets and variables → Actions. |
"code": "token-invalid" | Le jeton est erroné, révoqué ou expiré. Créez-en un nouveau et mettez à jour le secret. |
"code": "plan-api" | L'offre du compte ne comprend pas l'API et MCP. Démarrez l'essai Individual ou choisissez une offre ; le jeton fonctionne alors de nouveau. |
"code": "org-policy" | L'organisation du projet a désactivé l'accès API. Adressez-vous à un administrateur de l'organisation. |
"code": "not-found" | HOLARCH_PROJECT n'est pas un projet que le jeton peut utiliser. Vérifiez l'id, ainsi que le paramètre Projets du jeton. |
"code": "rate-limited" | Plus de 600 requêtes par minute avec ce jeton. Exécutez le workflow moins souvent, ou donnez aux autres scripts leurs propres jetons. |
gh issue create échoue : étiquette introuvable | Créez l'étiquette holarch dans le dépôt. |
gh répond HTTP 403 | Le workflow nécessite permissions: issues: write, et les paramètres Actions du dépôt doivent l'autoriser. |
| Claude Code ne propose pas les outils d'écriture de Holarch | La connexion est en lecture seule. Exécutez /mcp, reconnectez holarch avec Lire et proposer des modifications, puis démarrez une nouvelle conversation. |