Configuración

ajat aplica la configuración desde cuatro fuentes, en orden de prioridad ascendente:

En la práctica, esto permite a los equipos mantener valores persistentes de la estación de trabajo en el archivo de configuración, inyectar secretos mediante variables de entorno en CI/CD y reservar los flags de CLI para overrides puntuales y depuración.

Ubicación del archivo de configuración

La ubicación predeterminada del archivo de configuración depende del sistema operativo. Ejecuta:

ajat config where

Para crear un archivo de configuración con todos los valores por defecto rellenados:

ajat config create

El archivo de configuración es un archivo YAML llamado config.yaml, ubicado junto al license.bin vinculado a la máquina en el directorio de configuración de usuario estándar de cada plataforma:

Puedes apuntar ajat a otro archivo para la ejecución actual con el flag global --config-file o la variable de entorno AJAT_CONFIG_FILE.

Referencia completa del archivo de configuración

# Conexión con Jira Cloud
jira:
  domain: acme.atlassian.net # Hostname simple, sin https:// ni barra final
  username: you@acme.com # Correo de tu cuenta de Atlassian
  api_token: YOUR_API_TOKEN # API token de id.atlassian.com (anonimizado en la salida)
  type: cloud # Tipo de despliegue de Jira (cloud)
 
# Comportamiento del cliente HTTP
http:
  client:
    max_retries: 3 # Reintentos para llamadas HTTP no-Automation
    base_timeout: 1s # Timeout inicial de la petición
    max_timeout: 30s # Timeout máximo después de reintentos
    proxy: "" # URL del proxy HTTP/HTTPS (ej. http://proxy.corp:8080)
 
# Logging
log:
  level: info # debug | info | warn | error
  format: text # text | json
  file: "" # stdout | stderr | /path/to/file.log
 
# Modo debug
debug:
  enabled: false # Activa salida de depuración detallada
  dir: debug # Directorio para artefactos de depuración

jira.domain es el hostname simple. No incluyas https://, una barra final ni un sufijo /wiki. jira.type tiene el valor por defecto cloud, que coincide con el único modelo de despliegue soportado.

Configurar credenciales

ajat necesita tres valores de conexión — jira.domain, jira.username y jira.api_token — antes de que cualquier comando operativo pueda llegar al tenant. Puedes proporcionarlos de tres maneras.

1. Archivo de configuración (estación de trabajo)

Edita config.yaml directamente, o escribe los valores con config set:

ajat config set jira.domain acme.atlassian.net
ajat config set jira.username you@acme.com
ajat config set jira.api_token <api-token>

2. ajat config set (persistente, sin YAML manual)

config set escribe en el mismo archivo de configuración pero evita editar YAML a mano. Si el archivo aún no existe, se crea con valores por defecto primero. Esta es la forma más sencilla de establecer una configuración repetible de la estación de trabajo con un rastro de auditoría claro. Consulta Comandos de configuración.

3. Variables de entorno AJAT_ (CI/CD)

Para runners de CI/CD y sistemas compartidos, prefiere las variables de entorno para que los secretos nunca toquen un archivo de configuración en disco:

export AJAT_JIRA_DOMAIN=acme.atlassian.net
export AJAT_JIRA_USERNAME=you@acme.com
export AJAT_JIRA_API_TOKEN=<api-token>

Crea el API token para la cuenta de Atlassian que operará en id.atlassian.com/manage-profile/security/api-tokens. La autenticación de la API de Jira Cloud usa el correo de la cuenta como jira.username, no un nombre de visualización.

Variables de entorno

Cada clave de configuración puede definirse con una variable de entorno añadiendo el prefijo AJAT_ y sustituyendo . por _:

Flags globales de CLI

Estos flags persistentes están disponibles en todos los comandos:

Validación de credenciales

Valida la configuración efectiva sin contactar con Jira ni hacer ninguna llamada de red:

ajat config validate

Añade --require-credentials para confirmar además que jira.domain, jira.username y jira.api_token están definidos — la misma comprobación que ejecutan los comandos de exportación y de reportes antes de conectarse a Jira:

ajat config validate --require-credentials

El comando termina con 0 cuando la configuración es válida y con un código distinto de cero, con un mensaje accionable, cuando no lo es, lo que lo convierte en una buena barrera para scripts de configuración y pipelines de CI. Para validar credenciales en vivo y la conectividad de extremo a extremo, ejecuta ajat doctor.

Anonimización del token

jira.api_token siempre se anonimiza en la salida de los comandos. ajat config get, ajat config list y el paquete de ajat support muestran el token oculto, así que la configuración efectiva es segura para compartir al reportar un problema o revisar una instalación.

ajat config list
ajat config get jira.domain

Prácticas seguras de configuración

• Prefiere las variables de entorno AJAT_ para API tokens en sistemas compartidos, gestionados o de CI/CD.
• Usa config create para establecer la estructura esperada del archivo antes de editarlo manualmente.
• Ejecuta doctor después de cambios de configuración para validar juntos licencia, credenciales y conectividad.
• Usa un --config-file personalizado cuando necesites configuraciones aisladas de prueba y producción en la misma máquina.

Detrás de un proxy corporativo

ajat config set http.client.proxy "http://proxy.corp.example.com:8080"

Con autenticación:

ajat config set http.client.proxy "http://user:password@proxy.corp.example.com:8080"

Escribir logs en un archivo

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

Usa --log-format json para logs estructurados en entornos regulados o de CI/CD, y stdout o stderr para enviar logs directamente a tu terminal:

ajat export --output-dir ./jira-automations-backup --log-file stdout --log-format json

Próximos pasos

• Comandos de configuración — gestiona el archivo de configuración desde la CLI.
• Utilidades — valida la estación de trabajo con doctor e inspecciona la superficie de comandos.
• Primeros pasos — la ruta completa desde la instalación hasta la primera exportación.