Holarch

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.

Utilisation →

Sur cette page
  1. Vue d'ensemble
  2. Prérequis
  3. Mode d'emploi
    1. Quand et pourquoi
    2. Configurer le dépôt
    3. Exécuter les Contrôles du modèle selon un planning
    4. Proposer des cas de test pour une branche avec Claude Code
    5. Exemple complet : la démo CubeSat EO-1
    6. Conseils
  4. Dépannage
  5. Pages associées

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

  1. Dans Holarch, créez un jeton Lecture seule limité au projet : Paramètres du compte → Jetons API → Nouveau jeton (Créer un jeton).
  2. Trouvez l'id du projet : GET /api/v1/projects liste vos projets avec leur id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Dans GitHub, ouvrez Settings → Secrets and variables → Actions du dépôt :
    • Sous Secrets, ajoutez HOLARCH_TOKEN avec le jeton.
    • Sous Variables, ajoutez HOLARCH_PROJECT avec l'id du projet.
  2. 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=Requirement exé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-body fait échouer l'étape en cas d'erreur et affiche le message de Holarch, comme {"error": "…", "code": "token-invalid"}.
  • gh et jq sont fournis avec les runners Ubuntu de GitHub.

Variantes :

  • Autres règles : remplacez class=Requirement par une autre classe (Test Case, Asset, Custom pour vos jeux de règles), ou nommez une seule règle avec rule=Requirement.10.
  • Qualité des exigences : GET /api/v1/projects/<project>/quality note chaque exigence selon les neuf attributs de qualité. Listez de la même façon les exigences dont le score est inférieur à votre seuil.
  • Faire échouer l'exécution en cas de constats : ajoutez test "$total" -eq 0 comme 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.

  1. 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.

  1. 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. »
  2. Claude Code lit le diff avec git. Dans Holarch, il utilise search_entities et get_entity pour trouver les exigences, et run_model_checks avec la règle Requirement.10 pour voir lesquelles n'ont pas de cas de test qui les vérifie. Il ajoute chaque cas de test avec create_entity et sa relation verifies, puis envoie la proposition avec propose_changes.

    Claude Code répond avec le titre de la proposition et un lien pour l'examiner.

  3. Dans Holarch, ouvrez ✦ IA ▾ → Examiner « <title> »…, ou la notification sous la cloche.
  4. 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

  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.
  2. 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.

  3. 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.

  4. 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.
  5. 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ômeCause 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 introuvableCréez l'étiquette holarch dans le dépôt.
gh répond HTTP 403Le 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 HolarchLa connexion est en lecture seule. Exécutez /mcp, reconnectez holarch avec Lire et proposer des modifications, puis démarrez une nouvelle conversation.