Holarch

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.

Como usá-lo →

Nesta página
  1. Visão geral
  2. Pré-requisitos
  3. Como usá-lo
    1. Quando e por quê
    2. Configurar a sincronização
    3. Criar issues do Jira a partir de requisitos aprovados
    4. Manter a chave do Jira no Holarch (opcional)
    5. Transformar uma issue do Jira em uma proposta do Holarch com o Claude
    6. Exemplo prático: a demonstração CubeSat EO-1
    7. Dicas
  4. Solução de problemas
  5. Páginas relacionadas

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

  1. No Holarch, crie um token Somente leitura limitado ao projeto. Copie-o.
  2. Encontre o id do projeto: GET /api/v1/projects lista seus projetos com o id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. 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, como https://your-site.atlassian.net.
    • JIRA_EMAIL e JIRA_API_TOKEN: o e-mail com que você entra na Atlassian e o token de API.
    • JIRA_PROJECT: a chave do projeto do Jira, como EO.
  2. 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}")
  1. 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=Requirement lista os requisitos, 500 por vez.
  • GET /api/v1/projects/<project>/entities/<id> traz os atributos de cada requisito (aqui, Status) e sua url, o link que o abre no Holarch.
  • Cada issue recebe os rótulos do Jira holarch e holarch-<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.

  1. 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).
  2. Crie um token Leitura e escrita para o script em vez do token somente leitura.
  3. 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.

  1. Abra o Claude, conectado ao Holarch com acesso Ler e propor alterações.
  2. 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.

  3. O Claude lê o projeto com list_projects, search_entities e get_entity. Ele acrescenta cada alteração a uma proposta com update_entity (ou create_entity e relate para novos requisitos) e depois a envia com propose_changes.

    O Claude responde com o título da proposta e um link para revisá-la.

  4. No Holarch, abra ✦ IA ▾ → Revisar “<título>”…, ou a notificação sob o sino.
  5. 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

  1. Crie a demonstração com Gerenciar projetos → Arquivos de projeto ▾ → Novo projeto de demonstração.
  2. Crie um token somente leitura limitado ao projeto de demonstração e execute holarch_to_jira.py contra 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.

  3. Execute o script novamente.

    Ele não imprime nada: todos os requisitos aprovados já têm sua issue.

  4. 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.
  5. 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 sintomaCausa e solução
Holarch answered 401 token-invalidO token está errado, revogado ou expirado. Crie um novo em Ajustes da conta → Tokens de API.
Holarch answered 403 plan-apiO 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-policyA organização do projeto desativou o acesso pela API. Peça a um administrador da organização.
Holarch answered 403 read-only-tokenA gravação de Jira Key exige um token Leitura e escrita.
Holarch answered 400 unknown-attributeO projeto não tem atributo Jira Key para Requirement. Adicione-o em Ajustes → Esquema, ou omita o passo opcional.
Holarch answered 409 change-controlO 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-limitedMais 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 400O 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 403Verifique 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 HolarchA conexão é somente leitura. Conecte novamente com Ler e propor alterações e inicie uma nova conversa.