Dynamic Jenkins Parameters with Groovy: GitHub Branches, Builds, and Dependencies

In Jenkins, well-designed parameters can simplify even the most complex deployments. In this article, we will see how to build dynamic parameters with a shared Jenkins library, how to query GitHub branches, and how to relate parameters to one another. The examples use a declarative Jenkinsfile, but they can also be adapted to scripted pipelines.

Before getting started, you need:

• A Jenkins instance with permissions to configure the job and run pipelines.

• The Pipeline: Groovy Libraries plugin to load shared libraries.

• The Active Choices plugin if you plan to use reactive parameters such as CascadeChoiceParameter.

• Credentials stored in Jenkins to access private repositories.

• A Git repository with the structure expected by the shared library.

How to Import a Dynamic Library into Your Pipeline

At one point, I had to create a personal repository to develop Groovy libraries because I did not have access to either the Jenkins configuration or the repository containing the original libraries. That is why I used this script.

A shared library can be organized, for example, as follows:

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

Files placed in vars/ expose global pipeline steps. For larger projects, reusable logic should live in src/, leaving only a simple interface for Jenkinsfiles in vars/.

In production, it is preferable to pin a specific tag or version of the library instead of always using master or main. This way, a change in the library does not accidentally modify all pipelines.

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

Once we have resolved the library issue, it is time to put it into action in your pipeline. You can invoke its functions in a simple and practical way. This will allow you to make the most of the library's capabilities to optimize your processes.

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

In this example, testName returns an option for the dropdown. If the function returns multiple lines, Jenkins interprets them as multiple parameter options:

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

And the parameter can consume them as follows:

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

It is advisable to use descriptive and consistent parameter names, such as ENVIRONMENT or RELEASE_BUILD, so that the pipeline is easy to read and maintain.

In this case, the function is very simple.

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

And this is what our new dynamic parameter would look like

Listing Repository Branches on GitHub

If you need a project's branches to come directly from its GitHub repository, you can integrate this code.

 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}

This approach is useful, but it has two important considerations. First, the git ls-remote command must be executed with a secure credential, rather than with credentials interpolated directly into a URL, because they could end up exposed in logs or in the process list. Second, the user running the pipeline needs permission to read the credentials and access the repository.

Whenever possible, use the Git plugin and withCredentials, or an SSH credential managed by Jenkins. Also validate the repository names and branches received before using them in subsequent commands. If the repository contains many branches, consider returning only the allowed branches to prevent the form from becoming slow.

Using the Last Successful Build Number from Another Pipeline

If your Docker builds are in a different pipeline, you can use the RunParameterDefinition parameter and add it to your pipeline with this code.

 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])

This is what our pipeline would look like

The RunParameterDefinition parameter allows you to select an existing run from another job. It is especially useful when a deployment pipeline needs to consume an artifact generated by a build pipeline.

In the pipeline, you can retrieve the selected number and use it to download the corresponding artifact:

 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}

Selecting a successful build is safer than choosing only the most recent number: it prevents deploying a failed or incomplete run. Even so, it is advisable to verify that the artifact exists and corresponds to the target branch and environment.

Logic and Dependencies on Other Parameters

We can also add logic that depends on what is selected in other parameters; for example, if you need to identify which environment was selected and, based on that, apply specific behavior.

First, we need to add the parameter for selecting the environment.

 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])

In a real-world case, the second parameter may depend on the selected environment. For example, we can display different accounts or regions for each environment. With Active Choices, the reactive script receives the values of the parameters it depends on:

 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 is the part that establishes the dependency. Every time the user changes environment, Jenkins reevaluates the REGION script.

Complete Example of Use in a Stage

After defining the parameters, the pipeline can use them to select the behavior for each run:

 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}

Validation within the pipeline is still necessary even if the form limits the available options. Parameters may be empty, modified through an API call, or supplied by an automated job.

Best Practices and Common Issues

• Avoid secrets in code: store tokens, passwords, and SSH keys in Manage Jenkins → Credentials.

• Limit disabled sandbox use: scripts outside the sandbox require administrative approval. Enable the sandbox whenever possible.

• Control response time: do not make several network calls every time the form is opened. Use caching or a limited list of options.

• Validate values in the pipeline: a dynamic parameter improves the user experience, but it does not replace security checks.

• Pin versions: use tags or commits for shared libraries and critical plugins.

• Log useful errors: return understandable messages when GitHub is unavailable or the credential lacks permissions.

If a parameter does not appear, check that the job has run at least once and that the required plugin is installed. If it appears empty, check the script's result, the credential's permissions, and the Jenkins logs. For reactive parameters, also verify that referencedParameters exactly matches the name of the parameter they depend on.

In summary, dynamic Jenkins pipelines with Groovy are a powerful tool that can revolutionize your deployments. By understanding the importance of parameters and how they can influence the efficiency of your pipelines, you are on your way to achieving simpler and more effective deployments.