Flujos y comandos

Esta página reúne recetas de ajat con estilo de producción y secuencias de comandos completas, para equipos que necesitan operaciones repetibles a escala de patrimonio, no solo ejemplos aislados de comandos. Cada receta sigue la misma disciplina: validar, descubrir el alcance, exportar o inspeccionar, y ejecutar la operación de mayor impacto solo después de que el operador pueda ver el plan.

Si todavía no has completado la configuración inicial, empieza por Instalación y configuración inicial. Vuelve aquí cuando el puesto, la licencia y el acceso a Jira Cloud ya estén validados con ajat doctor.

ajat opera únicamente sobre Atlassian Jira Cloud Automation. No es compatible con Jira Server ni Jira Data Center.

Descubrimiento de comandos en un tenant nuevo

La forma más segura de explorar un tenant que no has operado antes es validar, luego mirar, luego leer y luego planificar.


ajat doctor                                        # config, licencia, credenciales, acceso a la API
ajat tree --short                                  # familias de comandos disponibles
ajat search --limit 10                             # confirma que la cuenta puede leer resúmenes de reglas
ajat export --output-dir ./jira-automations-backup # crea el catálogo local
ajat report inventory --input-dir ./jira-automations-backup --output-file inventory.html

Solo después de revisar el informe de inventario deberías recurrir a ajat diff, ajat rule o ajat import con --dry-run.

Revisión trimestral de toda la organización

Usa este flujo cuando un responsable de gobernanza necesita una imagen completa y compartible del patrimonio de automatización: qué existe, qué es arriesgado, qué está duplicado y qué hay que limpiar.


ajat doctor --output-dir ./reviews/q2
ajat export --output-dir ./reviews/q2 --redact-sensitive-fields
 
ajat report inventory   --input-dir ./reviews/q2 --output-file q2-inventory.html
ajat report collision   --input-dir ./reviews/q2 --output-file q2-collisions.html
ajat report consistency --input-dir ./reviews/q2 --output-file q2-consistency.html
ajat report risk        --input-dir ./reviews/q2 --output-file q2-risk.html

Cómo leer las salidas:

Inventory es la línea base — cada regla por ámbito, con diagramas de flujo por regla y la huella de integración de cada servicio externo al que llega el patrimonio.
Risk prioriza lo que requiere atención: fallos silenciosos, propiedad huérfana, secretos expuestos, reglas antiguas pero habilitadas, y las programaciones, disparadores y búsquedas que disparan el coste de la automatización, puntuado de A a F y atribuido por proyecto.
Collision aflora candidatas a consolidación — reglas casi duplicadas copiadas y pegadas entre proyectos.
Consistency señala higiene de nombres, etiquetas y propiedad que conviene limpiar.

Los informes enmascaran las credenciales que citan, y el informe de riesgo lista las reglas que llevan alguna. --redact-sensitive-fields pide a Jira que haga lo mismo en el JSON exportado, pero deja intactos las claves y los tokens de webhook, así que trata el directorio de la revisión como confidencial. Consulta Compartir informes de forma segura.

Revisión del coste de automatización

Ejecútala antes de un ciclo de facturación, o cuando la página de consumo de Jira suba. Jira factura la automatización por pasos — cada disparador, condición, acción e iteración de rama que se ejecuta — y la página de consumo da el total sin decir por qué.


ajat export --output-dir ./reviews/cost --probe-jql
ajat audit-log import --input-dir ./reviews/cost ~/Downloads/automation-audit-logs-*.csv   # o: ajat audit-log fetch (experimental)
ajat report risk --input-dir ./reviews/cost --output-file cost-risk.html --state enabled

Con el registro de auditoría importado o descargado, empieza por Reglas más activas: una regla que se ejecuta miles de veces y casi nunca realiza una acción es el ahorro más barato. Ejecuciones limitadas son reglas que Jira ya está deteniendo.

Después toma los hallazgos de coste de severidad alta: Programaciones por debajo de la hora, Disparador amplio entre proyectos y Búsquedas sin límite (cada búsqueda de más de 1000 work items se lista con su tamaño real, medido con --probe-jql). Después revisa Disparadores amplios y Búsquedas y peticiones web en cada ejecución. Las correcciones típicas son una programación más espaciada, un disparador más estrecho (un campo concreto en lugar de cualquier cambio), una ventana temporal en el JQL (updated >= -1d) o «incluir solo work items que hayan cambiado desde la última ejecución» en una búsqueda programada.

Consulta Historial de ejecución de reglas para las dos formas de incorporar el registro de auditoría, y Risk para cada hallazgo y sus puntos.

Barrido de secretos


ajat export --output-dir ./reviews/secrets
ajat report risk --input-dir ./reviews/secrets --output-file secrets.html

Abre Secretos expuestos. Cada entrada dice qué tipo de secreto contiene una regla y dónde — por ejemplo, una clave y un token de webhook de Google Chat en la URL de una petición web — nunca el valor. Rota cada uno, muévelo después al almacén de secretos de Jira y referéncialo como smart value. Vuelve a ejecutar el barrido para confirmar que la lista está vacía. Protege el propio directorio de exportación: el JSON de las reglas en disco sigue conteniendo todos los secretos, y --redact-sensitive-fields no los elimina. En un inventario real de 654 reglas, solo este hallazgo listó 175 reglas.

Gate diario de drift en CI

Usa este flujo para hacer fallar un pipeline (o simplemente alertar) cuando el patrimonio de automatización en vivo se desvía de una línea base revisada.


ajat export --output-dir ./current --no-progress
ajat diff ./baseline ./current --check

ajat diff --check devuelve un código de salida distinto de cero cuando encuentra diferencias, y eso es lo que lo convierte en un gate. Guarda las credenciales de Jira como secretos de CI y usa logging estructurado para el registro de la ejecución:


export AJAT_JIRA_DOMAIN=acme.atlassian.net
export AJAT_JIRA_USERNAME=$JIRA_USER
export AJAT_JIRA_API_TOKEN=$JIRA_TOKEN
 
ajat export --output-dir ./current --no-progress \
  --log-file ./ajat.log --log-format json
ajat diff ./baseline ./current --check

Las ejecuciones recurrentes y desatendidas corresponden a la edición de licencia CI/CD Automation. Compara ediciones en la página del producto ajat y consulta Licenciamiento para la variante CI/CD.

Cuando el gate se dispara, promociona la exportación revisada para que sea la nueva línea base, de modo que la siguiente ejecución compare contra un estado aprobado.

Pausa y recuperación ante incidentes

Usa este flujo para pausar rápidamente todas las reglas de un ámbito de proyecto afectado durante un incidente, y volver a habilitarlas limpiamente una vez resuelto. Cada mutación se previsualiza con --dry-run antes de aplicarse.


# 1. Toma una exportación antes de tocar nada — es tu evidencia y punto de retorno.
ajat export --output-dir ./incident-snapshot
 
# 2. Previsualiza la pausa, acotada al proyecto afectado.
ajat rule disable --input-dir ./incident-snapshot \
  --scope ari:cloud:jira:<tenant>:project/ALPHA \
  --dry-run
 
# 3. Aplica la pausa.
ajat rule disable --input-dir ./incident-snapshot \
  --scope ari:cloud:jira:<tenant>:project/ALPHA \
  --yes

Una vez resuelto el incidente, refresca el catálogo y vuelve a habilitar el mismo ámbito:


ajat export --output-dir ./incident-snapshot
ajat rule enable --input-dir ./incident-snapshot \
  --scope ari:cloud:jira:<tenant>:project/ALPHA \
  --yes

Las operaciones masivas de reglas seleccionan contra una exportación local auditable, no contra una consulta invisible al servidor. Consulta Operaciones masivas de reglas para el conjunto completo de selectores (UUID, etiqueta, glob de nombre, autor, ámbito, estado).

Recuperación ante desastres en el mismo tenant

Usa este flujo cuando una regla se ha dañado o borrado y necesitas restaurar el último estado fiable en el mismo tenant, conservando los UUID originales para que las referencias externas sigan funcionando.


# 1. Previsualiza la restauración.
ajat import --input-dir ./last-known-good --dry-run
 
# 2. Aplícala (por defecto --uuid-strategy=preserve conserva los UUID originales).
ajat import --input-dir ./last-known-good --yes
 
# 3. Verifica exportando el estado actual y comparándolo con la exportación.
ajat export --output-dir ./post-restore
ajat diff ./last-known-good ./post-restore

Un diff limpio tras la restauración es tu evidencia de que el tenant coincide ahora con la exportación que importaste. Consulta Importar y restaurar para el plan, el fichero de estado y la estrategia de UUID.

Promoción de sandbox a producción

Usa este flujo para promocionar a producción reglas validadas en un tenant de sandbox. Los UUID nuevos evitan colisiones y --scope-map reescribe cada ARI de proyecto de sandbox a su equivalente de producción.


# 1. Dry-run para confirmar el plan y el número de entradas de scope-map.
ajat import --input-dir ./sandbox-export --uuid-strategy=new \
  --scope-map ari:cloud:jira:sandbox:project/APP=ari:cloud:jira:prod:project/APP \
  --dry-run
 
# 2. Aplica la promoción.
ajat import --input-dir ./sandbox-export --uuid-strategy=new \
  --scope-map ari:cloud:jira:sandbox:project/APP=ari:cloud:jira:prod:project/APP \
  --yes
 
# 3. Exporta producción después y guárdalo como evidencia.
ajat export --output-dir ./post-promotion

Usa una entrada --scope-map por cada ARI de proyecto que difiera entre el tenant de origen y el de destino. El plan del dry-run indica el número de entradas activas para que confirmes que se ha cargado el número correcto de mapeos antes de aplicar.

Limpieza de reglas deshabilitadas obsoletas

Usa este flujo para eliminar de forma permanente reglas que se deshabilitaron y se marcaron para retirada. El borrado solo se permite en reglas DISABLED, así que las candidatas habilitadas se deshabilitan primero.


ajat export --output-dir ./jira-automations-backup
 
ajat rule delete --input-dir ./jira-automations-backup \
  --label deprecated \
  --state DISABLED \
  --dry-run
 
ajat rule delete --input-dir ./jira-automations-backup \
  --label deprecated \
  --state DISABLED \
  --yes

Si las reglas marcadas como deprecated siguen habilitadas, deshabilítalas primero, refresca la exportación y luego borra:


ajat rule disable --input-dir ./jira-automations-backup --label deprecated --yes
ajat export --output-dir ./jira-automations-backup
ajat rule delete --input-dir ./jira-automations-backup --label deprecated --state DISABLED --yes

Como alternativa durante una restauración, ajat import --prune elimina las huérfanas DISABLED que están ausentes de una exportación de origen fiable.

Invocar una regla manual para triaje

Usa este flujo para descubrir y ejecutar una regla de disparo manual contra un objetivo concreto — por ejemplo, retriar una incidencia durante un incidente.


ajat rule manual list --target PROJ-123
 
ajat invoke <rule-uuid> \
  --target PROJ-123 \
  --input reason="re-triage" \
  --dry-run
 
ajat invoke <rule-uuid> \
  --target PROJ-123 \
  --input reason="re-triage" \
  --yes

Consulta Invocar reglas manuales para los ARI de objetivo, la resolución de claves de incidencia y el JSON de entrada tipado.

Secuencia recomendada para una ejecución con cliente

confirmar el puesto con ajat doctor
descubrir el alcance con ajat search y una primera ajat export
construir los informes que necesita la audiencia (inventory como línea base, risk para priorizar)
seguir los cambios a lo largo del tiempo con ajat diff entre exportaciones
tratar cada mutación como plan-first — --dry-run, lee el plan y luego --yes

Trata tu automatización como si fuera código fuente. Tómale una exportación de forma periódica, compara las exportaciones y conserva los artefactos. El diff es tu respuesta cuando “nadie cambió nada”, y la copia de seguridad es tu deshacer cuando una regla se borra por error.