Справочник
Рецепт: Jira
Связывание требований Holarch с задачами Jira через REST API и превращение задач Jira в проверенные изменения Holarch с помощью Claude; настройка, скрипт синхронизации, разобранный пример и устранение неполадок.
На этой странице
Обзор
Этот рецепт связывает инженерную работу в Jira с требованиями в Holarch. В нём две части:
- Из Holarch в Jira (REST API): скрипт создаёт по одной задаче Jira на каждое утверждённое требование. Каждая задача содержит ссылку на требование в Holarch. Запускайте его повторно в любое время: он пропускает требования, у которых уже есть задача.
- Из Jira в Holarch (MCP, через Claude): Claude читает задачу Jira, например запрос заказчика на изменение, и предлагает соответствующие изменения требований в Holarch. Ничего не меняется, пока вы не просмотрите и не примените предложение в Holarch.
Встроенного коннектора Jira в Holarch нет. Рецепт использует REST API и MCP, поэтому любой шаг можно адаптировать.
Предварительные требования
- Тариф с API и MCP: Individual или Team либо пробный период Individual. На тарифе Free они есть также у учётной записи с подтверждённым академическим адресом электронной почты или в активной учебной организации (Тарифы и ограничения).
- Проект Holarch, в котором вы редактор или владелец. Для предложений нужна роль редактора.
- Персональный токен доступа: Настройки учётной записи → Токены API → Новый токен. Используйте Только чтение для скрипта из Holarch в Jira и ограничьте его проектом (Создание токена).
- Jira Cloud: проект Jira, в котором вы можете создавать задачи, и токен API Atlassian (настройки учётной записи Atlassian → Security → API tokens). Jira Data Center вместо этого использует пути
/rest/api/2/и персональный токен доступа; см. его справочник по API. - Python 3.9 или новее с пакетом
requests(python3 -m pip install requests) для скрипта. - Для части с Claude: Claude, подключённый к Holarch (Подключение Holarch к Claude). Claude сам читает задачи Jira, только если у него есть и коннектор Jira; иначе вставьте текст задачи в беседу.
Как использовать
Когда и зачем
Требования находятся в Holarch; работа по их реализации и тестированию часто планируется в Jira. Связь между ними отвечает на два вопроса: “какая работа в Jira реализует это требование?” и “каких требований касается этот запрос на изменение?”. Запускайте синхронизацию после каждой рецензии требований, когда новые требования достигают статуса Approved.
Настройка синхронизации
- В Holarch создайте токен Только чтение, ограниченный проектом. Скопируйте его.
- Найдите id проекта:
GET /api/v1/projectsперечисляет ваши проекты с ихid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- Задайте переменные окружения, которые читает скрипт:
HOLARCH_TOKEN: токен Holarch.HOLARCH_PROJECT: id проекта.JIRA_URL: ваш сайт Jira, напримерhttps://your-site.atlassian.net.JIRA_EMAILиJIRA_API_TOKEN: адрес электронной почты для входа в Atlassian и токен API.JIRA_PROJECT: ключ проекта Jira, напримерEO.
- Сохраните скрипт ниже как
holarch_to_jira.py.
Создание задач Jira из утверждённых требований
Скрипт читает все требования через REST API, пропускает те, у которых уже есть задача Jira, и создаёт Task для каждого оставшегося требования, у которого Status — Approved.
# holarch_to_jira.py: one Jira issue per approved Holarch requirement. Safe to run again.
import os
import requests
HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
JIRA = os.environ["JIRA_URL"].rstrip("/")
JIRA_AUTH = (os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"])
JIRA_PROJECT = os.environ["JIRA_PROJECT"]
def holarch(method, path, **kw):
r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
if r.status_code >= 400:
d = r.json()
raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
return r.json()
def requirements():
offset = 0
while True:
page = holarch("GET", f"/projects/{PROJECT}/entities",
params={"class": "Requirement", "limit": 500, "offset": offset})
yield from page["entities"]
offset += page["limit"]
if offset >= page["total"]:
return
def linked_in_jira():
"""The Jira labels holarch-<requirement id> already on issues of the Jira project."""
seen, token = set(), None
while True:
params = {"jql": f'project = "{JIRA_PROJECT}" AND labels = holarch', "fields": "labels", "maxResults": 100}
if token:
params["nextPageToken"] = token
r = requests.get(JIRA + "/rest/api/3/search/jql", params=params, auth=JIRA_AUTH, timeout=60)
r.raise_for_status()
d = r.json()
for issue in d.get("issues", []):
seen.update(x for x in issue["fields"]["labels"] if x.startswith("holarch-"))
token = d.get("nextPageToken")
if not token:
return seen
seen = linked_in_jira()
for req in requirements():
if "holarch-" + req["id"] in seen:
continue
e = holarch("GET", f"/projects/{PROJECT}/entities/{req['id']}")["entity"]
if e["attributes"].get("Status") != "Approved":
continue
text = (e["description"] + "\n\n" if e["description"] else "") + "Requirement in Holarch: " + e["url"]
fields = {
"project": {"key": JIRA_PROJECT},
"issuetype": {"name": "Task"},
"summary": f"{e['number']} {e['name']}".strip(),
"labels": ["holarch", "holarch-" + e["id"]],
"description": {"type": "doc", "version": 1, "content": [
{"type": "paragraph", "content": [{"type": "text", "text": text}]}]},
}
issue = requests.post(JIRA + "/rest/api/3/issue", json={"fields": fields}, auth=JIRA_AUTH, timeout=60)
issue.raise_for_status()
key = issue.json()["key"]
print(f"{e['number']} {e['name']} -> {key}")
- Выполните
python3 holarch_to_jira.py.Вы увидите по одной строке на новую задачу, например
2.1 Pointing Accuracy -> EO-12.
Как это работает:
GET /api/v1/projects/<project>/entities?class=Requirementперечисляет требования по 500 за раз.GET /api/v1/projects/<project>/entities/<id>даёт атрибуты каждого требования (здесь Status) и егоurl— ссылку, которая открывает его в Holarch.- Каждая задача получает метки Jira
holarchиholarch-<id>. Следующий запуск находит их поиском в Jira и пропускает эти требования. - Требования только читаются. Скрипт ничего не меняет в Holarch.
Хранение ключа Jira в Holarch (необязательно)
Чтобы видеть ключ Jira у требования в Holarch, добавьте текстовый атрибут и запишите в него ключ.
- В Holarch откройте Настройки → Схема, щёлкните Requirement и добавьте атрибут с именем Jira Key и типом Короткий текст (Добавление атрибута в класс).
- Создайте для скрипта токен Чтение и запись вместо токена только для чтения.
- В конце последнего цикла скрипта, после строки
print(…), добавьте:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
Изменение записывается как правка в приложении: оно записывается под вашим именем, и все, у кого открыт проект, его видят. Установка этого атрибута не возвращает утверждённое требование на рецензирование. Когда в проекте используется управление конфигурацией, утверждённые требования отклоняют прямые изменения (409 change-control); храните ключ только в Jira или вносите изменение через запрос на изменение.
Превращение задачи Jira в предложение Holarch с помощью Claude
Используйте это, когда задача Jira просит изменить требование, например заказчик просит ужесточить значение.
- Откройте Claude, подключённый к Holarch с доступом Чтение и предложение изменений.
- Спросите, например: “Read Jira issue EO-31. Find the Holarch requirements in the CubeSat project that it affects, and propose the changes it asks for. Mention EO-31 in the proposal summary.”
Без коннектора Jira вставьте в сообщение сводку и описание задачи.
- Claude читает проект с помощью
list_projects,search_entitiesиget_entity. Он добавляет каждое изменение в предложение с помощьюupdate_entity(илиcreate_entityиrelateдля новых требований), затем отправляет его с помощьюpropose_changes.Claude отвечает заголовком предложения и ссылкой для его рецензирования.
- В Holarch откройте ✦ ИИ ▾ → Рецензировать «<title>»… или уведомление под колокольчиком.
- Проверьте каждое изменение. Снимите отметки с ненужных, затем нажмите Применить выбранные.
Изменения применяются, и одно нажатие “Отменить” возвращает всё назад. Изменённый текст требования помечает его связи трассировки для проверки, а утверждённое требование возвращается в In Review, как при любой правке.
Скрипты могут сделать такое же предложение без Claude: POST /api/v1/projects/<project>/proposal/changes по одному разу на изменение, затем POST /api/v1/projects/<project>/proposal с title и summary.
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
-d '{"op": "update", "entity": "<requirement id>", "description": "The ADCS shall point the payload boresight within 0.08 degrees of the commanded target."}' \
https://app.holarch.app/api/v1/projects/<project>/proposal/changes
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
-d '{"title": "EO-31: tighter pointing", "summary": "Customer request EO-31 tightens pointing accuracy to 0.08 degrees."}' \
https://app.holarch.app/api/v1/projects/<project>/proposal
Рабочий пример: демо CubeSat EO-1
- Создайте демо-проект через Управление проектами → Файлы проекта ▾ → Новый демо-проект.
- Создайте токен только для чтения, ограниченный демо-проектом, и запустите
holarch_to_jira.pyдля тестового проекта Jira.Каждое утверждённое требование получает задачу, например 2.1 Pointing Accuracy с текстом “The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.” и ссылкой на требование.
- Запустите скрипт снова.
Он ничего не выводит: у каждого утверждённого требования уже есть задача.
- В Jira создайте задачу EO-31 с просьбой указать 0.08 градуса вместо 0.1 градуса. Попросите Claude предложить изменение, как описано выше.
- В Holarch просмотрите предложение. Оно меняет текст 2.1 Pointing Accuracy, а его список Влияние показывает TC-04 Pointing Accuracy Test, который его верифицирует.
Советы
- Дайте скрипту синхронизации собственный токен только для чтения, ограниченный проектом. Дайте Claude отдельное подключение.
- Храните токены в хранилище секретов или в окружении, но никогда в скрипте.
- Ищите в Jira требования, стоящие за спринтом, по метке
holarch. - Номера требований могут меняться, а метка
holarch-<id>— нет. Сопоставляйте по метке, а не по номеру в сводке.
Устранение неполадок
| Сообщение или признак | Причина и исправление |
|---|---|
Holarch answered 401 token-invalid | Токен неверен, отозван или истёк. Создайте новый в разделе Настройки учётной записи → Токены API. |
Holarch answered 403 plan-api | Тариф учётной записи не включает API и MCP. Начните пробный период Individual или выберите тариф; после этого токен снова заработает. |
Holarch answered 403 org-policy | Организация проекта отключила доступ к API. Обратитесь к администратору организации. |
Holarch answered 403 read-only-token | Для записи Jira Key нужен токен Чтение и запись. |
Holarch answered 400 unknown-attribute | У класса Requirement в проекте нет атрибута Jira Key. Добавьте его в Настройки → Схема или пропустите необязательный шаг. |
Holarch answered 409 change-control | Требование находится под управлением конфигурацией. Измените его через запрос на изменение или храните ключ только в Jira. |
Holarch answered 429 rate-limited | Более 600 запросов или 120 изменений в минуту. Подождите столько секунд, сколько указано в Retry-After, затем запустите снова; готовые задачи пропускаются. |
| Jira отвечает 400 | Jira отклонила поля задачи, например тип задачи, которого нет в проекте. Используйте вместо Task один из типов задач проекта. |
| Jira отвечает 401 или 403 | Проверьте JIRA_EMAIL, JIRA_API_TOKEN и ваше право создавать задачи в проекте Jira. |
| Claude не показывает инструменты записи Holarch | Подключение только для чтения. Подключитесь снова с доступом Чтение и предложение изменений, затем начните новую беседу. |