Holarch

Довідник

Рецепт: Jira

Зв’яжіть вимоги Holarch із задачами Jira через REST API і перетворюйте задачі Jira на переглянуті зміни Holarch через Claude; налаштування, скрипт синхронізації, розібраний приклад і усунення несправностей.

Як цим користуватися →

На цій сторінці
  1. Огляд
  2. Передумови
  3. Як користуватися
    1. Коли й навіщо
    2. Налаштування синхронізації
    3. Створення задач Jira із затверджених вимог
    4. Збереження ключа Jira в Holarch (необов’язково)
    5. Перетворення задачі Jira на пропозицію Holarch за допомогою Claude
    6. Робочий приклад: демопроєкт CubeSat EO-1
    7. Поради
  4. Усунення несправностей
  5. Пов’язані сторінки

Огляд

Цей рецепт пов’язує інженерну роботу в 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.

Налаштування синхронізації

  1. У Holarch створіть токен Лише читання, обмежений проєктом. Скопіюйте його.
  2. Знайдіть id проєкту: GET /api/v1/projects перелічує ваші проєкти з їхнім id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Задайте змінні середовища, які читає скрипт:
    • 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.
  2. Збережіть скрипт нижче як 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}")
  1. Виконайте 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, додайте текстовий атрибут і записуйте ключ у нього.

  1. У Holarch відкрийте Налаштування → Схема, клацніть Requirement і додайте атрибут з назвою Jira Key типу Короткий текст (Додавання атрибута до класу).
  2. Створіть для скрипту токен Читання й запис замість токена лише для читання.
  3. Наприкінці останнього циклу скрипту, після рядка print(…), додайте:
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

Зміна записується як редагування в застосунку: вона записується під вашим іменем, і її бачить кожен, у кого відкрито проєкт. Задання цього атрибута не повертає затверджену вимогу на рецензування. Коли проєкт використовує керування конфігурацією, затверджені вимоги відхиляють прямі зміни (409 change-control); зберігайте ключ лише в Jira або вносьте зміну через запит на зміну.

Перетворення задачі Jira на пропозицію Holarch за допомогою Claude

Використовуйте це, коли задача Jira вимагає зміни вимоги, як-от запит замовника посилити значення.

  1. Відкрийте Claude, під’єднаний до Holarch з доступом Читати й пропонувати зміни.
  2. Запитайте, наприклад: "Прочитай задачу Jira EO-31. Знайди вимоги Holarch у проєкті CubeSat, яких вона стосується, і запропонуй зміни, яких вона вимагає. Згадай EO-31 у підсумку пропозиції."

    Без конектора Jira натомість вставте в повідомлення короткий опис і опис задачі.

  3. Claude читає проєкт через list_projects, search_entities і get_entity. Він додає кожну зміну до пропозиції через update_entity (або create_entity і relate для нових вимог), потім надсилає її через propose_changes.

    Claude відповідає назвою пропозиції й посиланням для її перегляду.

  4. У Holarch відкрийте ✦ ШІ ▾ → Переглянути “<title>”… або сповіщення під дзвіночком.
  5. Перевірте кожну зміну. Зніміть позначки з того, чого не хочете, потім натисніть Застосувати вибране.

    Зміни застосовуються, і одне натискання “Відмінити” повертає все назад. Змінений текст вимоги позначає її зв’язки простежування для перегляду, а затверджена вимога повертається в стан 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

  1. Створіть демо через Керування проєктами → Файли проєктів ▾ → Новий демопроєкт.
  2. Створіть токен лише для читання, обмежений демопроєктом, і запустіть holarch_to_jira.py з тестовим проєктом Jira.

    Кожна затверджена вимога отримує задачу, як-от 2.1 Pointing Accuracy з текстом "The ADCS shall point the payload boresight within 0.1 degrees of the commanded target." і посиланням на вимогу.

  3. Запустіть скрипт знову.

    Він нічого не виводить: кожна затверджена вимога вже має свою задачу.

  4. У Jira створіть задачу EO-31 з вимогою 0,08 градуса замість 0,1 градуса. Попросіть Claude запропонувати зміну, як описано вище.
  5. У 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 відповідає 400Jira відхилила поля задачі, наприклад тип задачі, якого немає в проєкті. Використайте один із типів задач проєкту замість Task.
Jira відповідає 401 або 403Перевірте JIRA_EMAIL, JIRA_API_TOKEN і свій дозвіл створювати задачі в проєкті Jira.
Claude не показує інструментів запису HolarchЗ’єднання лише для читання. Під’єднайтеся знову з Читати й пропонувати зміни, потім почніть нову розмову.