Référence
Recette : Jira
Reliez les exigences de Holarch aux tickets Jira avec l'API REST, et transformez des tickets Jira en modifications Holarch examinées grâce à Claude ; configuration, script de synchronisation, exemple complet et dépannage.
Vue d'ensemble
Cette recette garde le travail d'ingénierie dans Jira lié aux exigences dans Holarch. Elle comporte deux parties :
- De Holarch vers Jira (API REST) : un script crée un ticket Jira pour chaque exigence approuvée. Chaque ticket renvoie vers l'exigence dans Holarch. Exécutez-le de nouveau à tout moment : il ignore les exigences qui ont déjà un ticket.
- De Jira vers Holarch (MCP, par Claude) : Claude lit un ticket Jira, comme une demande de modification d'un client, et propose les modifications d'exigences correspondantes dans Holarch. Rien ne change tant que vous n'avez pas examiné et appliqué la proposition dans Holarch.
Holarch n'a pas de connecteur Jira intégré. La recette utilise l'API REST et MCP : vous pouvez donc adapter chaque étape.
Prérequis
- Une offre avec l'API et MCP : Individual ou Team, ou l'essai Individual. Avec l'offre Free, un compte doté d'une adresse e-mail académique vérifiée ou appartenant à une organisation de cours active en dispose aussi (Offres et limites).
- Un projet Holarch dont vous êtes éditeur ou propriétaire. Les propositions nécessitent le rôle d'éditeur.
- Un jeton d'accès personnel : Paramètres du compte → Jetons API → Nouveau jeton. Utilisez Lecture seule pour le script de Holarch vers Jira et limitez-le au projet (Créer un jeton).
- Jira Cloud : un projet Jira dans lequel vous pouvez créer des tickets, et un jeton API Atlassian (paramètres du compte Atlassian → Security → API tokens). Jira Data Center utilise plutôt les chemins
/rest/api/2/et un jeton d'accès personnel ; consultez sa référence d'API. - Python 3.9 ou une version ultérieure avec le paquet
requests(python3 -m pip install requests) pour le script. - Pour la partie Claude : Claude connecté à Holarch (Connecter Holarch à Claude). Claude ne lit lui-même les tickets Jira que s'il dispose aussi d'un connecteur Jira ; sinon, collez le texte du ticket dans la conversation.
Mode d'emploi
Quand et pourquoi
Les exigences se trouvent dans Holarch ; le travail pour les réaliser et les tester est souvent planifié dans Jira. Relier les deux répond à deux questions : « quel travail Jira met en œuvre cette exigence ? » et « quelles exigences cette demande de modification touche-t-elle ? ». Exécutez la synchronisation après chaque revue des exigences, lorsque de nouvelles exigences atteignent Approved.
Configurer la synchronisation
- Dans Holarch, créez un jeton Lecture seule limité au projet. Copiez-le.
- Trouvez l'id du projet :
GET /api/v1/projectsliste vos projets avec leurid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- Définissez les variables d'environnement que lit le script :
HOLARCH_TOKEN: le jeton Holarch.HOLARCH_PROJECT: l'id du projet.JIRA_URL: votre site Jira, commehttps://your-site.atlassian.net.JIRA_EMAILetJIRA_API_TOKEN: votre e-mail de connexion Atlassian et votre jeton API.JIRA_PROJECT: la clé du projet Jira, commeEO.
- Enregistrez le script ci-dessous sous le nom
holarch_to_jira.py.
Créer des tickets Jira à partir des exigences approuvées
Le script lit chaque exigence par l'API REST, ignore celles qui ont déjà un ticket Jira et crée une Task pour chaque exigence restante dont le Statut est 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}")
- Exécutez
python3 holarch_to_jira.py.Vous voyez une ligne par nouveau ticket, comme
2.1 Pointing Accuracy -> EO-12.
Fonctionnement :
GET /api/v1/projects/<project>/entities?class=Requirementliste les exigences, 500 à la fois.GET /api/v1/projects/<project>/entities/<id>donne les attributs de chaque exigence (ici Statut) et sonurl, le lien qui l'ouvre dans Holarch.- Chaque ticket reçoit les étiquettes Jira
holarchetholarch-<id>. L'exécution suivante les trouve par une recherche Jira et ignore ces exigences. - Les exigences sont seulement lues. Le script ne modifie rien dans Holarch.
Conserver la clé Jira dans Holarch (facultatif)
Pour voir la clé Jira sur l'exigence dans Holarch, ajoutez un attribut texte et écrivez-y la clé.
- Dans Holarch, ouvrez Paramètres → Schéma, cliquez sur Requirement et ajoutez un attribut nommé Jira Key de type Texte court (Ajouter un attribut à une classe).
- Créez un jeton Lecture et écriture pour le script au lieu du jeton en lecture seule.
- À la fin de la dernière boucle du script, après la ligne
print(…), ajoutez :
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
La modification est écrite comme une modification dans l'application : elle est enregistrée sous votre nom et toutes les personnes qui ont ouvert le projet la voient. Définir cet attribut ne renvoie pas une exigence approuvée en revue. Lorsque le projet utilise le contrôle de configuration, les exigences approuvées refusent les modifications directes (409 change-control) ; conservez la clé uniquement dans Jira, ou faites la modification par une demande de modification.
Transformer un ticket Jira en proposition Holarch avec Claude
Utilisez ceci lorsqu'un ticket Jira demande une modification d'exigence, comme une demande d'un client de resserrer une valeur.
- Ouvrez Claude, connecté à Holarch avec l'accès Lire et proposer des modifications.
- Demandez par exemple : « Lis le ticket Jira EO-31. Trouve les exigences Holarch du projet CubeSat qu'il concerne, et propose les modifications qu'il demande. Mentionne EO-31 dans le résumé de la proposition. »
Sans connecteur Jira, collez plutôt le résumé et la description du ticket dans le message.
- Claude lit le projet avec
list_projects,search_entitiesetget_entity. Il ajoute chaque modification à une proposition avecupdate_entity(oucreate_entityetrelatepour les nouvelles exigences), puis l'envoie avecpropose_changes.Claude répond avec le titre de la proposition et un lien pour l'examiner.
- Dans Holarch, ouvrez ✦ IA ▾ → Examiner « <title> »…, ou la notification sous la cloche.
- Vérifiez chaque modification. Décochez ce que vous ne voulez pas, puis cliquez sur Appliquer la sélection.
Les modifications sont appliquées, et une seule annulation défait le tout. Un texte d'exigence modifié marque ses liens de traçabilité pour revue, et une exigence approuvée revient à In Review, comme pour toute modification.
Les scripts peuvent faire la même proposition sans Claude : POST /api/v1/projects/<project>/proposal/changes une fois par modification, puis POST /api/v1/projects/<project>/proposal avec un title et un 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
Exemple complet : la démo CubeSat EO-1
- Créez la démonstration avec Gérer les projets → Fichiers de projet ▾ → Nouveau projet de démonstration.
- Créez un jeton en lecture seule limité au projet de démonstration, et exécutez
holarch_to_jira.pysur un projet Jira de test.Chaque exigence approuvée reçoit un ticket, comme 2.1 Pointing Accuracy avec le texte « The ADCS shall point the payload boresight within 0.1 degrees of the commanded target. » et le lien vers l'exigence.
- Exécutez de nouveau le script.
Il n'affiche rien : chaque exigence approuvée a déjà son ticket.
- Dans Jira, créez un ticket EO-31 qui demande 0,08 degré au lieu de 0,1 degré. Demandez à Claude de proposer la modification, comme ci-dessus.
- Dans Holarch, examinez la proposition. Elle modifie le texte de 2.1 Pointing Accuracy, et sa liste Impact affiche TC-04 Pointing Accuracy Test, qui la vérifie.
Conseils
- Donnez au script de synchronisation son propre jeton en lecture seule, limité au projet. Donnez à Claude une connexion distincte.
- Conservez les jetons dans votre coffre de secrets ou dans l'environnement, jamais dans le script.
- Recherchez dans Jira les exigences derrière un sprint avec l'étiquette
holarch. - Les numéros d'exigence peuvent changer ; l'étiquette
holarch-<id>, non. Faites la correspondance sur l'étiquette, pas sur le numéro du résumé.
Dépannage
| Message ou symptôme | Cause et solution |
|---|---|
Holarch answered 401 token-invalid | Le jeton est erroné, révoqué ou expiré. Créez-en un nouveau sous Paramètres du compte → Jetons API. |
Holarch answered 403 plan-api | L'offre du compte ne comprend pas l'API et MCP. Démarrez l'essai Individual ou choisissez une offre ; le jeton fonctionne alors de nouveau. |
Holarch answered 403 org-policy | L'organisation du projet a désactivé l'accès API. Adressez-vous à un administrateur de l'organisation. |
Holarch answered 403 read-only-token | L'écriture de Jira Key nécessite un jeton Lecture et écriture. |
Holarch answered 400 unknown-attribute | Le projet n'a pas d'attribut Jira Key pour Requirement. Ajoutez-le dans Paramètres → Schéma, ou omettez l'étape facultative. |
Holarch answered 409 change-control | L'exigence est sous contrôle de configuration. Modifiez-la par une demande de modification, ou conservez la clé uniquement dans Jira. |
Holarch answered 429 rate-limited | Plus de 600 requêtes ou 120 modifications par minute. Attendez le nombre de secondes indiqué dans Retry-After, puis relancez ; les tickets déjà créés sont ignorés. |
| Jira répond 400 | Jira a refusé les champs du ticket, par exemple un type de ticket que le projet n'a pas. Utilisez l'un des types de tickets du projet au lieu de Task. |
| Jira répond 401 ou 403 | Vérifiez JIRA_EMAIL, JIRA_API_TOKEN et votre autorisation de créer des tickets dans le projet Jira. |
| Claude n'affiche pas les outils d'écriture de Holarch | La connexion est en lecture seule. Connectez-vous de nouveau avec Lire et proposer des modifications, puis démarrez une nouvelle conversation. |