Referência
Receita: Jira
Conecte requisitos do Holarch a issues do Jira com a API REST e transforme issues do Jira em mudanças revisadas do Holarch por meio do Claude; configuração, um script de sincronização, um exemplo prático e solução de problemas.
Visão geral
Esta receita mantém o trabalho de engenharia no Jira ligado aos requisitos no Holarch. Ela tem duas partes:
- Do Holarch para o Jira (API REST): um script cria uma issue do Jira para cada requisito aprovado. Cada issue tem um link de volta para o requisito no Holarch. Execute-o novamente a qualquer momento: ele pula os requisitos que já têm uma issue.
- Do Jira para o Holarch (MCP, pelo Claude): o Claude lê uma issue do Jira, como uma solicitação de mudança de um cliente, e propõe as alterações correspondentes nos requisitos do Holarch. Nada muda até que você revise e aplique a proposta no Holarch.
O Holarch não tem um conector embutido para o Jira. A receita usa a API REST e o MCP, para que você possa adaptar cada passo.
Pré-requisitos
- Um plano com a API e o MCP: Individual ou Team, ou a avaliação do Individual. No plano Free, uma conta com um endereço de e-mail acadêmico verificado ou em uma organização de turma ativa também os tem (Planos e limites).
- Um projeto do Holarch do qual você é editor ou proprietário. As propostas exigem o papel de editor.
- Um token de acesso pessoal: Ajustes da conta → Tokens de API → Novo token. Use Somente leitura para o script do Holarch para o Jira e limite-o ao projeto (Criar um token).
- Jira Cloud: um projeto do Jira em que você possa criar issues, e um token de API da Atlassian (ajustes da conta Atlassian → Security → API tokens). O Jira Data Center usa os caminhos
/rest/api/2/e um token de acesso pessoal; consulte a referência da API dele. - Python 3.9 ou posterior com o pacote
requests(python3 -m pip install requests) para o script. - Para a parte do Claude: o Claude conectado ao Holarch (Conectar o Holarch ao Claude). O Claude só lê issues do Jira por conta própria quando também tem um conector do Jira; caso contrário, cole o texto da issue na conversa.
Como usá-lo
Quando e por quê
Os requisitos ficam no Holarch; o trabalho para construí-los e testá-los costuma ser planejado no Jira. Vincular os dois responde a duas perguntas: "que trabalho no Jira implementa este requisito?" e "quais requisitos esta solicitação de mudança afeta?". Execute a sincronização após cada revisão de requisitos, quando novos requisitos chegarem a Approved.
Configurar a sincronização
- No Holarch, crie um token Somente leitura limitado ao projeto. Copie-o.
- Encontre o id do projeto:
GET /api/v1/projectslista seus projetos com oid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- Defina as variáveis de ambiente que o script lê:
HOLARCH_TOKEN: o token do Holarch.HOLARCH_PROJECT: o id do projeto.JIRA_URL: o seu site do Jira, comohttps://your-site.atlassian.net.JIRA_EMAILeJIRA_API_TOKEN: o e-mail com que você entra na Atlassian e o token de API.JIRA_PROJECT: a chave do projeto do Jira, comoEO.
- Salve o script abaixo como
holarch_to_jira.py.
Criar issues do Jira a partir de requisitos aprovados
O script lê todos os requisitos pela API REST, pula os que já têm uma issue do Jira e cria uma Task para cada requisito restante cujo Status seja 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}")
- Execute
python3 holarch_to_jira.py.Você vê uma linha por nova issue, como
2.1 Pointing Accuracy -> EO-12.
Como funciona:
GET /api/v1/projects/<project>/entities?class=Requirementlista os requisitos, 500 por vez.GET /api/v1/projects/<project>/entities/<id>traz os atributos de cada requisito (aqui, Status) e suaurl, o link que o abre no Holarch.- Cada issue recebe os rótulos do Jira
holarcheholarch-<id>. A execução seguinte os encontra com uma pesquisa no Jira e pula esses requisitos. - Os requisitos são apenas lidos. O script não altera nada no Holarch.
Manter a chave do Jira no Holarch (opcional)
Para ver a chave do Jira no requisito no Holarch, adicione um atributo de texto e grave a chave nele.
- No Holarch, abra Ajustes → Esquema, clique em Requirement e adicione um atributo chamado Jira Key com o tipo Texto curto (Adicionar um atributo a uma classe).
- Crie um token Leitura e escrita para o script em vez do token somente leitura.
- No final do último laço do script, depois da linha
print(…), acrescente:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
A alteração é gravada como uma edição no app: ela é registrada com o seu nome, e todos com o projeto aberto a veem. Definir este atributo não devolve um requisito aprovado para revisão. Quando o projeto usa controle de configuração, os requisitos aprovados recusam alterações diretas (409 change-control); mantenha a chave somente no Jira, ou faça a alteração por meio de uma solicitação de mudança.
Transformar uma issue do Jira em uma proposta do Holarch com o Claude
Use isto quando uma issue do Jira pede uma alteração de requisito, como um pedido de um cliente para apertar um valor.
- Abra o Claude, conectado ao Holarch com acesso Ler e propor alterações.
- Peça, por exemplo: "Leia a issue EO-31 do Jira. Encontre os requisitos do Holarch no projeto CubeSat que ela afeta e proponha as alterações que ela pede. Mencione EO-31 no resumo da proposta."
Sem um conector do Jira, cole o resumo e a descrição da issue na mensagem.
- O Claude lê o projeto com
list_projects,search_entitieseget_entity. Ele acrescenta cada alteração a uma proposta comupdate_entity(oucreate_entityerelatepara novos requisitos) e depois a envia compropose_changes.O Claude responde com o título da proposta e um link para revisá-la.
- No Holarch, abra ✦ IA ▾ → Revisar “<título>”…, ou a notificação sob o sino.
- Verifique cada alteração. Desmarque o que você não quer e clique em Aplicar selecionados.
As alterações são aplicadas, e um único Desfazer reverte tudo. Um texto de requisito alterado marca seus vínculos de rastreamento para revisão, e um requisito aprovado volta para In Review, como em qualquer edição.
Scripts podem fazer a mesma proposta sem o Claude: POST /api/v1/projects/<project>/proposal/changes uma vez por alteração e depois POST /api/v1/projects/<project>/proposal com um title e um 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
Exemplo prático: a demonstração CubeSat EO-1
- Crie a demonstração com Gerenciar projetos → Arquivos de projeto ▾ → Novo projeto de demonstração.
- Crie um token somente leitura limitado ao projeto de demonstração e execute
holarch_to_jira.pycontra um projeto de teste do Jira.Cada requisito aprovado recebe uma issue, como 2.1 Pointing Accuracy com o texto "The ADCS shall point the payload boresight within 0.1 degrees of the commanded target." e o link para o requisito.
- Execute o script novamente.
Ele não imprime nada: todos os requisitos aprovados já têm sua issue.
- No Jira, crie uma issue EO-31 pedindo 0,08 grau em vez de 0,1 grau. Peça ao Claude que proponha a alteração, como acima.
- No Holarch, revise a proposta. Ela altera o texto de 2.1 Pointing Accuracy, e sua lista Impacto mostra TC-04 Pointing Accuracy Test, que o verifica.
Dicas
- Dê ao script de sincronização o seu próprio token somente leitura, limitado ao projeto. Dê ao Claude uma conexão separada.
- Mantenha os tokens no seu cofre de segredos ou no ambiente, nunca no script.
- Pesquise no Jira os requisitos por trás de um sprint com o rótulo
holarch. - Os números dos requisitos podem mudar; o rótulo
holarch-<id>não. Faça a associação pelo rótulo, não pelo número no resumo.
Solução de problemas
| Mensagem ou sintoma | Causa e solução |
|---|---|
Holarch answered 401 token-invalid | O token está errado, revogado ou expirado. Crie um novo em Ajustes da conta → Tokens de API. |
Holarch answered 403 plan-api | O plano da conta não inclui a API e o MCP. Inicie a avaliação do Individual ou escolha um plano; o token então volta a funcionar. |
Holarch answered 403 org-policy | A organização do projeto desativou o acesso pela API. Peça a um administrador da organização. |
Holarch answered 403 read-only-token | A gravação de Jira Key exige um token Leitura e escrita. |
Holarch answered 400 unknown-attribute | O projeto não tem atributo Jira Key para Requirement. Adicione-o em Ajustes → Esquema, ou omita o passo opcional. |
Holarch answered 409 change-control | O requisito está sob controle de configuração. Altere-o por meio de uma solicitação de mudança, ou mantenha a chave somente no Jira. |
Holarch answered 429 rate-limited | Mais de 600 solicitações ou 120 alterações por minuto. Aguarde os segundos indicados em Retry-After e execute novamente; as issues já concluídas são puladas. |
| O Jira responde 400 | O Jira recusou os campos da issue, por exemplo um tipo de issue que o projeto não tem. Use um dos tipos de issue do projeto em vez de Task. |
| O Jira responde 401 ou 403 | Verifique JIRA_EMAIL, JIRA_API_TOKEN e sua permissão para criar issues no projeto do Jira. |
| O Claude não mostra as ferramentas de escrita do Holarch | A conexão é somente leitura. Conecte novamente com Ler e propor alterações e inicie uma nova conversa. |