Referencia
Receta: GitHub
Ejecute las comprobaciones del modelo de Holarch desde GitHub Actions y siga los hallazgos como una incidencia de GitHub, y permita que Claude Code proponga casos de prueba para los requisitos que implementa una rama; configuración, un archivo de flujo de trabajo, un ejemplo práctico y solución de problemas.
En esta página
Resumen
Esta receta conecta un repositorio de GitHub con un proyecto de Holarch. Tiene dos partes:
- Comprobaciones del modelo en GitHub Actions (API REST): un flujo de trabajo programado ejecuta las comprobaciones del modelo de Holarch sobre los requisitos del proyecto. Escribe los hallazgos en el resumen de la ejecución y mantiene una incidencia de GitHub actualizada con ellos.
- Requisitos en la revisión de código (MCP, mediante Claude Code): Claude Code lee la rama en la que trabaja, encuentra en Holarch los requisitos que implementa y propone casos de prueba que los verifican. Usted revisa la propuesta en Holarch antes de que cambie nada.
Holarch no tiene una aplicación de GitHub integrada. La receta usa la API REST y MCP, por lo que puede adaptar cada paso.
Requisitos previos
- Un plan con la API y MCP: Individual o Team, o la prueba de Individual. En el plan Free, una cuenta con una dirección de correo académica verificada o en una organización de clase activa también los tiene (Planes y límites).
- Un proyecto de Holarch. El flujo de trabajo solo lo lee; las propuestas de Claude Code necesitan el rol de editor o de propietario.
- Un repositorio de GitHub en el que pueda añadir secretos y variables de Actions, y en el que Actions pueda crear incidencias.
- Para la parte de Claude: Claude Code, conectado a Holarch con el acceso Leer y proponer cambios (Conectar Holarch a Claude).
Cómo usarlo
Cuándo y por qué
Las comprobaciones del modelo encuentran carencias en el modelo, como requisitos sin un caso de prueba que los verifique. Ejecutarlas de forma programada y hacer el seguimiento de los hallazgos donde el equipo ya trabaja mantiene visibles las carencias entre revisiones. Claude Code cierra el ciclo desde el otro lado: cuando el código implementa un requisito, redacta el caso de prueba que lo verifica.
Configurar el repositorio
- En Holarch, cree un token de Solo lectura limitado al proyecto: Ajustes de la cuenta → Tokens de API → Nuevo token (Crear un token).
- Busque el id del proyecto:
GET /api/v1/projectsenumera sus proyectos con suid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- En GitHub, abra Settings → Secrets and variables → Actions del repositorio:
- En Secrets, añada
HOLARCH_TOKENcon el token. - En Variables, añada
HOLARCH_PROJECTcon el id del proyecto.
- En Secrets, añada
- En Issues → Labels, cree la etiqueta
holarch. El flujo de trabajo la usa para encontrar su incidencia.
Ejecutar las comprobaciones del modelo de forma programada
Guarde este archivo como .github/workflows/holarch-checks.yml y confírmelo.
# 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
Para ejecutarlo ahora, abra Actions → Holarch model checks → Run workflow.
Verá los hallazgos en el resumen de la ejecución, una línea por hallazgo, como Requirement.10 <number> <name>: Leaf requirements with no verifying test case. La incidencia Holarch Model Checks findings contiene la misma lista. Cuando los hallazgos se corrigen, la siguiente ejecución la cierra.
Cómo funciona:
GET /api/v1/projects/<project>/model-checks?class=Requirementejecuta las comprobaciones con los ajustes de reglas propios del proyecto y devuelve los hallazgos:rule,heading,entity(id,number,name) y los elementos relacionados. Los resultados se devuelven, no se guardan.curl --fail-with-bodyhace fallar el paso ante un error e imprime el mensaje de Holarch, como{"error": "…", "code": "token-invalid"}.ghyjqvienen con los ejecutores Ubuntu de GitHub.
Variantes:
- Otras reglas: cambie
class=Requirementpor otra clase (Test Case,Asset,Custompara sus conjuntos de reglas), o nombre una regla conrule=Requirement.10. - Calidad de los requisitos:
GET /api/v1/projects/<project>/qualitypuntúa cada requisito según los nueve atributos de calidad. Enumere de la misma forma los requisitos cuyoscoreestá por debajo de su umbral. - Hacer fallar la ejecución si hay hallazgos: añada
test "$total" -eq 0como última línea, por ejemplo en las comprobaciones de una rama de publicación.
Proponer casos de prueba para una rama con Claude Code
Use esto antes de abrir una pull request, para que los requisitos que implementa un cambio reciban un caso de prueba que los verifique.
- Conecte Claude Code a Holarch una vez:
claude mcp add --transport http holarch https://app.holarch.app/mcp
Después escriba /mcp, elija holarch → Authenticate, inicie sesión en Holarch y haga clic en Permitir con Leer y proponer cambios.
- En el repositorio, en su rama, pida a Claude Code, por ejemplo: «Compara esta rama con main. Busca los requisitos del proyecto CubeSat de Holarch que implementa el cambio y propón un caso de prueba para cada uno que no tenga un caso de prueba que lo verifique. Nombra la rama en el resumen de la propuesta.»
- Claude Code lee las diferencias con git. En Holarch usa
search_entitiesyget_entitypara encontrar los requisitos, yrun_model_checkscon la reglaRequirement.10para ver cuáles no tienen un caso de prueba que los verifique. Añade cada caso de prueba concreate_entityy su relación verifies, y después envía la propuesta conpropose_changes.Claude Code responde con el título de la propuesta y un enlace para revisarla.
- En Holarch, abra ✦ IA ▾ → Revisar «<título>»…, o la notificación de la campana.
- Edite los nombres y las descripciones si hace falta y haga clic en Aplicar seleccionados.
Los casos de prueba se crean con su nombre en el historial, y un solo Deshacer lo revierte todo. La siguiente ejecución programada del flujo de trabajo ya no enumera esos requisitos.
Pegue el enlace del requisito en la descripción de la pull request: get_entity y la API REST lo devuelven como url. Abre el requisito para cualquier miembro del proyecto.
Ejemplo práctico: la demostración CubeSat EO-1
- Cree la demo con Gestionar proyectos → Archivos de proyecto ▾ → Nuevo proyecto de demostración y use su id como
HOLARCH_PROJECT. - Ejecute el flujo de trabajo con Run workflow.
El resumen enumera los requisitos que marcan las comprobaciones del modelo, por ejemplo requisitos hoja sin un caso de prueba que los verifique. La incidencia Holarch Model Checks findings enumera lo mismo.
- En una rama que cambia el código de control de actitud, pida a Claude Code que proponga casos de prueba para los requisitos que implementa la rama.
Los requisitos de ese código son 2.1 Pointing Accuracy y 2.2 Pointing Stability. Ambos ya están verificados por TC-04 Pointing Accuracy Test, por lo que no necesitan un caso de prueba nuevo.
- Pídale en su lugar que proponga un caso de prueba para un requisito de la lista de la incidencia, y después revise y aplique la propuesta en Holarch.
- Ejecute el flujo de trabajo de nuevo.
Ese requisito ya no aparece en la lista.
Consejos
- Dé al flujo de trabajo su propio token de solo lectura, limitado al proyecto. Revóquelo en Ajustes de la cuenta → Tokens de API cuando quite el flujo de trabajo.
- El flujo de trabajo programado usa los ajustes de reglas de Holarch: desactive una regla o cambie su nivel en las comprobaciones del modelo, y la siguiente ejecución lo sigue.
- Un token caduca en la fecha que eligió. Elija un año o nunca para un flujo de trabajo, y anote la fecha.
Solución de problemas
| Mensaje o síntoma | Causa y solución |
|---|---|
"code": "token-required" | El secreto HOLARCH_TOKEN está vacío o falta. Añádalo en Settings → Secrets and variables → Actions. |
"code": "token-invalid" | El token es incorrecto, está revocado o caducado. Cree uno nuevo y actualice el secreto. |
"code": "plan-api" | El plan de la cuenta no incluye la API ni MCP. Inicie la prueba de Individual o elija un plan; el token vuelve entonces a funcionar. |
"code": "org-policy" | La organización del proyecto desactivó el acceso por API. Pregunte a un administrador de la organización. |
"code": "not-found" | HOLARCH_PROJECT no es un proyecto que el token pueda usar. Compruebe el id y el ajuste Proyectos del token. |
"code": "rate-limited" | Más de 600 solicitudes por minuto con este token. Ejecute el flujo de trabajo con menos frecuencia, o dé a los demás scripts sus propios tokens. |
gh issue create falla: no se encuentra la etiqueta | Cree la etiqueta holarch en el repositorio. |
gh responde HTTP 403 | El flujo de trabajo necesita permissions: issues: write, y los ajustes de Actions del repositorio deben permitirlo. |
| Claude Code no ofrece las herramientas de escritura de Holarch | La conexión es de solo lectura. Ejecute /mcp, vuelva a conectar holarch con Leer y proponer cambios y después inicie una conversación nueva. |