リファレンス
レシピ:GitHub
GitHub Actions から Holarch のモデルチェックを実行して指摘事項を GitHub の issue として追跡し、ブランチが実装する要求に対するテストケースを Claude Code に提案させます。設定、ワークフローファイル、具体例、トラブルシューティングを説明します。
このページの内容
概要
このレシピは、GitHub リポジトリを Holarch プロジェクトに接続します。2 つの部分があります:
- GitHub Actions でのモデルチェック(REST API):スケジュールされたワークフローが、プロジェクトの要求に対して Holarch のモデルチェックを実行します。指摘事項を実行の概要に書き込み、1 つの GitHub の issue をそれで最新の状態に保ちます。
- コードレビューでの要求(MCP、Claude Code を通じて):Claude Code が作業中のブランチを読み、それが実装している要求を Holarch で見つけ、それを検証するテストケースを提案します。何かが変わる前に、Holarch で提案をレビューします。
Holarch には組み込みの GitHub アプリはありません。このレシピは REST API と MCP を使うので、どの手順も調整できます。
前提条件
- API と MCP を含むプラン:Individual または Team、または Individual トライアル。Free プランでも、確認済みのアカデミックメールアドレスがあるアカウント、または有効なクラス組織内のアカウントは利用できます(プランと上限)。
- Holarch プロジェクト。ワークフローはそれを読み取るだけです。Claude Code からの提案には編集者またはオーナーのロールが必要です。
- Actions のシークレットと変数を追加でき、Actions が issue を作成できる GitHub リポジトリ。
- Claude の部分には:読み取りと変更の提案のアクセスで Holarch に接続した Claude Code(Holarch を Claude に接続する)。
使い方
使う場面と理由
モデルチェックは、検証するテストケースのない要求など、モデル内のギャップを見つけます。スケジュールに従って実行し、チームがすでに作業している場所で指摘事項を追跡すると、レビューの間もギャップが見える状態に保たれます。Claude Code は反対側からループを閉じます:コードが要求を実装すると、それを検証するテストケースを下書きします。
リポジトリを設定する
- Holarch で、プロジェクトに限定した読み取り専用のトークンを作成します:アカウント設定 → API トークン → 新しいトークン(トークンを作成する)。
- プロジェクト ID を調べます:
GET /api/v1/projectsが、プロジェクトをそのidとともに一覧表示します。
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- GitHub で、リポジトリの Settings → Secrets and variables → Actions を開きます:
- Secrets で、トークンを値とする
HOLARCH_TOKENを追加します。 - Variables で、プロジェクト ID を値とする
HOLARCH_PROJECTを追加します。
- Secrets で、トークンを値とする
- Issues → Labels で、ラベル
holarchを作成します。ワークフローはこれを使って自分の issue を見つけます。
スケジュールに従ってモデルチェックを実行する
このファイルを .github/workflows/holarch-checks.yml として保存し、コミットします。
# 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
今すぐ実行するには、Actions → Holarch model checks → Run workflow を開きます。
実行の概要に、指摘事項が 1 件につき 1 行で表示されます。たとえば Requirement.10 <number> <name>: Leaf requirements with no verifying test case です。issue Holarch Model Checks findings にも同じ一覧が入ります。指摘事項が修正されると、次の実行でその issue がクローズされます。
仕組み:
GET /api/v1/projects/<project>/model-checks?class=Requirementは、プロジェクト独自のルール設定でチェックを実行し、指摘事項を返します:rule、heading、entity(id、number、name)、および関連する項目です。結果は返されるだけで、保存されません。curl --fail-with-bodyは、エラー時にステップを失敗させ、{"error": "…", "code": "token-invalid"}のような Holarch のメッセージを出力します。ghとjqは GitHub の Ubuntu ランナーに含まれています。
バリエーション:
- その他のルール:
class=Requirementを別のクラス(Test Case、Asset、独自のルールセットにはCustom)に変えるか、rule=Requirement.10で 1 つのルールを指定します。 - 要求の品質:
GET /api/v1/projects/<project>/qualityは、すべての要求を 9 つの品質属性で採点します。scoreがしきい値を下回る要求も、同じ方法で一覧表示します。 - 指摘事項があれば実行を失敗させる:最後の行として
test "$total" -eq 0を追加します。たとえばリリースブランチのチェックで使います。
Claude Code でブランチのテストケースを提案する
プルリクエストを開く前にこれを使うと、変更が実装する要求に検証するテストケースが付きます。
- Claude Code を Holarch に一度だけ接続します:
claude mcp add --transport http holarch https://app.holarch.app/mcp
次に /mcp と入力し、holarch → 認証を選んで Holarch にサインインし、読み取りと変更の提案で許可をクリックします。
- リポジトリの自分のブランチで、たとえば次のように Claude Code に依頼します:「このブランチを main と比較してください。変更が実装している Holarch の CubeSat プロジェクトの要求を見つけ、検証するテストケースのないものそれぞれにテストケースを提案してください。提案の要約にブランチ名を記載してください。」
- Claude Code は git で差分を読みます。Holarch では、
search_entitiesとget_entityを使って要求を見つけ、ルールRequirement.10を指定したrun_model_checksで、どれに検証するテストケースがないかを確認します。create_entityとその verifies 関係で各テストケースを追加し、propose_changesで提案を送信します。Claude Code は、提案のタイトルとレビュー用のリンクで答えます。
- Holarch で ✦ AI ▾ → Review “<title>”…、またはベルの下の通知を開きます。
- 必要に応じて名前と説明を編集してから、選択した項目を適用をクリックします。
テストケースは、履歴にあなたの名前を付けて作成されます。1 回の元に戻すですべて取り消せます。次にスケジュールされたワークフローの実行では、それらの要求は表示されなくなります。
要求のリンクをプルリクエストの説明に貼り付けます:get_entity と REST API はそれを url として返します。プロジェクトのメンバーであれば誰でも、そのリンクで要求を開けます。
実例:CubeSat EO-1 のデモ
- プロジェクトを管理 → プロジェクトファイル ▾ → 新しいデモプロジェクトでデモを作成し、その ID を
HOLARCH_PROJECTとして使います。 - Run workflow でワークフローを実行します。
概要には、モデルチェックが指摘した要求が一覧表示されます。たとえば、検証するテストケースのない末端の要求です。issue Holarch Model Checks findings にも同じものが一覧表示されます。
- 姿勢制御のコードを変更するブランチで、そのブランチが実装する要求のテストケースを提案するよう Claude Code に依頼します。
そのコードの要求は 2.1 Pointing Accuracy と 2.2 Pointing Stability です。どちらもすでに TC-04 Pointing Accuracy Test で検証されているので、新しいテストケースは必要ありません。
- 代わりに issue の一覧にある要求のテストケースを提案するよう依頼し、Holarch で提案をレビューして適用します。
- ワークフローをもう一度実行します。
その要求は表示されなくなります。
ヒント
- ワークフローには、プロジェクトに限定した専用の読み取り専用トークンを与えます。ワークフローを除去するときは、アカウント設定 → API トークンでそのトークンを失効させます。
- スケジュールされたワークフローは Holarch のルール設定を使います:モデルチェックでルールをオフにするかレベルを変更すると、次の実行はそれに従います。
- トークンは選択した日に期限切れになります。ワークフローには 1 年または無期限を選び、日付を控えておきます。
トラブルシューティング
| メッセージまたは症状 | 原因と対処 |
|---|---|
"code": "token-required" | シークレット HOLARCH_TOKEN が空か、存在しません。Settings → Secrets and variables → Actions で追加します。 |
"code": "token-invalid" | トークンが間違っている、失効している、または期限切れです。新しいトークンを作成し、シークレットを更新します。 |
"code": "plan-api" | アカウントのプランに API と MCP が含まれていません。Individual トライアルを開始するかプランを選択すると、トークンは再び機能します。 |
"code": "org-policy" | プロジェクトの組織が API アクセスをオフにしています。組織管理者に依頼します。 |
"code": "not-found" | HOLARCH_PROJECT が、トークンの使えるプロジェクトではありません。ID と、トークンのプロジェクトの設定を確認します。 |
"code": "rate-limited" | このトークンで 1 分間に 600 リクエストを超えています。ワークフローの実行頻度を下げるか、他のスクリプトに専用のトークンを与えます。 |
gh issue create が失敗する:label not found | リポジトリにラベル holarch を作成します。 |
gh が HTTP 403 を返す | ワークフローには permissions: issues: write が必要で、リポジトリの Actions の設定でそれが許可されている必要があります。 |
| Claude Code が Holarch の書き込みツールを提示しない | 接続が読み取り専用です。/mcp を実行し、読み取りと変更の提案で holarch を再接続してから、新しい会話を始めます。 |