Aller au contenu

InsightsSoftware Factory

Exporter ses tickets Jira en Markdown pour ses agents de code

Jira Cloud ne répond plus sur /rest/api/3/search : l'export passe par /search/jql et son nextPageToken. Script Python testé qui écrit un fichier Markdown par ticket au format Backlog.md, convertit l'ADF, rapatrie commentaires et pièces jointes, et les pièges à connaître.

Exporter ses tickets Jira en Markdown pour ses agents de code

Exporter Jira en Markdown consiste à écrire un fichier par ticket, avec un en-tête YAML pour les champs et le texte converti en Markdown, dans un dossier du repo. Vous obtenez un backlog en Markdown versionné que Claude Code, Codex ou Cursor lisent comme n'importe quel fichier, sans appel d'API. Cette page sert aux équipes sur Jira Cloud qui veulent amorcer ce backlog ou archiver leur historique avant de quitter Jira. Elle donne l'API à utiliser en novembre 2026, un script Python testé qui produit des fichiers au format Backlog.md, et les pièges que nous avons rencontrés.

Quelle API Jira Cloud utiliser pour exporter en 2026 ?

Sur Jira Cloud, la recherche passe par /rest/api/3/search/jql, en GET ou en POST1. Les anciens points d'accès sont retirés : la base de connaissances d'Atlassian indique que /rest/api/3/search a été entièrement supprimé de Jira Cloud2. Nous l'avons vérifié le 22 novembre 2026 sur une instance Jira Cloud publique d'Atlassian : /rest/api/3/search et /rest/api/2/search répondent tous deux HTTP 410 avec le message « The requested API has been removed. Please migrate to the /rest/api/3/search/jql API. »

Quatre différences cassent les scripts écrits pour l'ancienne API :

PointAncienne API (/search)/search/jql
PaginationstartAt et totalnextPageToken, absent de la dernière page, et booléen isLast
Champs renvoyésChamps navigables par défautL'identifiant seul par défaut : fields doit tout demander
Requête sans restrictionRenvoie tous les ticketsRefusée : HTTP 400, « Unbounded JQL queries are not allowed here »
Nombre total de résultatsChamp totalAbsent ; POST /rest/api/3/search/approximate-count donne une estimation

La spécification précise que maxResults vaut 50 par défaut et que l'API peut renvoyer moins de tickets par page quand beaucoup de champs sont demandés ; le jeton de page expire au bout de sept jours1. Une JQL bornée contient une restriction : project = PROJ ORDER BY key passe, ORDER BY key seul est refusé.

Jira Data Center garde l'ancienne API. Sur une instance autogérée en version 10.3, /rest/api/2/search répond encore avec startAt et total, et la description arrive en wiki markup (h3., # pour les listes) plutôt qu'en ADF (relevé du 22 novembre 2026).

Pourquoi convertir l'ADF avant de le donner à un agent ?

L'API v3 renvoie descriptions et commentaires en Atlassian Document Format (ADF), un arbre JSON de nœuds typés : paragraph, heading, bulletList, codeBlock, et des « marks » pour le gras, le code en ligne ou les liens3. Un agent sait lire ce JSON, mais une phrase de dix mots y occupe plusieurs lignes d'objets imbriqués. Le contexte part dans la structure au lieu du contenu. Convertir une fois à l'export coûte moins cher que de faire relire l'ADF à chaque session : c'est le principe du context engineering, mettre le contexte sous la forme que l'agent lit le mieux, là où il regarde déjà.

Le script Python, testé hors réseau

Le script ci-dessous parcourt une JQL, convertit l'ADF et écrit un fichier par ticket. Il dépend de requests et PyYAML et lit ses réglages dans l'environnement : JIRA_URL, JIRA_EMAIL, JIRA_TOKEN et JQL, plus BACKLOG_DIR et JIRA_SITE en option. Un jeton d'API sans portée s'utilise avec l'adresse du site (https://votre-site.atlassian.net). Atlassian recommande les jetons à portées, mais ceux-ci passent par la passerelle https://api.atlassian.com/ex/jira/{cloudId} : mettez alors cette adresse dans JIRA_URL et l'adresse du site dans JIRA_SITE, qui sert aux liens vers les tickets4. Nous l'avons testé le 22 novembre 2026 sur des réponses réelles de /search/jql rejouées hors réseau, avec un ADF d'essai qui couvre titres, listes imbriquées, code avec langage, liens, code en ligne et tableau.

#!/usr/bin/env python3
"""export_jira_md.py : un fichier Markdown par ticket Jira Cloud, au format Backlog.md.
Dépendances : pip install requests pyyaml"""
import os, re, requests, yaml
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

BASE = os.environ["JIRA_URL"].rstrip("/")          # ex. https://votre-site.atlassian.net
SITE = os.environ.get("JIRA_SITE", BASE)            # pour les liens /browse/
S = requests.Session()
S.auth = (os.environ["JIRA_EMAIL"], os.environ["JIRA_TOKEN"])
S.mount("https://", HTTPAdapter(max_retries=Retry(  # HTTP 429 : attendre Retry-After
    total=5, backoff_factor=2, status_forcelist=[429], allowed_methods=["GET", "POST"])))
JQL = os.environ.get("JQL", "project = PROJ ORDER BY key")  # la JQL doit être bornée
ROOT = os.environ.get("BACKLOG_DIR", "backlog")
FIELDS = ["summary", "status", "priority", "assignee", "labels", "issuelinks", "issuetype",
          "parent", "description", "comment", "attachment", "created", "updated"]
STATUS = {"new": "To Do", "indeterminate": "In Progress", "done": "Done"}  # catégories Jira

def mark(text, marks):
    """Applique les marques ADF (code, gras, italique, barré, lien) à un fragment."""
    for m in marks or []:
        t = m["type"]
        if t == "code": text = f"`{text}`"
        elif t == "strong": text = f"**{text}**"
        elif t == "em": text = f"*{text}*"
        elif t == "strike": text = f"~~{text}~~"
        elif t == "link": text = f"[{text}]({m['attrs']['href']})"
    return text

def adf_to_md(node):
    """Conversion ADF -> Markdown : couvre les nœuds courants, ignore les médias."""
    if not node: return ""
    t, kids, attrs = node.get("type"), node.get("content", []), node.get("attrs") or {}
    inner = lambda: "".join(adf_to_md(k) for k in kids)
    if t == "text": return mark(node.get("text", ""), node.get("marks"))
    if t == "hardBreak": return "\n"
    if t == "paragraph": return inner() + "\n\n"
    if t == "heading": return "#" * min(attrs.get("level", 1) + 2, 6) + " " + inner() + "\n\n"
    if t == "codeBlock":
        code = "".join(k.get("text", "") for k in kids)
        return f"```{attrs.get('language') or ''}\n{code}\n```\n\n"
    if t in ("bulletList", "orderedList"):
        lines = []
        for n, item in enumerate(kids, attrs.get("order", 1)):
            bullet = f"{n}." if t == "orderedList" else "-"
            body = re.sub(r"\n\n+", "\n", adf_to_md(item).strip("\n"))  # liste compacte
            body = body.replace("\n", "\n" + " " * (len(bullet) + 1))
            lines.append(f"{bullet} {body}")
        return "\n".join(lines) + "\n\n"
    if t == "blockquote": return "".join("> " + l + "\n" for l in inner().strip().split("\n")) + "\n"
    if t == "rule": return "***\n\n"
    if t in ("mention", "emoji"): return attrs.get("text") or attrs.get("shortName", "")
    if t in ("inlineCard", "blockCard"): return attrs.get("url", "")
    if t == "tableRow": return "| " + " | ".join(adf_to_md(c).strip().replace("\n", " ") for c in kids) + " |\n"
    if t == "table":
        rows = [adf_to_md(r) for r in kids]
        sep = "|" + " --- |" * len(kids[0].get("content", [])) + "\n" if kids else ""
        return (rows[0] + sep + "".join(rows[1:]) + "\n") if rows else ""
    if t in ("media", "mediaSingle", "mediaGroup"): return ""  # pièces jointes listées à part
    return inner()                                   # doc, listItem, panel, expand…

def search():
    """Parcourt tous les résultats : nextPageToken jusqu'à isLast."""
    token = None
    while True:
        body = {"jql": JQL, "fields": FIELDS, "maxResults": 100}
        if token: body["nextPageToken"] = token
        r = S.post(f"{BASE}/rest/api/3/search/jql", json=body, timeout=60)
        r.raise_for_status()
        data = r.json()
        yield from data["issues"]
        token = data.get("nextPageToken")
        if data.get("isLast") or not token: break

def comments(key, field):
    """Les commentaires de la recherche peuvent être incomplets : on complète si besoin."""
    got = field.get("comments", [])
    while len(got) < field.get("total", 0):
        r = S.get(f"{BASE}/rest/api/3/issue/{key}/comment", params={"startAt": len(got)}, timeout=60)
        r.raise_for_status()
        page = r.json()["comments"]
        if not page: break
        got += page
    return got

def filename(title):
    """Même nettoyage que Backlog.md (sanitizeFilename) pour le titre du fichier."""
    s = re.sub(r'[<>:"/\\|?*]', "-", title)
    s = re.sub(r"['(),!@#$%^&+=\[\]{};]", "", s)
    s = re.sub(r"-+", "-", re.sub(r"\s+", "-", s)).strip("-")
    return s or "untitled"

def main():
    for issue in search():
        key, f = issue["key"], issue["fields"]
        deps, links = [], []
        for l in f.get("issuelinks") or []:
            other = l.get("inwardIssue") or l.get("outwardIssue")
            if not other or not other.get("key"): continue  # lien sans ticket lisible
            rel = l["type"]["inward" if "inwardIssue" in l else "outward"]
            if l["type"]["name"] == "Blocks" and "inwardIssue" in l: deps.append(other["key"])
            links.append(f"- {rel} {other['key']}")
        status = STATUS.get(f["status"]["statusCategory"]["key"], "To Do")
        meta = {
            "id": key, "title": f["summary"], "status": status,
            "assignee": [f["assignee"]["displayName"]] if f.get("assignee") else [],
            "created_date": (f.get("created") or "")[:16].replace("T", " "),
            "updated_date": (f.get("updated") or "")[:16].replace("T", " "),
            "labels": (f.get("labels") or []) + ([f["issuetype"]["name"].lower()] if f.get("issuetype") else []),
            "dependencies": deps, "references": [f"{SITE}/browse/{key}"],
            "priority": (f.get("priority") or {}).get("name", "").lower() or None,
        }
        if (f.get("parent") or {}).get("key"): meta["parent_task_id"] = f["parent"]["key"]  # epic ou story parente
        body = ("## Description\n\n<!-- SECTION:DESCRIPTION:BEGIN -->\n"
                + adf_to_md(f.get("description")).strip() + "\n<!-- SECTION:DESCRIPTION:END -->\n")
        if links: body += "\n## Liens Jira\n\n" + "\n".join(links) + "\n"
        folder = f"{ROOT}/archive/tasks" if status == "Done" else f"{ROOT}/tasks"
        files = []
        for a in f.get("attachment") or []:              # téléchargement authentifié
            name, path = f"{a['id']}-{os.path.basename(a['filename'])}", f"{ROOT}/assets/{key}"
            os.makedirs(path, exist_ok=True)              # l'id évite d'écraser deux homonymes
            with S.get(a["content"], stream=True, timeout=300) as r:  # 303 vers les médias
                r.raise_for_status()
                with open(f"{path}/{name}", "wb") as fh:
                    for chunk in r.iter_content(1 << 20): fh.write(chunk)
            files.append(f"- [{name}](<{os.path.relpath(f'{path}/{name}', folder)}>)")
        if files: body += "\n## Pièces jointes\n\n" + "\n".join(files) + "\n"
        notes = [f"**{(c.get('author') or {}).get('displayName', '?')}**, {c['created'][:10]} :\n\n{adf_to_md(c['body']).strip()}"
                 for c in comments(key, f.get("comment") or {})]
        if notes: body += "\n## Commentaires Jira\n\n" + "\n\n".join(notes) + "\n"
        os.makedirs(folder, exist_ok=True)
        with open(f"{folder}/{key.lower()} - {filename(f['summary'])}.md", "w", encoding="utf-8") as fh:
            fh.write("---\n" + yaml.safe_dump(meta, allow_unicode=True, sort_keys=False)
                     + "---\n\n" + body)

if __name__ == "__main__":
    main()

Quatre choix méritent une explication.

  • Les liens entre tickets. Seul le lien « is blocked by » devient une dépendance au sens de Backlog.md ; les autres (« relates to », « clones », « is duplicated by ») restent lisibles dans une section « Liens Jira ». Un lien dont le ticket distant n'est pas renvoyé, par exemple faute de droits, est ignoré au lieu de produire une dépendance vide.
  • La hiérarchie. Le type du ticket (Story, Bug, Epic…) devient une étiquette, et le parent Jira (epic ou story) le champ parent_task_id de Backlog.md. Sans ces deux champs, epics, stories et sous-tâches se retrouveraient à plat.
  • Les commentaires. Le champ comment de la recherche porte un total. Quand il dépasse le nombre de commentaires reçus, le script complète par GET /rest/api/3/issue/{clé}/comment, qui se pagine par startAt5.
  • Les pièces jointes. L'URL content exige l'authentification et répond par une redirection 303 vers le stockage des médias d'Atlassian5. requests la suit ; le script écrit le fichier par blocs dans backlog/assets/<clé>/, préfixé par l'identifiant de la pièce jointe pour que deux captures homonymes ne s'écrasent pas, et le lie en chemin relatif.

Pour un ticket en cours, le résultat ressemble à ceci :

---
id: PROJ-123
title: Corriger la redirection après login SSO
status: In Progress
assignee:
- Camille Martin
created_date: 2026-10-02 09:14
updated_date: 2026-10-03 10:02
labels:
- auth
- sso
- story
dependencies:
- PROJ-98
references:
- https://votre-site.atlassian.net/browse/PROJ-123
priority: high
parent_task_id: PROJ-100
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Après connexion, l'utilisateur revient sur `/home` au lieu de la page demandée.

1. Conserver le paramètre `returnTo`
2. Ajouter un test de bout en bout
<!-- SECTION:DESCRIPTION:END -->

## Liens Jira

- is blocked by PROJ-98
- relates to PROJ-140

## Commentaires Jira

**Alex Dupont**, 2026-10-03 :

On garde la liste blanche des URL de retour, voir [la décision](https://wiki.example/adr-12).

Quelle arborescence et quel nommage retenir ?

Le plus simple est de reprendre l'arborescence de Backlog.md, même si vous n'adoptez pas l'outil tout de suite : un format déjà outillé vaut mieux qu'une convention maison à documenter.

  • backlog/tasks/ pour les tickets ouverts ;
  • backlog/archive/tasks/ pour les tickets dont le statut est dans la catégorie « Terminé » ;
  • backlog/assets/<clé>/ pour les pièces jointes ;
  • un fichier nommé <clé en minuscules> - <titre>.md, par exemple proj-123 - Corriger-la-redirection-après-login-SSO.md.

La clé Jira reste l'identifiant du ticket : un commit, une merge request ou un agent qui cite PROJ-123 retrouve le fichier, et le champ references garde le lien vers l'ancien ticket tant que l'instance existe.

Le fichier produit est-il compatible avec Backlog.md ?

Oui, à trois réglages près. Nous avons vérifié le format sur le dépôt de Backlog.md le 22 novembre 2026 (version 1.57.4 publiée sur npm) : README, référence de la CLI, documentation de configuration et code qui nomme les fichiers6.

ÉlémentFormat attendu par Backlog.mdCe que fait le script
Nom de fichieridentifiant en minuscules, « - », titre nettoyé (espaces en tirets, ponctuation retirée)Même règle de nettoyage, reprise de la fonction sanitizeFilename
En-tête YAMLid, title, status, assignee (liste), created_date, updated_date, labels, dependencies, references, priorityTous ces champs, dans cet ordre
DescriptionSection ## Description, entre marqueurs SECTION:DESCRIPTIONMarqueurs posés : un intertitre dans la description Jira ne coupe pas la section
StatutsTo Do, In Progress, Done par défautCorrespondance par catégorie de statut Jira, quel que soit le nom du statut

Les trois réglages :

  1. Le préfixe. Initialisez avec backlog init --task-prefix proj pour que les identifiants de Backlog.md soient vos clés Jira. Le préfixe n'accepte que des lettres et ne se change plus après l'initialisation : une clé de projet qui contient un chiffre demande de renuméroter. Plusieurs projets Jira dans un même repo demandent autant de préfixes, ce qu'un backlog Backlog.md n'offre pas ; un backlog par repo reste la règle.
  2. Les priorités. Backlog.md connaît High, Medium et Low par défaut, et les écrit en minuscules dans l'en-tête, comme le script. Si votre Jira utilise Highest, Lowest ou des priorités renommées, déclarez la liste dans le champ priorities du fichier de configuration ; elle se modifie à la main, pas par backlog config set.
  3. Le contrôle. Lancez backlog task list --plain : chaque ticket ouvert doit apparaître sous son statut. Les tickets archivés restent lisibles par backlog task view mais ne s'éditent plus, ce qui convient à un historique.

Ce qui casse à l'export

  • Une JQL non bornée. ORDER BY created seul renvoie une erreur 400. Ajoutez toujours un projet ou une autre restriction.
  • Les limites de débit. Sur des milliers de tickets, les appels de commentaires et de pièces jointes déclenchent des réponses HTTP 429. Atlassian demande d'attendre au moins la durée de l'en-tête Retry-After et d'espacer les nouvelles tentatives7 ; le script le fait, cinq fois au plus, avant d'abandonner.
  • Les champs oubliés. Sans fields, /search/jql ne renvoie que l'identifiant. Un champ personnalisé (points d'estimation, composant métier) doit figurer dans la liste par son identifiant customfield_….
  • Les médias collés dans le texte. Une capture collée dans la description est un nœud media qui référence un identifiant interne, pas un nom de fichier. Le script l'ignore dans le texte et liste les pièces jointes à part : relisez les tickets où l'image portait l'information.
  • Les mentions et les champs sensibles. L'export recopie noms, commentaires et pièces jointes dans le repo, qui hérite des droits du repo. Filtrez par JQL les tickets d'incident de sécurité ou de support client nominatif avant d'exporter.
  • Les fichiers lourds. Des centaines de captures et d'archives alourdissent l'historique git pour toujours. Placez backlog/assets/ sous Git LFS ou laissez les plus gros fichiers dans un stockage d'archive, avec un lien.

Questions fréquentes

Peut-on exporter Jira en Markdown sans script ?

Pas de façon exploitable par un agent. Les exports natifs de Jira produisent notamment du CSV ou du XML, sans un fichier par ticket. L'importateur de GitLab ne règle pas non plus la question : sa documentation indique que le texte des tickets Jira n'est pas converti en Markdown GitLab, ce qui peut casser la mise en forme8. Si votre cible est GitLab plutôt qu'un dossier du repo, voyez comment migrer vers GitLab Issues.

Le script fonctionne-t-il sur Jira Data Center ?

Pas tel quel. Data Center sert /rest/api/2/search, paginé par startAt et total, et renvoie du wiki markup. Le plus court est de demander expand=renderedFields, qui renvoie la description en HTML, puis de convertir ce HTML en Markdown avec un outil comme pandoc. Les dates de fin de Data Center sont détaillées dans notre page sur la fin de vie de Jira Data Center.

Faut-il exporter les tickets fermés ?

Oui, pour garder les décisions et les causes de bugs, mais à l'écart du backlog actif : le script les range dans backlog/archive/tasks/. Un agent qui liste les tâches ouvertes ne les charge pas ; il peut les retrouver par recherche quand un ticket ancien est cité.

L'export remplace-t-il le serveur MCP d'Atlassian ?

Non, il le complète. Le serveur MCP de Jira donne à l'agent un accès en direct à l'instance tant qu'elle reste la référence. L'export sert le jour où le repo devient la référence, ou pour figer un historique avant l'extinction d'une instance.

Ce que l'export vous laisse à faire

Un export propre ne règle que la reprise de l'existant. Il reste à décider qui écrit dans ces fichiers ensuite : une CLI ou un serveur MCP, jamais l'édition à la main, et une règle dans AGENTS.md ou CLAUDE.md qui demande aux agents de mettre à jour le ticket dans le même commit que le code. C'est le cœur de la trajectoire décrite dans notre analyse pour sortir de Jira, et de l'exemple de Warmtebouw, où toutes les écritures passent par une CLI typée et où « nobody edits these files by hand »9.

Sources

  1. Atlassian Developer, « The Jira Cloud platform REST API », groupe Issue search (/rest/api/3/search/jql, /rest/api/3/search/approximate-count) et spécification OpenAPI v3, consultées le 22 novembre 2026. developer.atlassian.com
  2. Atlassian Support, « Run JQL search query using Jira Cloud REST API », mis à jour le 5 décembre 2025, consulté le 22 novembre 2026. confluence.atlassian.com
  3. Atlassian Developer, « Atlassian Document Format », consulté le 22 novembre 2026. developer.atlassian.com
  4. Atlassian Support, « Manage API tokens for your Atlassian account », consulté le 22 novembre 2026. support.atlassian.com
  5. Atlassian, spécification OpenAPI de la Jira Cloud platform REST API v3 (/issue/{issueIdOrKey}/comment, /attachment/content/{id}), consultée le 22 novembre 2026. dac-static.atlassian.com
  6. Alex Gavrilescu, dépôt Backlog.md (README, CLI-INSTRUCTIONS.md, ADVANCED-CONFIG.md, src/file-system/operations.ts, backlog/config.yml), GitHub, consulté le 22 novembre 2026. github.com
  7. Atlassian Developer, « Rate limiting » (Jira Cloud platform), consulté le 22 novembre 2026. developer.atlassian.com
  8. GitLab Docs, « Migrate from Jira », consulté le 22 novembre 2026. docs.gitlab.com
  9. David Golverdingen, « We Replaced Jira With Markdown Files », 11 août 2026, mis à jour le 22 octobre 2026. davidgolverdingen.nl

Passer à l’action

Sortir de Jira : par où commencer ?

Un Diagnostic 10x part de votre instance Jira réelle (projets, champs, volumes, intégrations) et dit quoi exporter, où, et dans quel ordre.

Demander un Diagnostic 10x