Cómo hacer que Claude Code lea los checks de GitNest y proponga un reintento que tú apruebas en osFoundry

Al terminar esta guía, puedes preguntarle a Claude Code "¿está en verde el change set de checkout?" y recibir una respuesta leída de osFoundry, no deducida de tu ejecución local de tests. Claude Code lista los checks del commit compuesto del change set, te dice cuál falló y, si parece inestable (flaky), solicita un reintento solo para ese check. El reintento no empieza cuando Claude Code lo pide. Llega a osFoundry como una tarjeta "Retry GitNest check" con la versión del change set y el commit exacto, y solo se ejecuta cuando haces clic en Approve retry. Quién hace qué Claude Code osFoundry Inicio de sesión Su propio login en tu máquina La conexión que aprobaste una vez para un workspace, con los scopes osfoundry:read y osfoundry:write Qué repositorio Elige entre los que lista el servidor Solo repositorios de GitNest asignados a un proyecto en el que está la conexión Leer checks list_gitnest_checks sobre un change set Devuelve un estado acotado del commit compuesto actual del change set Ejecutar checks Nunca Los ejecutan tus máquinas runner registradas. osFoundry no ejecuta tu código Reintentar un check propose_gitnest_check_rerun, marcada como destructiva, así que Claude Code te pregunta antes Una tarjeta bajo "Needs your approval" (necesita tu aprobación). Approve retry vuelve a encolar ese único check terminado Qué se vuelve a comprobar Nada Al aprobar: acceso al repositorio, versión del change set, commit y estado del check Configuración 1. Añade osFoundry a Claude Code $ claude mcp add --transport http -s user osfoundry https://api.osfoundry.io/api/v1/external-mcp La CLI de osFoundry imprime la misma línea con osfoundry agent connect claude --print. En Claude Code, ejecuta /mcp, elige osfoundry y selecciona Authenticate. El navegador abre osFoundry y ahí eliges un workspace. Después, las herramientas aparecen como mcp__osfoundry__…. 2. Asegúrate de que el repositorio tiene checks y un runner Un check que nunca se ejecutó no se puede leer ni reintentar. En GitNest, abre la página de ajustes del repositorio. Aquí importan dos paneles: Check runners: "Checks run on your machine, not ours — osFoundry never executes your code on its own infrastructure." (los checks corren en tu máquina, no en la de osFoundry). Register runner te da un token una sola vez y el comando para arrancarlo, OSF_RUNNER_TOKEN=… osfoundry-runner --api https://api.osfoundry.io. Sin runner, el panel avisa "Checks will stay queued until one is." Required checks: nombres sacados de .osfoundry/checks.yaml. "A change set cannot merge until every check named here has passed on its commit." 3. Mete el repositorio en un proyecto, y la conexión en el mismo proyecto En GitNest, la sección Project del repositorio dice "Connected agents in this project can use approved GitNest read tools when their connection owner still has repository access." Solo el propietario del repositorio ve el selector. Elige un proyecto y osFoundry confirma "Repository project updated". Luego abre el icono de la llave → Connected, selecciona la conexión de Claude Code y, en Projects, añádela a ese proyecto. Ejemplo: Añadiendo la conexión de Claude Code al proyecto que contiene el repositorio En Tools, dentro del mismo panel, "All supported tools are on by default." Las que usa esta guía aparecen como list gitnest work, list gitnest checks, list gitnest saved results, read gitnest work y propose gitnest check rerun. Si quieres que Claude Code solo pueda leer los checks, desmarca propose gitnest check rerun y haz clic en Save tools. Una ejecución real Los nombres de herramientas y argumentos son los que devuelve el servidor de osFoundry en tools/list. El repositorio, el change set, los IDs, los nombres de los checks y las respuestas son contenido de ejemplo. 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 pregunta antes de la llamada propose porque la herramienta está anotada con destructiveHint: true. Es su propio aviso de permisos, independiente de la aprobación de osFoundry. Antes de aprobar, mira el propio change set. En su página de revisión en GitNest, el panel de checks está encima de las pestañas y resume el commit compuesto en una línea, aquí "Checks did not pass: e2e", con cada check y su estado debajo. Un change set que no se ha compuesto no muestra ningún panel, y un commit sin checks dice "No checks have run against this commit" en lugar de mostrar un tick. La campana muestra " proposes retrying a GitNest check". En icono de la llave → Connected → tu conexión → Needs your approval, la tarjeta dice: 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 ] Ejemplo: Una propuesta Retry GitNest check bajo Needs your approval "Review change set before approving" abre esa misma página de revisión. Si el commit de la tarjeta es el que has revisado, haz clic en Approve retry. El check e2e vuelve a la cola para ese commit y tu runner lo recoge. Después díselo a Claude Code, y volverá a llamar a list_gitnest_checks. Dónde está el límite El reintento apunta a un commit, no a una rama. propose_gitnest_check_rerun exige expected_change_set_version y expected_composition_oid, así que la tarjeta siempre indica qué commit compuesto vio fallar Claude Code. Si alguien vuelve a componer el change set mientras la tarjeta espera, el commit que estarías aprobando ya no es el de la tarjeta. osFoundry vuelve a comprobar versión, commit y estado del check cuando haces clic, y una tarjeta desactualizada no se ejecuta. El panel muestra entonces "Could not decide this proposal. Its access may have changed." Pide a Claude Code que lea los checks otra vez y que proponga sobre el nuevo commit. Solo se puede reintentar un check terminado. La descripción de la herramienta dice "retry one finished check", y el estado del check forma parte de la comprobación. Un check que ya está en cola o ejecutándose de nuevo, porque otra persona lo reintentó o porque el change set se recompuso, no se encola por segunda vez. Un check por propuesta. check_name es un único string de hasta 200 caracteres. Reintentar toda la suite supone una tarjeta por check, y cada una la decides tú. Así, reintentar un e2e inestable no relanza en silencio un análisis de seguridad que prefieres que siga en rojo. Nada en este flujo se ejecuta en máquinas de osFoundry ni cambia código. Los checks corren en los runners que registraste. Aprobar un reintento vuelve a encolar un check, y nada más. No recompone, no hace merge ni publica. El merge sigue esperando a que todos los checks obligatorios pasen en el commit. Las lecturas son mínimas. list_gitnest_checks devuelve un estado acotado solo del commit compuesto actual. list_gitnest_saved_results y read_gitnest_work dejan fuera los bindings locales y las credenciales, así que Claude Code puede decirte que un test falló, pero nunca ve tu token de runner ni la ruta de tu checkout local. Para probarlo, registra un runner en una máquina libre, sube un change set con un check que sepas que es inestable y pregúntale a Claude Code si está en verde. La página de GitNest muestra las pantallas de repositorio, change set y checks, y la página de Connected explica el panel de aprobación.