Cómo automatizar un backlog de Jira Cloud con API y templates

Guia detallada

Este runbook explica como crear automáticamente un backlog o board de Jira Cloud usando la API REST y un template versionado en archivos.

La utilidad principal es simple: Jira permite trabajar con templates avanzados de proyecto, pero esa capacidad puede depender de features o planes pagos, como opciones enterprise o administración centralizada de templates. 

Cuando un equipo no tiene acceso a esa función, todavía puede automatizar gran parte del trabajo mediante la API de Jira, siempre que el proyecto y el board ya existan.

Con este enfoque, el equipo define el backlog una vez en un archivo fuente, lo revisa en control de versión, ejecuta un dry-run, y luego crea las Epics, Tasks, Stories y Subtasks de forma repetible. Esto evita cargar manualmente decenas o cientos de issues, reduce errores de copia, mantiene una referencia auditable del template y permite reutilizar el mismo baseline entre proyectos.

Este mecanismo no intenta reemplazar Jira Enterprise ni la administración formal de Jira. Es una alternativa pragmática para automatizar la carga inicial de trabajo cuando ya existe un proyecto Jira destino y el equipo tiene permiso para crear issues mediante la API.

Que se gana

• Crear boards/backlogs grandes sin carga manual issue por issue.

• Versionar templates en Git o en un repositorio compartido.

• Revisar el contenido antes de impactar Jira.

• Crear primero las Epics y luego el resto del backlog manteniendo relaciones parent.

• Reintentar una ejecución fallida sin duplicar issues ya creados.

• Compartir templates reutilizables entre equipos sin depender de una feature enterprise de Jira.

• Mantener evidencia del mapping entre Template ID y issue real de Jira.

Caso de uso

El flujo crea issues en un proyecto Jira existente:

• Epics primero.

• Stories, Tasks y Subtasks después.

• Relaciones parent entre Epics y tickets hijos.

• Relaciones parent entre Tasks/Stories y Subtasks.

• Descripciones enriquecidas con metadata del template, criterios de aceptación, Definition of Ready, Definition of Done y estimación original.

Ejemplo validado:

Jira Cloud URL: https://example.atlassian.net

Project key: ABC

Project ID: 1234

Board ID: 1234

Project name: Example Template Board

Issues creados: ABC-1 a ABC-127

Prerrequisitos en Jira

Antes de ejecutar el script, un administrador o responsable de Jira debe dejar preparado:

• Un proyecto Jira destino ya creado.

• Un board asociado al proyecto.

• Los issue types necesarios, por ejemplo, Epic, Task, Story y Subtask.

• Permisos para que el usuario del API token pueda crear issues.

• Jerarquía compatible para asociar Tasks/Stories a Epics mediante parent.

• Configuración de campos obligatorios compatible con el payload mínimo del script.

El script no reemplaza la administración inicial de Jira. Automatiza la carga del backlog/template dentro de un proyecto existente.

Archivos mínimos

Para ejecutar una implementación nueva se necesitan estos archivos:

create_jira_issues.py

validate_template.py

map_template.yaml

También se necesita una credencial local fuera del repositorio:

~/.jira/jira-template.env

Contenido esperado:

JIRA_BASE_URL=https://example.atlassian.net

JIRA_EMAIL=usuario@empresa.com

JIRA_API_TOKEN=token-atlassian

JIRA_PROJECT_KEY=ABC

Permisos recomendados:

chmod 600 ~/.jira/jira-template.env

Distribución del kit

Para compartir este material como Teratip interno, se puede publicar el runbook como página principal y adjuntar el archivo comprimido:

teratip-jira-template-kit.zip

Contraseña del ZIP:

jira

La contraseña evita que el contenido se extraiga sin conocerla. Según la herramienta ZIP usada, los nombres de archivos podrían seguir siendo visibles al listar el comprimido; por eso el ZIP no debe incluir tokens, credenciales, datos de clientes ni información sensible.

El ZIP debe contener solamente material reutilizable:

RUNBOOK.md

create_jira_issues.py

validate_template.py

map_template.yaml

template_source_example.md

Para adopción interna, conviene evaluar la creación de un repositorio GitHub de la empresa dedicado a templates de Jira. Eso permite versionar mejoras, recibir pull requests, mantener ejemplos por tipo de proyecto y publicar releases internas del kit.

Recomendaciones para ese repositorio:

• Usar un repositorio privado o interno si el contenido es para uso corporativo.

• No subir tokens, archivos .env, datos de clientes, proyectos reales, usuarios reales ni mappings de ejecución sensibles.

• Mantener el runbook y los scripts como código reutilizable.

• Mantener templates de ejemplo con datos ficticios.

• Publicar el ZIP como artefacto de release interna si se quiere facilitar la descarga.

Archivos recomendados, pero no obligatorios:

template_source_example.md

jira_create_results.json

RUNBOOK.md

jira_create_results.json no es fuente del template. Es el estado de ejecución y el mapping entre Template ID y issue real de Jira. Sirve para continuar con --skip-existing sin duplicar issues.

Fuente del template

La fuente estructurada actual es:

map_template.yaml

Aunque la extensión es .yaml, el archivo está escrito como JSON compatible con YAML. Esto evita dependencias externas como PyYAML y permite validación determinística con la librería estándar de Python.

El script también puede consumir un Markdown como fuente si el archivo contiene un bloque fenced jira-template:

```jira-template

{

  "template_name": "Example",

  "allowed_issue_types": ["Epic", "Story", "Task", "Sub-task"],

  "allowed_applicability": ["Core", "Conditional", "Optional", "Not Applicable"],

  "issues": []

}

```

Para un ejemplo completo y valido, usar:

template_source_example.md

Qué archivo debe crear el usuario

El usuario puede mantener el template de dos formas.

Opción recomendada para implementaciones reales:

map_template.yaml

Este archivo es la fuente estructurada principal. Es el formato más conveniente para automatización, validación, control de cambios y ejecución repetible.

Ejemplo:

python3 create_jira_issues.py --template map_template.yaml

Opción alternativa para documentación o capacitación:

template_source_example.md

Este formato sirve cuando se quiere explicar el template en lenguaje natural y guardar la estructura dentro de un bloque fenced jira-template.

Ejemplo:

# Template de proyecto

Descripción del alcance, convenciones y uso.

```jira-template

{

  "template_name": "Template de proyecto",

  "issues": []

}

```

Ejecución:

python3 create_jira_issues.py --template template_source_example.md

No usar como fuente automática un Markdown visual generado para revisión humana. Ese tipo de archivo sirve como preview del board, pero no es una fuente robusta para automatización.

Crear token de API

1. Entrar a https://id.atlassian.com/manage-profile/security/api-tokens.

2. Crear un token con un nombre claro, por ejemplo, jira-template-import.

3. Copiar el token una sola vez.

4. Guardarlo en ~/.jira/jira-template.env.

5. No commitear el token al repositorio.

El token no crea una conexión persistente tipo SSH. Es una credencial reutilizable hasta su vencimiento o revocación. Cada ejecución del script la usa para autenticarse contra Jira.

Validar acceso

Desde la carpeta del template:

python3 create_jira_issues.py --check

Salida esperada:

Project: ABC - Example Template Board

Issue types: Epic, Subtask, Task, Story, Feature, Bug

Si falla por certificados SSL en macOS, usar el bundle de certifi:

export SSL_CERT_FILE="$(python3 -c 'import certifi; print(certifi.where())')"

python3 create_jira_issues.py --check

Dry-run

Antes de crear issues, ejecutar siempre:

python3 create_jira_issues.py

Esto imprime el orden de creación sin modificar Jira.

Para revisar solo las primeras 23 operaciones:

python3 create_jira_issues.py --limit 23

En el template MAP, esas primeras 23 operaciones son las Epics.

Crear Epics primero

Crear solo Epics:

python3 create_jira_issues.py \

  --execute \

  --limit 23 \

  --results jira_create_results.json

El resultado guarda el mapping:

{

  "TPL-01-EP": "ABC-1",

  "TPL-02-EP": "ABC-2"

}

Revisar Jira antes de continuar. Confirmar que las Epics se ven correctamente en el proyecto/board.

Crear el resto del board

Cuando las Epics ya existen y el mapping esta guardado:

python3 create_jira_issues.py \

  --execute \

  --skip-existing \

  --results jira_create_results.json

--skip-existing carga el mapping existente y no recrea los Template ID ya creados. Esto permite continuar en dos fases:

1. Crear Epics.

2. Crear Stories, Tasks y Subtasks.

Reintentos

Si una ejecución falla a mitad de camino:

1. No borrar jira_create_results.json.

2. Corregir el problema.

3. Reejecutar con:

python3 create_jira_issues.py --execute --skip-existing

El script saltará los issues ya creados y continuará con los pendientes.

Usar otro proyecto o template

Otro proyecto:

python3 create_jira_issues.py \

  --project-key ABC \

  --check

Otro archivo fuente:

python3 create_jira_issues.py \

  --template template_source_example.md

Usar un archivo de resultados separado por proyecto o cliente:

python3 create_jira_issues.py \

  --execute \

  --results results-cliente-abc.json

Limitaciones conocidas

• El script crea issues; no crea proyectos Jira ni boards.

• El usuario/API token necesita permiso Create Issues en el proyecto.

• Jira Cloud team-managed usa parent para colgar Stories/Tasks de Epics.

• En proyectos company-managed puede existir comportamiento legacy con Epic Link; ese caso puede requerir mapeo adicional de campos custom.

• El script no configura workflows, estados, columnas, permisos, sprints ni releases.

• La estimación original se carga en la descripción si Jira no expone un campo nativo editable de estimación.

• Los componentes solo deben enviarse con --components si ya existen en Jira.

• La prioridad solo se envía con --priority si el proyecto acepta ese campo.

Recomendaciones de uso comunitario

• Mantener un template base sin datos confidenciales.

• Crear una copia por cliente/proyecto.

• Usar placeholders como <CLIENT_NAME>, <PROJECT_NAME>, <ENVIRONMENT> y <TARGET_DATE>.

• Hacer dry-run y revisión del Markdown visual antes de crear issues.

• Crear Epics primero y revisar.

• Crear el resto con --skip-existing.

• Guardar el results.json del proyecto como evidencia operativa, si no contiene información sensible.

• No guardar tokens dentro del repositorio.

Archivos del kit

map_template.yaml             Fuente estructurada de ejemplo

template_source_example.md    Fuente Markdown de ejemplo

validate_template.py          Validador estructural

create_jira_issues.py         Ejecutor Jira API

jira_create_results.json      Mapping real Template ID -> Jira key, generado en ejecución

Silvio Depetri

Cloud Engineer