參考資料
範例做法:GitHub
從 GitHub Actions 執行 Holarch 模型檢查,並將發現事項以 GitHub 議題追蹤,並讓命令列 AI 工具為分支所實作的需求提出測試案例;設定、工作流程檔案、實作範例與疑難排解。
概觀
此範例做法將 GitHub 儲存庫連接到 Holarch 專案。它分為兩個部分:
- GitHub Actions 中的模型檢查(REST API):排程的工作流程會對專案的需求執行 Holarch 的模型檢查。它會將發現事項寫入執行的摘要,並據以持續更新一個 GitHub 議題。
- 程式碼審查中的需求(MCP,透過命令列 AI 工具):命令列 AI 工具會讀取您正在處理的分支,在 Holarch 中找出它所實作的需求,並提議驗證這些需求的測試案例。在任何內容變更之前,您會先在 Holarch 中審查提議。
Holarch 沒有內建的 GitHub 應用程式。此範例做法使用 REST API 與 MCP,因此您可以調整每個步驟。
先決條件
- 含 API 與 MCP 的方案:Individual 或 Team,或 Individual 試用。在 Free 方案上,具有已驗證學術電子郵件地址或在作用中班級組織內的帳戶也可使用(方案與限制)。
- Holarch 專案。工作流程只會讀取它;來自命令列 AI 工具的提議需要編輯者或擁有者角色。
- 您可以新增 Actions 密鑰與變數、且 Actions 可以建立議題的 GitHub 儲存庫。
- AI 應用程式部分:以讀取並提出變更存取權連接到 Holarch 的命令列 AI 工具(將 Holarch 連接到 AI 應用程式)。
使用方式
使用時機與原因
模型檢查會找出模型中的缺口,例如沒有驗證用測試案例的需求。依排程執行它們,並在團隊已在使用的地方追蹤發現事項,可讓缺口在審查之間保持可見。命令列 AI 工具則從另一端補上:當程式碼實作某個需求時,它會草擬驗證該需求的測試案例。
設定儲存庫
- 在 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。工作流程會用它來找到自己的議題。
依排程執行模型檢查
將此檔案儲存為 .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。
您會在執行的摘要中看到發現事項,每個發現事項一行,例如 Requirement.10 <number> <name>: Leaf requirements with no verifying test case。議題 Holarch Model Checks findings 包含相同的清單。當發現事項修正後,下一次執行會將其關閉。
運作方式:
GET /api/v1/projects/<project>/model-checks?class=Requirement會以專案自己的規則設定執行檢查,並傳回發現事項:rule、heading、entity(id、number、name)以及相關項目。結果只會傳回,不會儲存。curl --fail-with-body會在發生錯誤時使步驟失敗,並輸出 Holarch 的訊息,例如{"error": "…", "code": "token-invalid"}。- GitHub 的 Ubuntu 執行器已內含
gh與jq。
變化做法:
- 其他規則:將
class=Requirement改為其他類別(Test Case、Asset,您的規則集則為Custom),或以rule=Requirement.10指定單一規則。 - 需求品質:
GET /api/v1/projects/<project>/quality會依九個品質屬性為每個需求評分。以相同方式列出score低於您門檻的需求。 - 有發現事項時使執行失敗:在最後一行加入
test "$total" -eq 0,例如用於發行分支的檢查。
以命令列 AI 工具為分支提議測試案例
請在開啟提取要求之前使用此方式,讓變更所實作的需求取得驗證用的測試案例。
- 將命令列 AI 工具連接到 Holarch 一次:
claude mcp add --transport http holarch https://app.holarch.app/mcp
然後輸入 /mcp,選擇 holarch → 驗證身分,登入 Holarch 並以讀取並提出變更按一下允許。
- 在儲存庫中,於您的分支上詢問命令列 AI 工具,例如:「將此分支與 main 比較。找出 Holarch CubeSat 專案中此變更所實作的需求,並為每個沒有驗證用測試案例的需求提議一個測試案例。在提議摘要中寫出分支名稱。」
- 命令列 AI 工具會以 git 讀取差異。在 Holarch 中,它使用
search_entities與get_entity找出需求,並以規則Requirement.10執行run_model_checks,查看哪些需求沒有驗證用的測試案例。它會以create_entity新增每個測試案例及其 verifies 關係,然後以propose_changes送出提議。命令列 AI 工具會回覆提議的標題以及審查連結。
- 在 Holarch 中,開啟 ✦ AI ▾ → 審查「<title>」…,或鈴鐺下的通知。
- 視需要編輯名稱與描述,然後按一下套用所選項。
測試案例會被建立,並在歷程記錄中記下您的名字,一次復原即可全部撤回。下一次排程的工作流程執行就不會再列出這些需求。
將需求的連結貼到提取要求的描述中:get_entity 與 REST API 會以 url 傳回它。任何專案成員都能透過它開啟該需求。
實例演練:CubeSat EO-1 示範
- 以管理專案 → 專案檔案 ▾ → 新增示範專案建立示範,並以其 id 作為
HOLARCH_PROJECT。 - 以 Run workflow 執行工作流程。
摘要會列出模型檢查標示的需求,例如沒有驗證用測試案例的末端需求。議題 Holarch Model Checks findings 會列出相同的內容。
- 在變更姿態控制程式碼的分支上,請命令列 AI 工具為該分支所實作的需求提議測試案例。
該程式碼對應的需求為 2.1 Pointing Accuracy 與 2.2 Pointing Stability。兩者都已由 TC-04 Pointing Accuracy Test 驗證,因此不需要新的測試案例。
- 改為請它為議題清單中的某個需求提議測試案例,然後在 Holarch 中審查並套用提議。
- 再次執行工作流程。
該需求不再列出。
提示
- 為工作流程提供專屬的唯讀權杖,並限制在該專案。移除工作流程時,請在帳戶設定 → API 權杖下將其撤銷。
- 排程的工作流程使用 Holarch 的規則設定:在模型檢查中關閉某條規則或變更其層級,下一次執行就會依循。
- 權杖會在您選擇的日期到期。工作流程請選擇一年或永不到期,並記下日期。
疑難排解
| 訊息或症狀 | 原因與修正 |
|---|---|
"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" | 此權杖每分鐘超過 600 個請求。請降低工作流程的執行頻率,或為其他指令碼提供各自的權杖。 |
gh issue create 失敗:找不到標籤 | 在儲存庫中建立標籤 holarch。 |
gh 回應 HTTP 403 | 工作流程需要 permissions: issues: write,且儲存庫的 Actions 設定必須允許。 |
| 命令列 AI 工具未提供 Holarch 寫入工具 | 連線為唯讀。請執行 /mcp,以讀取並提出變更重新連接 holarch,然後開始新的對話。 |