Holarch

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.

Como usá-lo →

Nesta página
  1. Visão geral
  2. Pré-requisitos
  3. Como usá-lo
    1. Quando e por quê
    2. Configurar o repositório
    3. Executar as Checagens do modelo de forma agendada
    4. Propor casos de teste para um branch com o Claude Code
    5. Exemplo prático: a demonstração CubeSat EO-1
    6. Dicas
  4. Solução de problemas
  5. Páginas relacionadas

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

  1. No Holarch, crie um token Somente leitura limitado ao projeto: Ajustes da conta → Tokens de API → Novo token (Criar um token).
  2. Encontre o id do projeto: GET /api/v1/projects lista seus projetos com o id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. No GitHub, abra Settings → Secrets and variables → Actions do repositório:
    • Em Secrets, adicione HOLARCH_TOKEN com o token.
    • Em Variables, adicione HOLARCH_PROJECT com o id do projeto.
  2. 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=Requirement executa 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-body faz o passo falhar em caso de erro e imprime a mensagem do Holarch, como {"error": "…", "code": "token-invalid"}.
  • gh e jq vêm com os runners Ubuntu do GitHub.

Variações:

  • Outras regras: troque class=Requirement por outra classe (Test Case, Asset, Custom para os seus conjuntos de regras), ou indique uma regra com rule=Requirement.10.
  • Qualidade dos requisitos: GET /api/v1/projects/<project>/quality pontua cada requisito nos nove atributos de qualidade. Liste da mesma forma os requisitos cujo score está abaixo do seu limite.
  • Fazer a execução falhar quando houver constatações: acrescente test "$total" -eq 0 como ú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.

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

  1. 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."
  2. O Claude Code lê o diff com o git. No Holarch, ele usa search_entities e get_entity para encontrar os requisitos, e run_model_checks com a regra Requirement.10 para ver quais não têm caso de teste que os verifique. Ele acrescenta cada caso de teste com create_entity e seu relacionamento verifies, e depois envia a proposta com propose_changes.

    O Claude Code responde com o título da proposta e um link para revisá-la.

  3. No Holarch, abra ✦ IA ▾ → Revisar “<título>”…, ou a notificação sob o sino.
  4. 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

  1. Crie a demonstração com Gerenciar projetos → Arquivos de projeto ▾ → Novo projeto de demonstração e use o id dela como HOLARCH_PROJECT.
  2. 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.

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

  4. 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.
  5. 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 sintomaCausa 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 encontradoCrie o rótulo holarch no repositório.
gh responde HTTP 403O 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 HolarchA conexão é somente leitura. Execute /mcp, reconecte holarch com Ler e propor alterações e inicie uma nova conversa.