Referência
Receita: GitHub
Execute as Checagens do modelo do Holarch a partir do GitHub Actions e acompanhe as constatações como uma issue do GitHub, e deixe o Claude Code propor casos de teste para os requisitos que um branch implementa; configuração, um arquivo de workflow, um exemplo prático e solução de problemas.
Nesta página
Visão geral
Esta receita conecta um repositório do GitHub a um projeto do Holarch. Ela tem duas partes:
- Checagens do modelo no GitHub Actions (API REST): um workflow agendado executa as Checagens do modelo do Holarch nos requisitos do projeto. Ele grava as constatações no resumo da execução e mantém uma issue do GitHub atualizada com elas.
- Requisitos na revisão de código (MCP, pelo Claude Code): o Claude Code lê o branch em que você está trabalhando, encontra no Holarch os requisitos que ele implementa e propõe casos de teste que os verificam. Você revisa a proposta no Holarch antes que algo mude.
O Holarch não tem um app embutido para o GitHub. A receita usa a API REST e o MCP, para que você possa adaptar cada passo.
Pré-requisitos
- Um plano com a API e o MCP: Individual ou Team, ou a avaliação do Individual. No plano Free, uma conta com um endereço de e-mail acadêmico verificado ou em uma organização de turma ativa também os tem (Planos e limites).
- Um projeto do Holarch. O workflow apenas o lê; as propostas do Claude Code exigem o papel de editor ou proprietário.
- Um repositório do GitHub em que você possa adicionar secrets e variables do Actions, e em que o Actions possa criar issues.
- Para a parte do Claude: o Claude Code, conectado ao Holarch com acesso Ler e propor alterações (Conectar o Holarch ao Claude).
Como usá-lo
Quando e por quê
As Checagens do modelo encontram lacunas no modelo, como requisitos sem caso de teste que os verifique. Executá-las de forma agendada e acompanhar as constatações onde a equipe já trabalha mantém as lacunas visíveis entre as revisões. O Claude Code fecha o ciclo pelo outro lado: quando o código implementa um requisito, ele redige o caso de teste que o verifica.
Configurar o repositório
- No Holarch, crie um token Somente leitura limitado ao projeto: Ajustes da conta → Tokens de API → Novo token (Criar um token).
- Encontre o id do projeto:
GET /api/v1/projectslista seus projetos com oid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- No GitHub, abra Settings → Secrets and variables → Actions do repositório:
- Em Secrets, adicione
HOLARCH_TOKENcom o token. - Em Variables, adicione
HOLARCH_PROJECTcom o id do projeto.
- Em Secrets, adicione
- Em Issues → Labels, crie o rótulo
holarch. O workflow o usa para encontrar sua issue.
Executar as Checagens do modelo de forma agendada
Salve este arquivo como .github/workflows/holarch-checks.yml e faça o 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
Para executá-lo agora, abra Actions → Holarch model checks → Run workflow.
Você vê as constatações no resumo da execução, uma linha por constatação, como Requirement.10 <number> <name>: Leaf requirements with no verifying test case. A issue Holarch Model Checks findings contém a mesma lista. Quando as constatações forem corrigidas, a execução seguinte a fecha.
Como funciona:
GET /api/v1/projects/<project>/model-checks?class=Requirementexecuta as checagens com os ajustes de regras do próprio projeto e retorna as constatações:rule,heading,entity(id,number,name) e os itens relacionados. Os resultados são retornados, não armazenados.curl --fail-with-bodyfaz o passo falhar em caso de erro e imprime a mensagem do Holarch, como{"error": "…", "code": "token-invalid"}.ghejqvêm com os runners Ubuntu do GitHub.
Variações:
- Outras regras: troque
class=Requirementpor outra classe (Test Case,Asset,Custompara os seus conjuntos de regras), ou indique uma regra comrule=Requirement.10. - Qualidade dos requisitos:
GET /api/v1/projects/<project>/qualitypontua cada requisito nos nove atributos de qualidade. Liste da mesma forma os requisitos cujoscoreestá abaixo do seu limite. - Fazer a execução falhar quando houver constatações: acrescente
test "$total" -eq 0como última linha, por exemplo nas checagens de um branch de release.
Propor casos de teste para um branch com o Claude Code
Use isto antes de abrir um pull request, para que os requisitos que uma alteração implementa recebam um caso de teste que os verifique.
- Conecte o Claude Code ao Holarch uma vez:
claude mcp add --transport http holarch https://app.holarch.app/mcp
Depois digite /mcp, escolha holarch → Authenticate, entre no Holarch e clique em Permitir com Ler e propor alterações.
- No repositório, no seu branch, peça ao Claude Code, por exemplo: "Compare este branch com o main. Encontre os requisitos do projeto CubeSat do Holarch que a alteração implementa e proponha um caso de teste para cada um que não tenha caso de teste que o verifique. Nomeie o branch no resumo da proposta."
- O Claude Code lê o diff com o git. No Holarch, ele usa
search_entitieseget_entitypara encontrar os requisitos, erun_model_checkscom a regraRequirement.10para ver quais não têm caso de teste que os verifique. Ele acrescenta cada caso de teste comcreate_entitye seu relacionamento verifies, e depois envia a proposta compropose_changes.O Claude Code responde com o título da proposta e um link para revisá-la.
- No Holarch, abra ✦ IA ▾ → Revisar “<título>”…, ou a notificação sob o sino.
- Edite os nomes e as descrições se necessário e clique em Aplicar selecionados.
Os casos de teste são criados com o seu nome no histórico, e um único Desfazer reverte tudo. A próxima execução agendada do workflow não lista mais esses requisitos.
Cole o link do requisito na descrição do pull request: get_entity e a API REST o retornam como url. Ele abre o requisito para qualquer pessoa que seja membro do projeto.
Exemplo prático: a demonstração CubeSat EO-1
- Crie a demonstração com Gerenciar projetos → Arquivos de projeto ▾ → Novo projeto de demonstração e use o id dela como
HOLARCH_PROJECT. - Execute o workflow com Run workflow.
O resumo lista os requisitos que as Checagens do modelo sinalizam, por exemplo requisitos folha sem caso de teste que os verifique. A issue Holarch Model Checks findings lista os mesmos.
- Em um branch que altera o código de controle de atitude, peça ao Claude Code que proponha casos de teste para os requisitos que o branch implementa.
Os requisitos desse código são 2.1 Pointing Accuracy e 2.2 Pointing Stability. Os dois já são verificados por TC-04 Pointing Accuracy Test, então não precisam de novo caso de teste.
- Peça então que ele proponha um caso de teste para um requisito da lista da issue, e depois revise e aplique a proposta no Holarch.
- Execute o workflow novamente.
Esse requisito não é mais listado.
Dicas
- Dê ao workflow o seu próprio token somente leitura, limitado ao projeto. Revogue-o em Ajustes da conta → Tokens de API quando remover o workflow.
- O workflow agendado usa os ajustes de regras do Holarch: desative uma regra ou mude seu nível nas Checagens do modelo, e a execução seguinte acompanha.
- Um token expira na data que você escolheu. Escolha um ano ou nunca para um workflow, e anote a data.
Solução de problemas
| Mensagem ou sintoma | Causa e solução |
|---|---|
"code": "token-required" | O secret HOLARCH_TOKEN está vazio ou ausente. Adicione-o em Settings → Secrets and variables → Actions. |
"code": "token-invalid" | O token está errado, revogado ou expirado. Crie um novo e atualize o secret. |
"code": "plan-api" | O plano da conta não inclui a API e o MCP. Inicie a avaliação do Individual ou escolha um plano; o token então volta a funcionar. |
"code": "org-policy" | A organização do projeto desativou o acesso pela API. Peça a um administrador da organização. |
"code": "not-found" | HOLARCH_PROJECT não é um projeto que o token possa usar. Verifique o id e o ajuste Projetos do token. |
"code": "rate-limited" | Mais de 600 solicitações por minuto com este token. Execute o workflow com menos frequência, ou dê aos outros scripts os seus próprios tokens. |
gh issue create falha: rótulo não encontrado | Crie o rótulo holarch no repositório. |
gh responde HTTP 403 | O workflow precisa de permissions: issues: write, e os ajustes de Actions do repositório precisam permitir isso. |
| O Claude Code não oferece as ferramentas de escrita do Holarch | A conexão é somente leitura. Execute /mcp, reconecte holarch com Ler e propor alterações e inicie uma nova conversa. |