Довідник
Рецепт: Jira
Зв’яжіть вимоги Holarch із задачами Jira через REST API і перетворюйте задачі Jira на переглянуті зміни Holarch через Claude; налаштування, скрипт синхронізації, розібраний приклад і усунення несправностей.
Огляд
Цей рецепт пов’язує інженерну роботу в Jira з вимогами в Holarch. Він має дві частини:
- Holarch → Jira (REST API): скрипт створює одну задачу Jira для кожної затвердженої вимоги. Кожна задача посилається назад на вимогу в Holarch. Запускайте його повторно будь-коли: він пропускає вимоги, що вже мають задачу.
- Jira → Holarch (MCP, через Claude): Claude читає задачу Jira, як-от запит замовника на зміну, і пропонує відповідні зміни вимог у Holarch. Нічого не змінюється, доки ви не переглянете й не застосуєте пропозицію в Holarch.
Holarch не має вбудованого конектора Jira. Рецепт використовує 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 з доступом Читати й пропонувати зміни.
- Запитайте, наприклад: "Прочитай задачу Jira EO-31. Знайди вимоги Holarch у проєкті CubeSat, яких вона стосується, і запропонуй зміни, яких вона вимагає. Згадай EO-31 у підсумку пропозиції."
Без конектора 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 | Проєкт не має атрибута Jira Key для Requirement. Додайте його в Налаштування → Схема або пропустіть необов’язковий крок. |
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 | З’єднання лише для читання. Під’єднайтеся знову з Читати й пропонувати зміни, потім почніть нову розмову. |