Holarch

Reference

Recipe: GitHub

Run Holarch Model Checks from GitHub Actions and track the findings as a GitHub issue, and let Claude Code propose test cases for the requirements a branch implements; setup, a workflow file, a worked example and troubleshooting.

How to use it →

On this page
  1. Overview
  2. Prerequisites
  3. How to use it
    1. When and why
    2. Set up the repository
    3. Run Model Checks on a schedule
    4. Propose test cases for a branch with Claude Code
    5. Worked example: the CubeSat EO-1 demo
    6. Tips
  4. Troubleshooting
  5. Related pages

Overview

This recipe connects a GitHub repository to a Holarch project. It has two parts:

  • Model Checks in GitHub Actions (REST API): a scheduled workflow runs Holarch's Model Checks on the project's requirements. It writes the findings to the run's summary and keeps one GitHub issue up to date with them.
  • Requirements in code review (MCP, through Claude Code): Claude Code reads the branch you are working on, finds the requirements it implements in Holarch, and proposes test cases that verify them. You review the proposal in Holarch before anything changes.

Holarch has no built-in GitHub app. The recipe uses the REST API and MCP, so you can adapt every step.

Prerequisites

  • A plan with the API and MCP: Individual or Team, or the Individual trial. On the Free plan, an account with a verified academic email address or in an active class organization also has them (Plans and limits).
  • A Holarch project. The workflow only reads it; proposals from Claude Code need the editor or owner role.
  • A GitHub repository where you can add Actions secrets and variables, and where Actions can create issues.
  • For the Claude part: Claude Code, connected to Holarch with Read and propose changes access (Connect Holarch to Claude).

How to use it

When and why

Model Checks find gaps in the model, such as requirements without a verifying test case. Running them on a schedule and tracking the findings where the team already works keeps the gaps visible between reviews. Claude Code closes the loop from the other side: when code implements a requirement, it drafts the test case that verifies it.

Set up the repository

  1. In Holarch, create a Read only token limited to the project: Account Settings → API tokens → New token (Create a token).
  2. Find the project id: GET /api/v1/projects lists your projects with their id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. In GitHub, open the repository's Settings → Secrets and variables → Actions:
    • Under Secrets, add HOLARCH_TOKEN with the token.
    • Under Variables, add HOLARCH_PROJECT with the project id.
  2. Under Issues → Labels, create the label holarch. The workflow uses it to find its issue.

Run Model Checks on a schedule

Save this file as .github/workflows/holarch-checks.yml and commit it.

# 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

To run it now, open Actions → Holarch model checks → Run workflow.

You see the findings in the run's summary, one line per finding, such as Requirement.10 <number> <name>: Leaf requirements with no verifying test case. The issue Holarch Model Checks findings holds the same list. When the findings are fixed, the next run closes it.

How it works:

  • GET /api/v1/projects/<project>/model-checks?class=Requirement runs the checks with the project's own rule settings and returns the findings: rule, heading, entity (id, number, name) and the related items. Results are returned, not stored.
  • curl --fail-with-body fails the step on an error and prints Holarch's message, such as {"error": "…", "code": "token-invalid"}.
  • gh and jq come with GitHub's Ubuntu runners.

Variations:

  • Other rules: change class=Requirement to another class (Test Case, Asset, Custom for your rule sets), or name one rule with rule=Requirement.10.
  • Requirement quality: GET /api/v1/projects/<project>/quality scores every requirement on the nine quality attributes. List the requirements whose score is below your threshold the same way.
  • Fail the run on findings: add test "$total" -eq 0 as the last line, for example in a release branch's checks.

Propose test cases for a branch with Claude Code

Use this before you open a pull request, so the requirements a change implements get a verifying test case.

  1. Connect Claude Code to Holarch once:
claude mcp add --transport http holarch https://app.holarch.app/mcp

Then type /mcp, choose holarch → Authenticate, sign in to Holarch and click Allow with Read and propose changes.

  1. In the repository, on your branch, ask Claude Code, for example: "Compare this branch with main. Find the requirements in the Holarch CubeSat project that the change implements, and propose a test case for each one that has no verifying test case. Name the branch in the proposal summary."
  2. Claude Code reads the diff with git. In Holarch it uses search_entities and get_entity to find the requirements, and run_model_checks with the rule Requirement.10 to see which have no verifying test case. It adds each test case with create_entity and its verifies relationship, then sends the proposal with propose_changes.

    Claude Code answers with the proposal's title and a link to review it.

  3. In Holarch, open ✦ AI ▾ → Review “<title>”…, or the notification under the bell.
  4. Edit the names and descriptions if needed, then click Apply Selected.

    The test cases are created with your name in the history, and a single Undo takes it all back. The next scheduled workflow run no longer lists those requirements.

Paste the requirement's link into the pull request description: get_entity and the REST API return it as url. It opens the requirement for anyone who is a member of the project.

Worked example: the CubeSat EO-1 demo

  1. Create the demo with Manage Projects → Project Files ▾ → New Demo Project, and use its id as HOLARCH_PROJECT.
  2. Run the workflow with Run workflow.

    The summary lists the requirements Model Checks flag, for example leaf requirements with no verifying test case. The issue Holarch Model Checks findings lists the same.

  3. On a branch that changes the attitude control code, ask Claude Code to propose test cases for the requirements the branch implements.

    The requirements for that code are 2.1 Pointing Accuracy and 2.2 Pointing Stability. Both are already verified by TC-04 Pointing Accuracy Test, so they need no new test case.

  4. Ask it to propose a test case for a requirement in the issue's list instead, then review and apply the proposal in Holarch.
  5. Run the workflow again.

    That requirement is no longer listed.

Tips

  • Give the workflow its own read-only token, limited to the project. Revoke it under Account Settings → API tokens when you remove the workflow.
  • The scheduled workflow uses Holarch's rule settings: turn a rule off or change its level in Model Checks, and the next run follows.
  • A token expires on the date you chose. Choose one year or never for a workflow, and note the date.

Troubleshooting

Message or symptomCause and fix
"code": "token-required"The HOLARCH_TOKEN secret is empty or missing. Add it under Settings → Secrets and variables → Actions.
"code": "token-invalid"The token is wrong, revoked or expired. Create a new one and update the secret.
"code": "plan-api"The account's plan does not include the API and MCP. Start the Individual trial or choose a plan; the token then works again.
"code": "org-policy"The project's organization turned API access off. Ask an organization admin.
"code": "not-found"HOLARCH_PROJECT is not a project the token can use. Check the id, and the token's Projects setting.
"code": "rate-limited"More than 600 requests a minute with this token. Run the workflow less often, or give other scripts their own tokens.
gh issue create fails: label not foundCreate the label holarch in the repository.
gh answers HTTP 403The workflow needs permissions: issues: write, and the repository's Actions settings must allow it.
Claude Code does not offer the Holarch write toolsThe connection is read only. Run /mcp, reconnect holarch with Read and propose changes, then start a new conversation.