Довідник
Рецепт: GitHub
Запускайте перевірки моделі Holarch з GitHub Actions, відстежуйте зауваження як issue на GitHub і дозвольте Claude Code пропонувати тестові випадки для вимог, які реалізує гілка; налаштування, файл робочого процесу, розібраний приклад і усунення несправностей.
На цій сторінці
Огляд
Цей рецепт з’єднує репозиторій GitHub із проєктом Holarch. Він має дві частини:
- Перевірки моделі в GitHub Actions (REST API): запланований робочий процес запускає перевірки моделі Holarch для вимог проєкту. Він записує зауваження в підсумок запуску й підтримує актуальною одну задачу GitHub з ними.
- Вимоги в рецензуванні коду (MCP, через Claude Code): Claude Code читає гілку, з якою ви працюєте, знаходить у Holarch вимоги, які вона реалізує, і пропонує тестові випадки, що їх верифікують. Ви переглядаєте пропозицію в Holarch, перш ніж щось зміниться.
Holarch не має вбудованого застосунку GitHub. Рецепт використовує REST API і MCP, тож кожен крок можна адаптувати.
Передумови
- Тариф з API і MCP: Individual або Team чи пробний період Individual. У тарифі Free вони також є в облікового запису з підтвердженою академічною адресою електронної пошти або в активній навчальній організації (Тарифи та обмеження).
- Проєкт Holarch. Робочий процес лише читає його; пропозиції від Claude Code потребують ролі редактора чи власника.
- Репозиторій GitHub, де ви можете додавати секрети й змінні Actions і де Actions можуть створювати задачі.
- Для частини з Claude: Claude Code, під’єднаний до Holarch з доступом Читати й пропонувати зміни (Під’єднати 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 додайте
HOLARCH_PROJECTз id проєкту.
- У розділі 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"}.ghіjqвходять до раннерів Ubuntu від GitHub.
Варіанти:
- Інші правила: змініть
class=Requirementна інший клас (Test Case,Asset,Customдля ваших наборів правил) або вкажіть одне правило черезrule=Requirement.10. - Якість вимог:
GET /api/v1/projects/<project>/qualityоцінює кожну вимогу за дев’ятьма атрибутами якості. Так само перелічіть вимоги,scoreяких нижчий за ваш поріг. - Завершувати запуск помилкою за наявності зауважень: додайте
test "$total" -eq 0останнім рядком, наприклад у перевірках гілки випуску.
Пропонування тестових випадків для гілки за допомогою Claude Code
Використовуйте це перед відкриттям pull request, щоб вимоги, які реалізує зміна, отримали тестовий випадок, що їх верифікує.
- Один раз під’єднайте Claude Code до Holarch:
claude mcp add --transport http holarch https://app.holarch.app/mcp
Потім введіть /mcp, виберіть holarch → Authenticate, увійдіть у Holarch і натисніть Дозволити з Читати й пропонувати зміни.
- У репозиторії, у своїй гілці, попросіть Claude Code, наприклад: "Порівняй цю гілку з main. Знайди вимоги в проєкті Holarch CubeSat, які реалізує зміна, і запропонуй тестовий випадок для кожної, що не має тестового випадку, який її верифікує. Назви гілку в підсумку пропозиції."
- Claude Code читає diff за допомогою git. У Holarch він використовує
search_entitiesіget_entity, щоб знайти вимоги, іrun_model_checksіз правиломRequirement.10, щоб побачити, які не мають тестового випадку, що їх верифікує. Він додає кожен тестовий випадок черезcreate_entityз його зв’язком verifies, потім надсилає пропозицію черезpropose_changes.Claude Code відповідає назвою пропозиції й посиланням для її перегляду.
- У Holarch відкрийте ✦ ШІ ▾ → Переглянути “<title>”… або сповіщення під дзвіночком.
- За потреби відредагуйте назви й описи, потім натисніть Застосувати вибране.
Тестові випадки створюються з вашим іменем в історії, і одне натискання “Відмінити” повертає все назад. Наступний запланований запуск робочого процесу більше не наводить ці вимоги.
Вставте посилання на вимогу в опис pull request: get_entity і REST API повертають його як url. Воно відкриває вимогу для будь-кого, хто є учасником проєкту.
Робочий приклад: демопроєкт CubeSat EO-1
- Створіть демо через Керування проєктами → Файли проєктів ▾ → Новий демопроєкт і використайте його id як
HOLARCH_PROJECT. - Запустіть робочий процес через Run workflow.
Підсумок перелічує вимоги, які позначають перевірки моделі, наприклад листкові вимоги без тестового випадку, що їх верифікує. Задача Holarch Model Checks findings перелічує те саме.
- У гілці, що змінює код керування орієнтацією, попросіть Claude Code запропонувати тестові випадки для вимог, які реалізує гілка.
Вимоги до цього коду — 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 репозиторію мають це дозволяти. |
| Claude Code не пропонує інструментів запису Holarch | З’єднання лише для читання. Виконайте /mcp, перепід’єднайте holarch з Читати й пропонувати зміни, потім почніть нову розмову. |