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.

Встроенного коннектора 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.

Настройка синхронизации

  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. Спросите, например: “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 вставьте в сообщение сводку и описание задачи.

  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У класса Requirement в проекте нет атрибута Jira Key. Добавьте его в Настройки → Схема или пропустите необязательный шаг.
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Подключение только для чтения. Подключитесь снова с доступом Чтение и предложение изменений, затем начните новую беседу.