Comandos Esenciales de la CLI de Jenkins para la Gestión y Control de Trabajos

La CLI de Jenkins te ayuda a gestionar trabajos cuando la interfaz web es demasiado lenta para tareas repetitivas. Si necesitas crear trabajos a partir de plantillas, disparar builds o actualizar la configuración XML en scripts, la CLI te ofrece una ruta directa.

Esta guía se centra en los comandos de gestión de trabajos: list-jobs, get-job, create-job, copy-job, update-job, delete-job y build.

Configuración de la CLI de Jenkins

Antes de ejecutar cualquier comando, debes establecer una conexión segura con tu máster de Jenkins. Esto implica descargar el cliente CLI y asegurar la autenticación adecuada.

1. Descargar el jenkins-cli.jar

El cliente CLI se encuentra típicamente directamente en tu servidor Jenkins en un endpoint específico. Puedes descargarlo usando wget o curl:

wget http://tu-url-jenkins:8080/jnlpJars/jenkins-cli.jar
# O usando curl
curl -O http://tu-url-jenkins:8080/jnlpJars/jenkins-cli.jar

2. Métodos de Autenticación

Las conexiones de la CLI de Jenkins requieren autenticación. El método más seguro y recomendado es usar un Token de API en lugar de una contraseña de usuario simple.

Para generar un Token de API, navega a Configuración de Usuario > Configurar > Token de API en la interfaz web de Jenkins.

Todos los comandos subsiguientes requerirán banderas de autenticación, típicamente usando las banderas -s (URL del servidor) y -auth (credenciales de autenticación):

java -jar jenkins-cli.jar -s http://tu-url-jenkins:8080 -auth NOMBRE_USUARIO:TOKEN_API <comando>

Consejo: Por seguridad, almacena tu token de API en una variable de entorno segura o usa el método de autenticación con clave SSH si está configurado, en lugar de escribirlo directamente en los scripts.

Comandos Principales para el Descubrimiento de Trabajos

Antes de modificar trabajos, a menudo es necesario listar los trabajos existentes y recuperar sus configuraciones.

Listar Todos los Trabajos: list-jobs

Este comando muestra los nombres de todos los trabajos configurados en el máster de Jenkins.

java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH list-jobs

Recuperar la Configuración de un Trabajo: get-job

Los trabajos de Jenkins se definen mediante archivos de configuración XML. El comando get-job te permite recuperar esta definición XML, lo cual es esencial para crear nuevos trabajos basados en plantillas.

# Recuperar la configuración de 'mi-trabajo-plantilla' y guardarla en un archivo
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job mi-trabajo-plantilla > config-plantilla.xml

Comandos Esenciales de Gestión de Trabajos

Estos comandos manejan las operaciones fundamentales del ciclo de vida de los trabajos de Jenkins.

1. Crear un Nuevo Trabajo: create-job

El comando create-job requiere el nombre del nuevo trabajo y el archivo de configuración XML que define sus parámetros, pasos de build y disparadores.

Requisitos previos: Primero debes tener un archivo de configuración XML válido (por ejemplo, nueva-config.xml), generalmente derivado de modificar una plantilla recuperada usando get-job.

# Ejemplo: Crear un nuevo trabajo llamado 'proyecto-rama-funcionalidad' usando el archivo XML local
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job proyecto-rama-funcionalidad < nueva-config.xml

2. Copiar un Trabajo Existente: copy-job

Esta es a menudo la forma más rápida de crear un nuevo trabajo, tomando un trabajo existente como plantilla y aplicando un nuevo nombre. Este comando duplica efectivamente la configuración del trabajo fuente.

# Sintaxis: copy-job NOMBRE_TRABAJO_FUENTE NOMBRE_TRABAJO_DESTINO
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job pipeline-original nuevo-pipeline-dev

3. Habilitar y Deshabilitar Trabajos: enable-job y disable-job

Estos comandos son cruciales para mantenimiento, pausas temporales o control administrativo, previniendo o permitiendo que se disparen builds.

# Comando para detener builds programados o disparados adicionales para mantenimiento
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job build-proyecto-legado

# Comando para reactivar el trabajo
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job build-proyecto-legado

4. Eliminar un Trabajo: delete-job

Este comando elimina permanentemente un trabajo de la instancia de Jenkins, incluyendo su historial de builds y configuración. Usa este comando con precaución.

# Eliminación permanente del trabajo
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job trabajo-prueba-obsoleto

Advertencia: El comando delete-job se ejecuta inmediatamente sin confirmación adicional en el entorno CLI. Asegúrate de que tus scripts incluyan pasos de validación adecuados antes de ejecutar este comando.

Disparar y Monitorear Builds

Más allá de la gestión de configuración, la CLI se usa frecuentemente para disparar builds, especialmente aquellos que requieren parámetros específicos.

Disparar un Build: build

El comando build inicia un nuevo build para el trabajo especificado. Si el trabajo está parametrizado, puedes pasar argumentos directamente usando la bandera -p.

# Disparar un build simple, no parametrizado
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build despliegue-nocturno

# Disparar un trabajo parametrizado, pasando parámetros
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build prueba-integracion -p TARGET_ENV=staging -p BRANCH_NAME=hotfix-123

Nota: Si usas la bandera -s con build, la CLI esperará a que el build se complete e informará el estado de salida. De lo contrario, el comando regresa inmediatamente después de poner en cola el build.

Ver el Estado del Build: get-job y console

Aunque la CLI no ofrece transmisión en tiempo real comparable a la interfaz web, puedes verificar el estado del trabajo y recuperar la salida de la consola.

Para ver la salida de la consola de un número de build específico:

# Recuperar la salida de la consola para el build #55 de 'mi-trabajo'
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console mi-trabajo 55

Mejores Prácticas para Scripts CLI

Aprovechar la CLI de Jenkins de manera eficiente requiere adoptar mejores prácticas específicas para estabilidad y seguridad:

1. Scripting y Automatización

La CLI es más útil en scripts de shell. Usa get-job, modifica el XML resultante con cuidado, y luego alimenta la configuración modificada de vuelta usando create-job o update-job.

Ejemplo de Flujo de Trabajo (Copiar, Modificar y Crear):

1. Obtener plantilla: get-job trabajo-plantilla > tmp.xml
2. Usar sed para reemplazar marcadores de posición (por ejemplo, nombre del proyecto, URL del repositorio) en tmp.xml.
3. Crear nuevo trabajo: create-job nuevo-trabajo < tmp.xml

2. Manejo de Actualizaciones de Configuración

Para actualizar la configuración de un trabajo existente usando XML desde la entrada estándar, usa update-job. Esto es más seguro que eliminar y recrear el trabajo porque preserva el historial de builds.

# Actualizar 'proyecto-a' usando un archivo de configuración modificado localmente
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH update-job proyecto-a < config-actualizada.xml

3. Manejo de Errores

Siempre verifica el código de salida ($?) después de ejecutar un comando CLI en tus scripts. Un código de retorno de 0 indica éxito; cualquier código no cero señala un error. Esto es vital para una automatización robusta y depuración.

Conclusión Clave

La CLI de Jenkins es una herramienta práctica para la administración repetible de trabajos. Comienza exportando el XML del trabajo con get-job, realiza cambios controlados, actualiza trabajos con update-job y dispara builds con build. Mantén los tokens de API fuera de los scripts y valida comandos destructivos como delete-job antes de que se ejecuten.