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.
On this page
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
- In Holarch, create a Read only token limited to the project: Account Settings → API tokens → New token (Create a token).
- Find the project id:
GET /api/v1/projectslists your projects with theirid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- In GitHub, open the repository's Settings → Secrets and variables → Actions:
- Under Secrets, add
HOLARCH_TOKENwith the token. - Under Variables, add
HOLARCH_PROJECTwith the project id.
- Under Secrets, add
- 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=Requirementruns 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-bodyfails the step on an error and prints Holarch's message, such as{"error": "…", "code": "token-invalid"}.ghandjqcome with GitHub's Ubuntu runners.
Variations:
- Other rules: change
class=Requirementto another class (Test Case,Asset,Customfor your rule sets), or name one rule withrule=Requirement.10. - Requirement quality:
GET /api/v1/projects/<project>/qualityscores every requirement on the nine quality attributes. List the requirements whosescoreis below your threshold the same way. - Fail the run on findings: add
test "$total" -eq 0as 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.
- 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.
- 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."
- Claude Code reads the diff with git. In Holarch it uses
search_entitiesandget_entityto find the requirements, andrun_model_checkswith the ruleRequirement.10to see which have no verifying test case. It adds each test case withcreate_entityand its verifies relationship, then sends the proposal withpropose_changes.Claude Code answers with the proposal's title and a link to review it.
- In Holarch, open ✦ AI ▾ → Review “<title>”…, or the notification under the bell.
- 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
- Create the demo with Manage Projects → Project Files ▾ → New Demo Project, and use its id as
HOLARCH_PROJECT. - 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.
- 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.
- Ask it to propose a test case for a requirement in the issue's list instead, then review and apply the proposal in Holarch.
- 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 symptom | Cause 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 found | Create the label holarch in the repository. |
gh answers HTTP 403 | The workflow needs permissions: issues: write, and the repository's Actions settings must allow it. |
| Claude Code does not offer the Holarch write tools | The connection is read only. Run /mcp, reconnect holarch with Read and propose changes, then start a new conversation. |