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, reglas antiguas pero habilitadas y planificaciones de alta frecuencia, puntuadas de A a F y atribuidas 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.

--redact-sensitive-fields pide a Jira que enmascare valores sensibles para que los artefactos de la revisión sean seguros de compartir. Consulta Informes HTML para el catálogo de informes y las recomendaciones de compartición segura.

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 store.climakers.com/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.