リファレンス
レシピ:Jira
REST API で Holarch の要求を Jira の課題に接続し、Claude を通じて Jira の課題をレビュー済みの Holarch の変更に変換します。設定、同期スクリプト、具体例、トラブルシューティングを説明します。
このページの内容
概要
このレシピは、Jira でのエンジニアリング作業を Holarch の要求に結び付けておきます。2 つの部分があります:
- Holarch から Jira へ(REST API):スクリプトが、承認済みの要求ごとに 1 つの 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 プロジェクトと、Atlassian の API トークン(Atlassian のアカウント設定 → Security → API tokens)。Jira Data Center では、代わりに
/rest/api/2/のパスと個人用アクセストークンを使います。その API リファレンスを確認してください。 - スクリプト用に、
requestsパッケージ(python3 -m pip install requests)を備えた Python 3.9 以降。 - Claude の部分には:Holarch に接続された Claude(Holarch を Claude に接続する)。Claude が Jira の課題を自分で読めるのは、Jira のコネクタもある場合だけです。ない場合は、課題のテキストを会話に貼り付けます。
使い方
使う場面と理由
要求は Holarch にあり、それを構築してテストする作業は Jira で計画されることがよくあります。両者をリンクすると、2 つの質問に答えられます:「この要求を実装する 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 の課題があるものをスキップし、残りの要求のうちStatusが Approved のものそれぞれに Task を作成します。
# 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を実行します。新しい課題ごとに 1 行が表示されます。たとえば
2.1 Pointing Accuracy -> EO-12です。
仕組み:
GET /api/v1/projects/<project>/entities?class=Requirementが、要求を 500 件ずつ一覧表示します。GET /api/v1/projects/<project>/entities/<id>が、各要求の属性(ここではStatus)と、Holarch でそれを開くリンクであるurlを返します。- 各課題には Jira のラベル
holarchとholarch-<id>が付きます。次の実行では Jira の検索でそれらを見つけ、その要求をスキップします。 - 要求は読み取られるだけです。スクリプトは Holarch で何も変更しません。
Jira のキーを Holarch に保持する(任意)
Holarch の要求で Jira のキーを確認するには、テキスト属性を追加してキーを書き込みます。
- Holarch で設定 → スキーマを開き、Requirement をクリックして、種類短いテキストで Jira Key という名前の属性を追加します(クラスに属性を追加する)。
- スクリプト用に、読み取り専用のトークンの代わりに読み取りと書き込みのトークンを作成します。
- スクリプトの最後のループの終わり、
print(…)の行の後に、次を追加します:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
変更はアプリでの編集と同じように書き込まれます:あなたの名前で記録され、プロジェクトを開いている全員に表示されます。この属性を設定しても、承認済みの要求がレビューに戻ることはありません。プロジェクトで構成管理を使っている場合、承認済みの要求は直接の変更を拒否します(409 change-control)。キーは Jira にだけ保持するか、変更要求を通じて変更します。
Claude で Jira の課題を Holarch の提案にする
Jira の課題が要求の変更を求めている場合に使います。たとえば、値を厳しくするよう顧客が求めている場合です。
- 読み取りと変更の提案のアクセスで Holarch に接続した Claude を開きます。
- たとえば次のように依頼します:「Jira の課題 EO-31 を読んでください。それが影響する CubeSat プロジェクトの Holarch の要求を見つけ、求められている変更を提案してください。提案の要約に EO-31 を記載してください。」
Jira のコネクタがない場合は、代わりに課題の要約と説明をメッセージに貼り付けます。
- Claude は
list_projects、search_entities、get_entityでプロジェクトを読み取ります。update_entity(新しい要求にはcreate_entityとrelate)で各変更を提案に追加し、propose_changesで送信します。Claude は、提案のタイトルとレビュー用のリンクで答えます。
- Holarch で ✦ AI ▾ → Review “<title>”…、またはベルの下の通知を開きます。
- 各変更を確認します。不要なもののチェックを外してから、選択した項目を適用をクリックします。
変更が適用されます。1 回の元に戻すですべて取り消せます。通常の編集と同様に、要求のテキストが変更されるとそのトレースリンクにレビューの印が付き、承認済みの要求は In Review に戻ります。
スクリプトは Claude なしで同じ提案を作成できます:変更ごとに 1 回 POST /api/v1/projects/<project>/proposal/changes を送り、その後 title と summary を付けて POST /api/v1/projects/<project>/proposal を送ります。
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 のデモ
- プロジェクトを管理 → プロジェクトファイル ▾ → 新しいデモプロジェクトでデモを作成します。
- デモプロジェクトに限定した読み取り専用のトークンを作成し、テスト用の Jira プロジェクトに対して
holarch_to_jira.pyを実行します。承認済みの各要求に課題が作成されます。たとえば 2.1 Pointing Accuracy で、テキストは「The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.」、要求へのリンク付きです。
- スクリプトをもう一度実行します。
何も出力されません:承認済みのすべての要求にすでに課題があります。
- Jira で、0.1 度ではなく 0.08 度を求める課題 EO-31 を作成します。上記のとおり、Claude に変更を提案するよう依頼します。
- Holarch で提案をレビューします。提案は 2.1 Pointing Accuracy のテキストを変更し、その影響の一覧には、それを検証する TC-04 Pointing Accuracy Test が表示されます。
ヒント
- 同期スクリプトには、プロジェクトに限定した専用の読み取り専用トークンを与えます。Claude には別の接続を与えます。
- トークンはシークレットストアまたは環境に保持し、スクリプトには決して入れません。
- ラベル
holarchで、スプリントの背後にある要求を Jira で検索します。 - 要求の番号は変わることがありますが、
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 | 1 分間に 600 リクエストまたは 120 変更を超えています。Retry-After の秒数だけ待ってから、もう一度実行します。完了した課題はスキップされます。 |
| Jira が 400 を返す | Jira が課題のフィールドを拒否しました。たとえば、プロジェクトにない課題タイプです。Task の代わりに、プロジェクトの課題タイプのいずれかを使います。 |
| Jira が 401 または 403 を返す | JIRA_EMAIL、JIRA_API_TOKEN、および Jira プロジェクトで課題を作成する権限を確認します。 |
| Claude に Holarch の書き込みツールが表示されない | 接続が読み取り専用です。読み取りと変更の提案でもう一度接続してから、新しい会話を始めます。 |