Справочник
Рецепт: GitHub
Запуск проверок модели Holarch из GitHub Actions с отслеживанием замечаний в виде задачи GitHub и предложение Claude Code тестовых случаев для требований, которые реализует ветка; настройка, файл рабочего процесса, разобранный пример и устранение неполадок.
На этой странице
Обзор
Этот рецепт соединяет репозиторий GitHub с проектом Holarch. В нём две части:
- Проверки модели в GitHub Actions (REST API): рабочий процесс по расписанию запускает проверки модели Holarch для требований проекта. Он записывает замечания в сводку запуска и поддерживает одну задачу GitHub в актуальном состоянии.
- Требования при рецензировании кода (MCP, через Claude Code): Claude Code читает ветку, над которой вы работаете, находит в Holarch требования, которые она реализует, и предлагает тестовые случаи, которые их верифицируют. Вы просматриваете предложение в Holarch, прежде чем что-либо изменится.
Встроенного приложения GitHub в Holarch нет. Рецепт использует 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
Используйте это перед открытием запроса на слияние, чтобы требования, которые реализует изменение, получили верифицирующий тестовый случай.
- Подключите Claude Code к Holarch один раз:
claude mcp add --transport http holarch https://app.holarch.app/mcp
Затем введите /mcp, выберите holarch → Authenticate, войдите в Holarch и нажмите Разрешить с Чтение и предложение изменений.
- В репозитории, в своей ветке, попросите Claude Code, например: “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 читает diff с помощью git. В Holarch он использует
search_entitiesиget_entity, чтобы найти требования, иrun_model_checksс правиломRequirement.10, чтобы узнать, у каких нет верифицирующего тестового случая. Он добавляет каждый тестовый случай с помощьюcreate_entityвместе со связью verifies, затем отправляет предложение с помощьюpropose_changes.Claude Code отвечает заголовком предложения и ссылкой для его рецензирования.
- В Holarch откройте ✦ ИИ ▾ → Рецензировать «<title>»… или уведомление под колокольчиком.
- При необходимости отредактируйте имена и описания, затем нажмите Применить выбранные.
Тестовые случаи создаются с вашим именем в истории, и одно нажатие “Отменить” возвращает всё назад. Следующий запуск рабочего процесса по расписанию больше не перечисляет эти требования.
Вставьте ссылку на требование в описание запроса на слияние: 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 с доступом Чтение и предложение изменений, затем начните новую беседу. |