Comment laisser Claude Code lire les checks GitNest et proposer une relance que vous validez dans osFoundry

À la fin de ce guide, vous pouvez demander à Claude Code « le change set de checkout est-il au vert ? » et obtenir une réponse lue depuis osFoundry, pas devinée à partir de vos tests locaux. Claude Code liste les checks du commit composé du change set, vous dit lequel a échoué et, s'il semble instable (flaky), demande une relance pour ce seul check. La relance ne démarre pas quand Claude Code la demande. Elle arrive dans osFoundry sous forme de carte « Retry GitNest check » portant la version du change set et le commit exact, et ne s'exécute que lorsque vous cliquez sur Approve retry.

Qui fait quoi

Mise en place

1. Ajouter osFoundry à Claude Code

$ claude mcp add --transport http -s user osfoundry https://api.osfoundry.io/api/v1/external-mcp

La CLI osFoundry affiche la même ligne avec osfoundry agent connect claude --print. Dans Claude Code, lancez /mcp, choisissez osfoundry puis Authenticate. Le navigateur ouvre osFoundry et vous choisissez un workspace. Les outils apparaissent ensuite sous la forme mcp__osfoundry__….

2. Vérifier que le dépôt a des checks et un runner

Un check qui n'a jamais tourné ne peut être ni lu ni relancé. Dans GitNest, ouvrez la page des paramètres du dépôt. Deux panneaux comptent ici :

• Check runners : « Checks run on your machine, not ours — osFoundry never executes your code on its own infrastructure. » (les checks tournent sur votre machine, pas chez osFoundry). Register runner vous donne un token, une seule fois, et la commande pour le démarrer, OSF_RUNNER_TOKEN=… osfoundry-runner --api https://api.osfoundry.io. Sans runner, le panneau prévient « Checks will stay queued until one is. »
• Required checks : des noms issus de .osfoundry/checks.yaml. « A change set cannot merge until every check named here has passed on its commit. »

3. Mettre le dépôt dans un projet, et la connexion dans le même projet

Dans GitNest, la section Project du dépôt indique « Connected agents in this project can use approved GitNest read tools when their connection owner still has repository access. » Seul le propriétaire du dépôt voit le sélecteur. Choisissez un projet, et osFoundry confirme « Repository project updated ».

Ouvrez ensuite l'icône de clé → Connected, sélectionnez la connexion Claude Code et, sous Projects, ajoutez-la à ce projet.

Exemple : Ajout de la connexion Claude Code au projet qui contient le dépôt

Sous Tools, dans le même panneau, « All supported tools are on by default. » Ceux qu'utilise ce guide apparaissent comme list gitnest work, list gitnest checks, list gitnest saved results, read gitnest work et propose gitnest check rerun. Pour que Claude Code reste en lecture seule sur les checks, décochez propose gitnest check rerun et cliquez sur Save tools.

Un vrai déroulé

Les noms d'outils et d'arguments sont ceux que renvoie le serveur osFoundry via tools/list. Le dépôt, le change set, les IDs, les noms de checks et les réponses sont des exemples.

Example

You: Is the checkout-retry change set in shop-api green? If a check failed
     for a reason that isn't the code, ask osFoundry to retry it.

Claude Code → mcp__osfoundry__list_granted_resources {}
            ← project "Payments" · GitNest repository "shop-api"
Claude Code → mcp__osfoundry__list_gitnest_work {"repository_id": "…", "kind": "changes"}
            ← "Fix double charge on checkout retry" (cs_4e81a0) · version 3
Claude Code → mcp__osfoundry__list_gitnest_checks {"repository_id": "…", "change_set_id": "cs_4e81a0"}
            ← composed commit 9c1e47a…: unit passed · lint passed · e2e failed
Claude Code → mcp__osfoundry__list_gitnest_saved_results {"repository_id": "…", "limit": 10}
            ← 2 saved results behind this change set
Claude Code → mcp__osfoundry__read_gitnest_work {"repository_id": "…", "kind": "runs", "item_id": "…"}
            ← run summary: payment client tests passed locally

Claude Code: unit and lint passed on 9c1e47a. e2e failed. The change only
             touches the payment client, and its tests passed in the saved
             run, so a retry is reasonable. Shall I propose one?

You: Yes.

Claude Code → mcp__osfoundry__propose_gitnest_check_rerun
                {"repository_id": "…", "change_set_id": "cs_4e81a0",
                 "check_name": "e2e", "expected_change_set_version": 3,
                 "expected_composition_oid": "9c1e47a…",
                 "idempotency_key": "rerun-5b0c…"}
            ← proposal waiting for the owner

Claude Code: The retry is waiting under Connected → Needs your approval.
             Tell me when you've approved it and I'll read the checks again.

Claude Code demande avant l'appel propose parce que l'outil est annoté destructiveHint: true. C'est sa propre demande d'autorisation, distincte de la validation dans osFoundry.

Avant de valider, regardez le change set lui-même. Sur sa page de revue dans GitNest, le panneau des checks se trouve au-dessus des onglets et résume le commit composé en une ligne, ici « Checks did not pass: e2e », avec chaque check et son statut en dessous. Un change set qui n'a pas été composé n'affiche aucun panneau, et un commit sans checks indique « No checks have run against this commit » au lieu d'une coche.

La cloche affiche « proposes retrying a GitNest check ». Sous icône de clé → Connected → votre connexion → Needs your approval, la carte indique :

Retry GitNest check in shop-api
Change set: cs_4e81a0 · expected version 3
Reviewed commit: 9c1e47a…
Check to retry: e2e
Review change set before approving
Expires …
[ Approve retry ]  [ Decline ]

Exemple : Une proposition Retry GitNest check sous Needs your approval

« Review change set before approving » ouvre la même page de revue. Si le commit de la carte est bien celui que vous avez regardé, cliquez sur Approve retry. Le check e2e est remis en file pour ce commit et votre runner le prend. Prévenez ensuite Claude Code, qui rappelle list_gitnest_checks.

Où s'arrête la limite

La relance désigne un commit, pas une branche. propose_gitnest_check_rerun exige expected_change_set_version et expected_composition_oid, donc la carte indique toujours quel commit composé Claude Code a vu échouer. Si quelqu'un recompose le change set pendant que la carte attend, le commit que vous valideriez n'est plus celui de la carte. osFoundry revérifie version, commit et état du check au moment du clic, et une carte périmée ne s'exécute pas. Le panneau affiche alors « Could not decide this proposal. Its access may have changed. » Demandez à Claude Code de relire les checks et de proposer sur le nouveau commit.

Seul un check terminé peut être relancé. La description de l'outil dit « retry one finished check », et l'état du check fait partie de la revérification. Un check déjà remis en file ou en cours d'exécution, parce que quelqu'un d'autre l'a relancé ou que le change set a été recomposé, n'est pas mis en file une seconde fois.

Un check par proposition. check_name est une seule chaîne de 200 caractères maximum. Relancer toute la suite demande une carte par check, chacune décidée par vous. Ainsi, la relance d'un e2e instable ne relance pas en douce un scan de sécurité que vous préférez laisser en échec.

Rien dans ce parcours ne tourne sur les machines d'osFoundry ni ne modifie le code. Les checks tournent sur les runners que vous avez enregistrés. Valider une relance remet un check en file, et c'est tout. Pas de recomposition, pas de merge, pas de publication. Le merge attend toujours que chaque check requis passe sur le commit.

Les lectures restent minimales. list_gitnest_checks renvoie un statut limité pour le seul commit composé actuel. list_gitnest_saved_results et read_gitnest_work omettent les bindings locaux et les identifiants, donc Claude Code peut vous dire qu'un test a échoué, mais il ne voit jamais votre token de runner ni le chemin de votre checkout local.

Pour essayer, enregistrez un runner sur une machine libre, poussez un change set avec un check que vous savez instable, et demandez à Claude Code s'il est au vert. La page GitNest montre les écrans dépôt, change set et checks, et la page Connected présente le panneau de validation.