Creando parametros dinamicos en Jenkins con librerias groovy

En Jenkins, unos parámetros bien diseñados pueden simplificar incluso las implementaciones más complejas. En este artículo veremos cómo construir parámetros dinámicos con una librería compartida de Jenkins, cómo consultar ramas de GitHub y cómo relacionar unos parámetros con otros. Los ejemplos utilizan un Jenkinsfile declarativo, pero también pueden adaptarse a pipelines scripted.

Antes de empezar, necesitas:

• Un Jenkins con permisos para configurar el job y ejecutar pipelines.

• El plugin Pipeline: Groovy Libraries para cargar librerías compartidas.

• El plugin Active Choices si vas a utilizar parámetros reactivos como CascadeChoiceParameter.

• Credenciales almacenadas en Jenkins para acceder a repositorios privados.

• Un repositorio Git con la estructura esperada por la librería compartida.

Cómo importar una librería dinámica en tu pipeline

En una ocasión, tuve que crear un repositorio personal para desarrollar librerías de Groovy, ya que no tenía acceso ni a la configuración de Jenkins ni al repositorio que contenía las librerías originales. Por eso, utilicé este script.

Una librería compartida puede organizarse, por ejemplo, de esta manera:

1jenkins_poc/
2├── vars/
3│   └── testName.groovy
4├── src/
5│   └── com/ejemplo/jenkins/
6└── resources/

Los archivos colocados en vars/ exponen pasos globales del pipeline. Para proyectos más grandes, la lógica reutilizable debería vivir en src/, dejando en vars/ únicamente una interfaz sencilla para los Jenkinsfiles.

En producción es preferible fijar una etiqueta o una versión concreta de la librería en lugar de utilizar siempre master o main. De esta forma, un cambio en la librería no modifica accidentalmente todos los pipelines.

1library identifier: "jenkins_poc@main", retriever: modernSCM([
2    $class: 'GitSCMSource',
3    remote: "https://github.com/${user}/jenkins_poc.git",
4    credentialsId: credentialsId
5])

Una vez que hemos resuelto el tema de la librería, es hora de ponerla en acción en tu pipeline. Puedes invocar sus funciones de manera sencilla y práctica. Esto te permitirá aprovechar al máximo las capacidades de la librería para optimizar tus procesos.

1properties([
2    parameters([
3	choice (
4            name: 'name',
5            choices: [testName("Dynamic parameter")],
6            description: 'name'
7        ),
8	])
9])

En este ejemplo, testName devuelve una opción para el desplegable. Si la función devuelve varias líneas, Jenkins las interpreta como varias opciones del parámetro:

1// vars/environmentOptions.groovy
2def call() {
3    return ['dev', 'stag', 'prod']
4}

Y el parámetro puede consumirlas así:

1properties([
2    parameters([
3        choice(
4            name: 'ENVIRONMENT',
5            choices: environmentOptions(),
6            description: 'Selecciona el entorno de destino'
7        )
8    ])
9])

Conviene utilizar nombres de parámetros descriptivos y constantes, como ENVIRONMENT o RELEASE_BUILD, para que el pipeline sea fácil de leer y mantener.

En este caso la función es muy simple.

1# vars/testName.groovy
2def call(String name) {
3	return name
4}

Y así se vería nuestro nuevo parámetro dinámico

Listar las ramas de un repositorio en GitHub

Si requieres que las ramas de un proyecto vengan directamente del repositorio de GitHub, puedes integrar este código.

 1import com.cloudbees.plugins.credentials.CredentialsProvider;
 2import com.cloudbees.plugins.credentials.common.StandardUsernamePasswordCredentials;
 3import jenkins.model.Jenkins;
 4
 5def credentials = com.cloudbees.plugins.credentials.CredentialsProvider.lookupCredentials(
 6    com.cloudbees.plugins.credentials.Credentials.class,
 7    Jenkins.instance,
 8    null,
 9    null
10);
11def user = credentials.findResult { it.id == credentials_id ? it : null }
12try{
13    def gettags = ("git ls-remote -t -h https://${user.username}:${user.password}@github.com/${user}/${project}.git").execute()
14    def branchesNoDefault = gettags.text.readLines().collect {
15            it.split()[1].replaceAll('refs/heads/', '').replaceAll('refs/tags/', '').replaceAll("\\\\^\\\\{\\\\}", '')
16    }
17    branches = branchesNoDefault.collect {
18        if (it == defaultBranch){ 
19            return "${defaultBranch}:selected"
20        }else { 
21            return it 
22        }
23    }
24        return branches
25} catch(all) {
26    return [all.getMessage()]
27}

Este enfoque es útil, pero tiene dos aspectos importantes. Primero, el comando git ls-remote debe ejecutarse con una credencial segura y no con las credenciales interpoladas directamente en una URL, porque podrían terminar expuestas en logs o en la lista de procesos. Segundo, el usuario que ejecuta el pipeline necesita permisos para leer las credenciales y para acceder al repositorio.

Siempre que sea posible, utiliza el plugin de Git y withCredentials o una credencial SSH gestionada por Jenkins. También valida los nombres de repositorio y las ramas recibidas antes de utilizarlos en comandos posteriores. Si el repositorio contiene muchas ramas, considera devolver únicamente las ramas permitidas para evitar que el formulario sea lento.

Usar el último número de compilación exitoso de otro pipeline

Si tus builds de Docker están en un pipeline diferente, puedes usar el parámetro RunParameterDefinition y agregarlo a tu pipeline con este código.

 1properties([
 2    parameters([
 3		choice (
 4			name: 'name',
 5			choices: [testName("Dynamic parameter")],
 6			description: 'name'
 7		),
 8		[
 9			$class: 'RunParameterDefinition',
10			filter: 'SUCCESSFUL', 
11			name: 'RELEASE_BUILD',
12			projectName: build_job
13		]
14	])
15])

Así se vería nuestro pipeline

El parámetro RunParameterDefinition permite seleccionar una ejecución existente de otro job. Es especialmente útil cuando un pipeline de despliegue debe consumir un artefacto generado por un pipeline de compilación.

En el pipeline puedes obtener el número seleccionado y utilizarlo para descargar el artefacto correspondiente:

 1pipeline {
 2    agent any
 3
 4    stages {
 5        stage('Mostrar compilación seleccionada') {
 6            steps {
 7                echo "Compilación elegida: ${params.RELEASE_BUILD}"
 8            }
 9        }
10    }
11}

La selección de una compilación exitosa es más segura que elegir únicamente el número más reciente: evita desplegar una ejecución fallida o incompleta. Aun así, conviene comprobar que el artefacto existe y que corresponde a la rama y al entorno de destino.

Lógica y dependencias de otros parámetros

También podemos agregar lógica que dependa de lo que sea seleccionado en otros parámetros; por ejemplo, si necesitas identificar qué entorno fue seleccionado y, basándote en ello, tener cierto comportamiento.

Primero debemos agregar el parámetro para seleccionar el entorno.

 1properties([
 2    parameters([
 3		choice (
 4			name: 'name',
 5			choices: [testName("Dynamic parameter")],
 6			description: 'name'
 7		),
 8		[
 9			$class: 'RunParameterDefinition',
10			filter: 'SUCCESSFUL', 
11			name: 'RELEASE_BUILD',
12			projectName: build_job
13		],
14		[
15			$class: 'CascadeChoiceParameter',
16			choiceType: 'PT_SINGLE_SELECT',
17			description: 'Select the environment from the dropdown list',
18			filterLength: 1,
19			filterable: false,
20			name: 'environment',
21			script: [
22				$class: 'GroovyScript',
23				fallbackScript: [
24				classpath: [],
25				sandbox: false,
26				script: 
27					"return['CloudCould not get the envs']"
28			],
29			script: [
30				classpath: [],
31				sandbox: false,
32				script:
33				'''return["dev", "stag", "prod"]'''
34			]
35		 ]
36		],
37	])
38])

En un caso real, el segundo parámetro puede depender del entorno seleccionado. Por ejemplo, podemos mostrar cuentas o regiones distintas para cada entorno. Con Active Choices, el script reactivo recibe los valores de los parámetros de los que depende:

 1[
 2    $class: 'CascadeChoiceParameter',
 3    choiceType: 'PT_SINGLE_SELECT',
 4    name: 'REGION',
 5    referencedParameters: 'environment',
 6    script: [
 7        $class: 'GroovyScript',
 8        fallbackScript: [
 9            classpath: [],
10            sandbox: true,
11            script: "return ['No se pudieron cargar las regiones']"
12        ],
13        script: [
14            classpath: [],
15            sandbox: true,
16            script: '''
17                if (environment == 'prod') {
18                    return ['eu-west-1', 'us-east-1']
19                }
20                return ['eu-west-1']
21            '''
22        ]
23    ]
24]

referencedParameters es la parte que establece la dependencia. Cada vez que el usuario cambia environment, Jenkins vuelve a evaluar el script de REGION.

Ejemplo completo de uso en un stage

Después de definir los parámetros, el pipeline puede utilizarlos para seleccionar el comportamiento de cada ejecución:

 1pipeline {
 2    agent any
 3
 4    stages {
 5        stage('Validar parámetros') {
 6            steps {
 7                script {
 8                    if (params.ENVIRONMENT == 'prod' && !params.RELEASE_BUILD) {
 9                        error('La producción requiere una compilación seleccionada')
10                    }
11                }
12            }
13        }
14
15        stage('Desplegar') {
16            steps {
17                echo "Desplegando ${params.RELEASE_BUILD} en ${params.ENVIRONMENT}"
18            }
19        }
20    }
21}

La validación dentro del pipeline sigue siendo necesaria aunque el formulario limite las opciones. Los parámetros pueden llegar vacíos, modificarse desde una llamada API o proceder de un job automatizado.

Buenas prácticas y problemas habituales

• Evita secretos en el código: guarda tokens, contraseñas y claves SSH en Manage Jenkins → Credentials.

• Limita el sandbox desactivado: los scripts fuera del sandbox requieren aprobación administrativa. Actívalo siempre que sea posible.

• Controla el tiempo de respuesta: no hagas varias llamadas de red cada vez que se abre el formulario. Usa caché o una lista limitada de opciones.

• Valida los valores en el pipeline: un parámetro dinámico mejora la experiencia, pero no sustituye las comprobaciones de seguridad.

• Fija las versiones: utiliza tags o commits para las librerías compartidas y los plugins críticos.

• Registra errores útiles: devuelve mensajes comprensibles cuando GitHub no esté disponible o la credencial no tenga permisos.

Si un parámetro no aparece, revisa que el job se haya ejecutado al menos una vez y que el plugin requerido esté instalado. Si aparece vacío, comprueba el resultado del script, los permisos de la credencial y los logs de Jenkins. Para parámetros reactivos, verifica también que referencedParameters coincida exactamente con el nombre del parámetro del que dependen.

En resumen, los pipelines dinámicos en Jenkins con Groovy son una herramienta poderosa que puede revolucionar tus implementaciones. Al comprender la importancia de los parámetros y cómo pueden influir en la eficiencia de tus pipelines, estás en camino de lograr implementaciones más sencillas y efectivas.