Exportar el estado

ajat export escribe cada regla de Automation de tu tenant de Jira Cloud en un árbol de directorios de archivos JSON consciente del alcance, más un archivo de estado que impulsa las reejecuciones incrementales. El objetivo no es solo la recuperación ante desastres: la exportación se convierte en el inventario base para entender cómo está distribuido Jira Automation entre los alcances global, de proyecto, multiproyecto y otros.

Este es el flujo operativo principal de ajat y la base sobre la que se construyen los demás comandos. Los informes, diff, search y las operaciones masivas de rule leen todos el árbol local que produce este comando.

Los sitios grandes de Jira suelen acumular automatización durante años. Distintos equipos crean reglas, las copian entre proyectos y las amplían a alcance multiproyecto o global a medida que crecen los procesos de negocio. ajat export captura ese estado completo en una única ejecución repetible para que los equipos puedan revisar la malla de automatización desde disco en lugar de saltar entre pantallas de administración de proyectos.

Primera exportación

ajat export --output-dir ./jira-automations-backup

--output-dir es obligatorio y debe indicarse explícitamente. El comando primero página el endpoint de resumen de reglas de Automation de Jira para construir la lista de trabajo completa y luego descarga cada regla de forma concurrente.

🔍 Fetching rules...
  📥 Fetched 100 rule(s)...
  📥 Fetched 200 rule(s)...
  ...
  📥 Fetched 951 rule(s) ✅
Discovered 951 rule(s)
Exporting rules ... 23.66% [225 in 2.1s; ~ETA: 7s]

El banner de descubrimiento, la barra de progreso por regla y las líneas de estado por regla van todas a stderr, por lo que redirigir stdout (por ejemplo a tee, jq o un archivo) se mantiene limpio.

Estructura en disco

Las reglas se escriben en un árbol consciente del alcance para que puedas responder preguntas básicas de gobernanza antes de abrir un informe: qué reglas son globales, qué proyectos tienen reglas locales, qué automatizaciones abarcan más de un proyecto y qué definiciones requieren una inspección más detallada.

<output-dir>/
├── .ajat_state.json                                    # estado incremental
├── .ajat_external_directory.json                       # directorio de cuentas y fotos (omitido con --resolve-users=false)
├── .ajat_projects.json                                 # catálogo de proyectos: tipo, estilo e icono de cada proyecto al que apuntan las reglas
├── .ajat_audit_stats.json                              # estadísticas de ejecución (solo tras `ajat audit-log import` o `fetch`)
├── global/
│   └── <uuid>__<rule-name>.json                        # reglas sin ARI de alcance
├── projects/
│   └── <KEY>__<Project-Name>/
│       ├── <uuid>__<rule-name>.json                    # reglas de un solo proyecto
│       ├── <uuid>__<rule-name>.external-info.json      # identidades resueltas (omitido con --resolve-users=false)
│       └── <uuid>__<rule-name>.ops-info.json           # tamaños de búsqueda (solo con --probe-jql)
├── multi-project/
│   └── <KEY1>__<Name1>__<KEY2>__<Name2>__and-N-more/
│       └── <uuid>__<rule-name>.json                    # reglas multiproyecto
└── other-scope/
    └── <uuid>__<rule-name>.json                        # reglas con ARI de alcance no de proyecto

Los nombres de archivo se normalizan (NFKD a ASCII, caracteres especiales a -) para que el árbol sea seguro en Linux y macOS.

Para las reglas multiproyecto, las etiquetas de proyecto en el nombre del directorio se ordenan alfabéticamente. La API de Atlassian no garantiza un orden estable para ruleScopeARIs entre respuestas, así que el ordenamiento hace la ruta determinista entre ejecuciones — que es también lo que hace funcionar el salto incremental.

Modos incremental y sync

Reejecutar con el mismo --output-dir solo vuelve a descargar las reglas cuyo timestamp updated ha cambiado en el listado upstream. Las reglas ya en disco con el mismo updated se omiten. Dos flags mutuamente excluyentes controlan cómo se tratan las reglas que han desaparecido del listado upstream:

# Predeterminado: incremental, conserva en disco las reglas eliminadas para auditoría
ajat export --output-dir ./jira-automations-backup
 
# Modo sync: refleja upstream exactamente, incluidas las eliminaciones
ajat export --output-dir ./jira-automations-backup --sync
 
# Desactiva el estado por completo: redescarga cada regla, sin reconciliación de huérfanos
ajat export --output-dir ./jira-automations-backup --sync=false --incremental=false

El --incremental por defecto conserva en disco los archivos con tumba porque la automatización eliminada puede formar parte de la historia de auditoría — un flujo que cambia, un proyecto que se retira, una limpieza que hay que revisar. Cambia a --sync cuando quieras que el árbol en disco refleje Jira exactamente, por ejemplo cuando la exportación alimenta un pipeline downstream que nunca debería ver reglas obsoletas.

Elegir un modo

El archivo de estado

El archivo de estado (.ajat_state.json) registra qué se descargó, cuándo y con qué resultado. Se escribe como una sola línea de JSON, lo que lo mantiene amigable con git diff y con herramientas grep que esperan un registro por línea.

Cuando --sync o --incremental está activo, el bloque de resumen final imprime la ruta resuelta del archivo de estado, para que sea fácil copiarla a un depurador o a un comando grep:

Export complete
  discovered : 951
  downloaded : 12
  skipped    : 939
  failed     : 0
  deleted    : 0
  elapsed    : 8.3s
  output     : /Users/me/jira-automations-backup
  state file : /Users/me/jira-automations-backup/.ajat_state.json
  external   : /Users/me/jira-automations-backup/.ajat_external_directory.json

La línea state file se omite cuando el seguimiento de estado está desactivado (--sync=false --incremental=false). La línea external se muestra solo cuando se solicitó --resolve-users.

Por defecto el archivo de estado vive en <output-dir>/.ajat_state.json. Anula su ubicación con --state-file solo si necesitas un estado no colocado junto a la salida.

Reanudabilidad

.ajat_state.json se reescribe de forma atómica (archivo temporal y luego rename(2)) después de cada regla que el exportador procesa — descarga correcta, fallo o reclasificación de alcance. No hay un volcado de fin de ejecución que puedas perder: si pulsas Ctrl-C, o el proceso se termina, o el portátil se queda sin batería, cada regla que terminó está de forma duradera en disco con status: "downloaded", y la siguiente ejecución la omite.

Las reglas que terminaron en status: "failed" se reintentan en la siguiente ejecución. El reintento conserva el campo last_error previo en el estado hasta que la regla tiene éxito, por lo que el archivo de estado es también el registro de auditoría de lo que está roto actualmente.

¿Por qué se está redescargando una regla?

Si esperabas que una reejecución incremental omitiera casi todo y el contador de descargas sube rápido, pasa -v (--debug-changes). Cada regla que falla la comprobación de salto se imprime con el motivo exacto:

↻ redownloading "Triage Bugs" — updated 1.6739e+09 → 1.6741e+09
↻ redownloading "Onboarding" — path projects/X/... → projects/Y/...
↻ redownloading "Audit Log" — local file missing
↻ redownloading "Send Slack" — prior status: failed

Deja -v desactivado en ejecuciones rutinarias — el conteo en curso y el resumen final son suficientes — y actívalo al investigar rotación.

Resolver identidades de usuario

Cada regla exportada está llena de account ID opacos de Jira — el autor de la regla, la identidad con la que se ejecuta (actor), sus colaboradores y cualquier account ID enterrado en la configuración de los componentes. Por sí solos se leen como 712020:9c32… y no dicen nada.

ajat los convierte en identidades legibles automáticamente. --resolve-users está activado por defecto, porque los nombres resueltos son lo que hace realmente legibles la copia de seguridad y los informes:

# La resolución se ejecuta como parte de una exportación normal — sin flag extra.
ajat export --output-dir ./jira-automations-backup
 
# Desactívala cuando solo quieras el JSON crudo de las reglas, o el token carezca
# del scope read:jira-user:
ajat export --output-dir ./jira-automations-backup --resolve-users=false
 
# Conserva las identidades pero omite las fotos:
ajat export --output-dir ./jira-automations-backup --avatars=false

Cuando está activado, una fase posterior a la descarga recopila cada account ID distinto referenciado a lo largo de la ejecución, los resuelve en una única pasada por lotes, concurrente y cacheada (un tenant con cientos de reglas pero un puñado de cuentas distintas cuesta aproximadamente un viaje de ida y vuelta) y escribe las identidades resueltas junto a cada regla. Con --avatars (activado por defecto) también descarga la foto de 48×48 de cada cuenta resuelta, para que los informes muestren caras sin conexión; la descarga va a la CDN pública de avatares de Atlassian o a Gravatar, y las credenciales se envían únicamente a tu propio sitio, nunca a esos hosts. El JSON de la regla exportada nunca se modifica, por lo que la copia de seguridad sigue siendo una copia byte a byte de lo que Jira devolvió.

Se producen dos tipos de archivo:

• Sidecar por regla <uuid>__<rule-name>.external-info.json, escrito junto a la regla que describe. Registra el autor de la regla, el actor, los colaboradores y las referencias de componentes, cada uno con el nombre resuelto, el tipo de cuenta (atlassian / app / customer), el indicador de actividad y — donde aparece — la ruta JSON dentro de la regla. Los sidecars se imprimen con formato porque están pensados para leerse a mano junto a cada regla.
• Índice de directorio .ajat_external_directory.json en la raíz de salida: un mapa accountId → identity a nivel de tenant más un conteo por cuenta de cuántas reglas la referencian, para que los informes y las herramientas puedan responder “¿quién posee más automatización?” sin abrir cada sidecar. También es donde vive la foto de cada cuenta, como una data URI avatarData de unos 4 KB — una vez por cuenta, nunca en los sidecars — que es lo que permite a los informes mostrar caras sin descargar nada. Pasa --avatars=false para conservar las identidades y dejar fuera las fotos. Como .ajat_state.json, se escribe como una sola línea de JSON.

Los account ID que la API no puede resolver — cuentas desactivadas, eliminadas o de app que el token no puede ver — se registran como marcadores no resueltos ("resolved": false) en lugar de hacer fallar la ejecución. El enriquecimiento es aditivo, idempotente y reejecutable: cada archivo lleva un schemaVersion y una marca de tiempo resolvedAt, así que reejecutar --resolve-users refresca los nombres cambiados sin volver a descargar reglas. Cualquier fallo de enriquecimiento se registra pero nunca hace fallar la copia de seguridad — el JSON de la regla ya está a salvo en disco para entonces.

Todos los informes recogen estos archivos: nombres resueltos de actor y autor con sus fotos, un panel de Top authors, filas de Author / Collaborators por regla y los hallazgos de propiedad de los informes de consistencia y riesgo. Las copias de seguridad exportadas sin --resolve-users se renderizan con IDs de cuenta en bruto. Ejecuta ajat export una vez para incorporar las fotos a una copia de seguridad anterior a su existencia.

El catálogo de proyectos

Cada ejecución escribe también .ajat_projects.json en la raíz de salida: una entrada por cada proyecto al que apuntan las reglas, con su id, clave, nombre, tipo (software, business, service_desk) y estilo (classic para los gestionados por la empresa, next-gen para los gestionados por el equipo). No cuesta ninguna llamada extra a la API — el exportador ya recupera cada proyecto para nombrar su directorio de scope — y se escribe con o sin --resolve-users. Los informes usan el tipo y el estilo para enlazar cada regla con su propia página en Jira, que vive bajo la configuración del proyecto y cuya ruta depende de ambos (consulta Enlaces a Jira).

Con --avatars el catálogo lleva además el icono de cada proyecto (iconData, un PNG de aproximadamente 1 KB descargado del endpoint de avatares de tu propio sitio), para que los chips de proyecto de todos los informes lo muestren. Un icono que ya estaba en el catálogo anterior para la misma URL se reutiliza.

Flags comunes

Enmascarar campos sensibles

--redact-sensitive-fields pide a Jira que enmascare los campos que considera secretos en el JSON de la regla devuelto. No confíes en ello: en una exportación real dejó intactas todas las URLs de webhook que llevaban una clave y un token. Trata el directorio de exportación como confidencial con o sin el flag, y usa el hallazgo Secretos expuestos del informe de riesgo para encontrar las reglas que contienen una credencial (consulta Compartir informes de forma segura).

Informe de progreso

La etiqueta de progreso se actualiza en el sitio con el conteo en curso:

Exporting · ↓12 skip 939 fail 0 ... 99%

• ↓N — reglas obtenidas de la API de Automation en esta ejecución.
• skip N — reglas cuyo estado las mostró sin cambios y cuyo archivo JSON local sigue en disco.
• fail N — reglas donde la llamada a la API o la escritura local falló.

Cuando --resolve-users está activo la ejecución tiene dos fases — descargar reglas y luego resolver las cuentas que referencian — y el display muestra tres barras juntas: un agregado combinado Overall, el rastreador de descargas Automations y el rastreador de enriquecimiento External info. Las tres se crean por adelantado para que el display nunca colapse entre fases.

Todo se renderiza a stderr. Suprime la barra de progreso y las líneas de descubrimiento por página por completo con el flag persistente --no-progress — útil para logs de CI/CD, scripting y grabaciones de terminal. Cada transición por regla también se registra como un evento estructurado cuando --log-file está definido, así que desactivar la barra nunca pierde información visible para el operador.

Medir el tamaño de las búsquedas

Una búsqueda programada o una rama JQL vuelve a ejecutar los pasos posteriores por cada work item que devuelve, así que su tamaño decide cuánto cuesta una regla y si Jira la limita. El JSON de la regla solo contiene el JQL, no su tamaño. Pasa --probe-jql para preguntárselo a Jira:

ajat export --output-dir ./jira-automations-backup --probe-jql

Tras la descarga (y la resolución de identidades), la exportación:

1. recopila las búsquedas que se abren en abanico: cada disparador JQL programado que no está limitado a «work items que han cambiado desde la última ejecución», y cada rama JQL, a cualquier profundidad;
2. envuelve cada una en el scope de proyecto de la regla, project in (<ids>) AND (<jql>), porque Jira ejecuta el JQL de una regla con scope de proyecto dentro de sus proyectos, y contar el JQL sin más contaría todo el sitio;
3. cuenta cada consulta distinta una sola vez mediante POST /rest/api/3/search/approximate-count (las reglas copiadas entre proyectos suelen compartir consulta);
4. escribe un sidecar <uuid>__<rule-name>.ops-info.json junto a la regla, con cada búsqueda, la consulta contada y su recuento.

El resumen gana una línea:

  jql probe  : 28 searches counted across 35 rules

Qué significan los recuentos:

• Son la estimación de Jira y pueden ir por detrás de ediciones muy recientes.
• Cuentan lo que tu cuenta puede ver. Una regla que se ejecuta como otra cuenta puede ver más o menos work items.
• Las búsquedas con smart values ({{issue.key}}, {{lookupIssues.key}}) solo tienen valor mientras se ejecuta la regla; se registran como dinámicas y no se cuentan.
• Jira se niega a contar una búsqueda sin ninguna restricción (una consulta vacía o un ORDER BY a secas); se registra como sin límite.
• Un recuento fallido nunca hace fallar la exportación. Se registra con el error de Jira en el campo error del sidecar, y el informe de riesgo recurre a leer el JQL de esa búsqueda. Las causas habituales son un JQL que ya no es válido (un campo renombrado, un proyecto eliminado) y errores transitorios; vuelve a ejecutar la exportación para reintentar.

ajat report risk lee los sidecars. Una búsqueda contada de más de 1000 work items se señala con su tamaño real, una sin límite se señala como tal, y una búsqueda contada por debajo de 1000 no se señala sea cual sea el aspecto de su JQL. Sin --probe-jql el informe recurre a leer el texto JQL (consulta Risk). En un inventario real de 654 reglas, el texto por sí solo señaló nueve búsquedas; la sonda mostró que ocho de ellas coincidían con entre 0 y 46 work items, y confirmó la novena en 3.588. La sonda está desactivada por defecto y cuesta una petición por búsqueda distinta.

Como los sidecars de identidad, los archivos ops-info nunca se importan como reglas, se refrescan en cada ejecución con sonda, se eliminan cuando una regla ya no tiene una búsqueda que contar y se borran con su regla bajo --sync.

Límites de tasa y concurrencia

La API de Automation de Atlassian limita la tasa por tenant. ajat export está diseñado para replegarse limpiamente en lugar de reventar la ejecución:

• Se respeta Retry-After. Un 429 pausa la petición ofensora durante la duración de reloj indicada (más jitter, con tope de 120 segundos por espera), luego reintenta, con un presupuesto acumulado de reintentos de 5 minutos por petición y un cinturón de seguridad de 60 intentos.
• Una compuerta de repliegue compartida aparca a todos los workers en el mismo muro. Cuando un worker es limitado, los workers paralelos esperan al mismo plazo en lugar de martillar la API en sincronía. Esto es lo que hace seguros los valores altos de --workers.
• X-RateLimit-NearLimit: true dispara un colchón preventivo — el pool se ralentiza durante unos 750 ms para evitar caer en una oleada de 429.
• Los errores 5xx y de red reintentan de forma independiente con backoff exponencial con jitter, hasta cuatro intentos por petición.

El --workers 4 por defecto coincide con el perfil de baja concurrencia recomendado por Atlassian. Los tenants sanos suelen poder subirlo a --workers 16 sin ver 429; los tenants muy grandes o restringidos deberían considerar --workers 2. El exportador es totalmente reanudable — mata la ejecución, baja el número de workers y relánzala con el mismo --output-dir para retomar donde lo dejaste.

Códigos de salida

Exportaciones programadas

ajat export es seguro de ejecutar desde cron, GitHub Actions o cualquier otro planificador. Como es incremental y reanudable por defecto, un trabajo recurrente mantiene un inventario actualizado de forma barata.

# .github/workflows/jira-automations-backup.yaml
on:
  schedule: [{ cron: "0 4 * * *" }]   # 04:00 UTC diario
  workflow_dispatch:
 
jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - run: |
          # La URL de descarga viene de tu correo de pedido de Climakers; guárdala como secreto de CI.
          curl -sL "${{ secrets.AJAT_DOWNLOAD_URL }}" -o ajat.zip
          unzip ajat.zip && chmod +x ajat && sudo mv ajat /usr/local/bin/
      - run: ajat export --output-dir ./jira-automations-backup --workers 16 --redact-sensitive-fields --no-progress
        env:
          AJAT_JIRA_DOMAIN:    ${{ secrets.AJAT_JIRA_DOMAIN }}
          AJAT_JIRA_USERNAME:  ${{ secrets.AJAT_JIRA_USERNAME }}
          AJAT_JIRA_API_TOKEN: ${{ secrets.AJAT_JIRA_API_TOKEN }}
      - uses: actions/upload-artifact@v6
        with: { name: jira-automations-backup, path: ./jira-automations-backup/ }

Empareja el artefacto exportado con un trabajo downstream que ejecute Informes HTML o Comparar snapshots cuando necesites una vista fresca para revisiones de plataforma, reuniones de comité de cambios o evidencia de cumplimiento.

Lo que NO se exporta

• Historial de ejecución de reglas. Jira retiene aproximadamente 90 días de registro de auditoría, y no forma parte de la definición de la regla. ajat audit-log lo incorpora por separado, como estadísticas por regla para el informe de riesgo, desde la exportación CSV de Jira o directamente del registro (experimental).
• Configuración de workflow, proyecto o tablero. ajat se limita a reglas de Automation.
• Esquemas de campos personalizados. El JSON completo de la regla referencia IDs de campos personalizados pero no lleva sus esquemas.

Relacionado

• Instalación y configuración inicial — desde la instalación hasta tu primera exportación.
• Informes HTML — convierte el árbol de exportación en informes de inventario, colisión, consistencia, riesgo y workflow.
• Historial de ejecución de reglas — importa o descarga el registro de auditoría de Jira para que el informe de riesgo vea cómo se ejecutan realmente las reglas.
• Comparar snapshots — compara dos directorios de exportación para revisión de deriva y compuertas de CI.
• Operaciones masivas de reglas — ejecuta selectores de etiqueta, nombre, alcance y estado contra un directorio de exportación.
• Importar y restaurar — envía un árbol de exportación de vuelta a Jira, de forma segura y con plan primero.
• Configuración — precedencia, variables de entorno y ajustes de proxy.