05 Common Jenkins Project Configuration Parameters

05Common Jenkins Project Configuration Parameters #

In the previous chapter, we briefly introduced how to deploy services to different machines using Jenkins. However, we didn’t go into detail about other options and parameters in the project. So, in this chapter, we will briefly introduce some commonly used parameter options in projects.

Project Configuration #

In this section, we will take a freestyle project as an example to explain some commonly used options and parameters in different steps. Note that the parameter options in each step may vary depending on the plugins installed in Jenkins. If you come across a situation where certain parameter options mentioned below do not exist in your project, it is possible that the plugin has not been installed. In that case, simply search and install the required plugin.

General #

General steps are mainly used to configure some common settings for the build task, such as:

Description: The content in this input box can be customized or left empty. The purpose is to record some descriptive information about this job task, such as which group the project belongs to and what is the purpose of the service.

Discard old builds: Used to manage the build history of the Jenkins project. “Days to keep builds” and “Max # of builds to keep” can be customized based on your own situation.

This project is parameterized: This is commonly used in non-pipeline type jobs to define parameters used in the job build process. There are many types of parameters, and they will be explained in detail later.

Throttle builds: Used to control concurrency between two tasks, by setting the minimum interval between them and the maximum number of tasks allowed at the same time. This feature is rarely used. If you want to use this option, you need to check the “Execute concurrent builds if necessary” parameter below.

Restrict where this project can be run: Set the machine where the project can run.

Source Code Management #

We don’t need to go into too much detail about the steps for source code management here. Simply select the appropriate code retrieval method based on the different source code repositories. For authentication with the code repositories, use Jenkins credentials, as we discussed earlier. We won’t go into further detail here.

Build Triggers #

This step introduces several methods to automatically trigger job tasks, such as:

Trigger builds remotely (e.g., from scripts): This method allows triggering builds from outside of Jenkins using a URL command. You need to set your own authentication token (TOKEN_NAME), and the configuration already provides the URL connection, which is relatively simple.

Build after other projects are built: This method monitors the build status of other jobs and triggers the build of this job.

Build periodically: This method allows periodic project builds. The input box follows the format of crontab in Linux. If there is a 0 in the “minute hour day-of-month month day-of-week” fields, you can use H instead.

Poll SCM: This method is used to check for source code changes on a regular basis. If there are updates, it pulls the code and executes the build action. If there are no updates, it will not trigger a build. The writing format follows the same rules as crontab in Linux.

Building Environment #

The building environment steps are used to configure some preparations before the task is built, such as:

Use secret text(s) or file(s): used to bind Jenkins credentials that you want to use. The plugin used for this parameter is Credentials Binding Plugin.

Send files or execute commands over SSH before the build starts: send files or execute commands before the task is built. The plugin used for this parameter is Publish Over SSH.

With Ant: use Ant, similar to the Maven tool. The plugin used for this parameter is Ant Plugin.

Build #

The “Build” step can be understood as the core of the entire Jenkins job. In this step, there are multiple methods to implement the central task, and there are also many corresponding parameter options. Here, we will introduce some of the options parameters based on the actual situation. For example:

  • Build/Publish Docker image: This is used to build an image and upload it to a private repository based on the specified Dockerfile. The plugin used is Docker plugin.

  • Invoke top-level Maven targets: This was briefly introduced earlier and will not be repeated here.

  • Conditional steps (multiple): This allows for task building based on one or more conditions, and comes with default options.

  • Deploy to Kubernetes: This deploys resource objects to a Kubernetes cluster based on the given files. The plugin used is Kubernetes Continuous Deploy Plugin, which will be detailed in the following sections.

  • Execute Docker command: This is used to execute Docker commands, including restarting containers, pulling images, and packaging images. It supports almost all Docker subcommands that can be used in the bash shell.

  • Execute SonarQube Scanner: This executes the sonar-scanner command to check code quality. The plugin used is Sonarqube scanner.

  • Exec shell: This executes shell commands using the user set in Jenkins.

  • Invoke Ansible ..: This uses Ansible commands in Jenkins. The plugin used is Jenkins Ansible Plugin.

  • Provide Configuration files: This uses configuration files for certain services or features configured in Jenkins. The plugin used is Config File Provider Plugin, which will be introduced in later chapters.

  • Send files or execute commands over SSH: This sends files or executes shell commands over SSH. The plugin used is Publish Over SSH.

This is a brief introduction to the options parameters in the “Build” step. Although not all of them may be used in work, understanding how to use these options can be very helpful in using Jenkins flexibly.

Post-build Actions #

Post-build actions can be considered as the final tasks of a Jenkins job. In this step, you can use the “Archive the artifacts” option to save the archived files generated in the previous step. You can use the “E-mail Notification” option to send build details and other information to the management personnel. You can also use the “publish over ssh” plugin to send deployment files or execute commands, or use the “Build other project” option to build other jobs based on conditions.

This is a brief introduction to some options and parameters in Jenkins project configuration. The usage of these options will be explained in detail in later chapters.

Parameterized Build Process #

In practical work, when configuring a job in the Jenkins UI or writing a pipeline, variables are often used to increase the flexibility of Jenkins jobs. The values of variables can be either pre-defined internal variables in Jenkins, or variables passed from external sources. In most cases, these variables passed from external sources are defined through parameterized builds.

By using parameterized builds, you can define parameters based on your actual needs. Jenkins provides over ten types of parameter definitions for parameterized builds. Below is a simple explanation of some commonly used parameter types.

Boolean Parameter #

A Boolean parameter is a type of parameter whose value can only be true or false.

For example, to enable Boolean parameter for a project, check the box This project is parameterized and select “Boolean Parameter” from the “Add Parameter” dropdown menu.

Screenshot

In the “Build” step, use Exec shell to write the following script:

#!/bin/bash

if ${test_boolean} is true;
then
    echo "Parameter is checked"
else
    echo "Parameter is not checked"
fi

The passed parameter should be referenced using ${parameter_name} syntax.

After saving, click on Build with Parameters as shown below:

Screenshot

I won’t show the build result here, but you can try it out yourself if you’re interested.

Choice Parameter #

A choice parameter is used in Jenkins to define a list of parameter values. During a build, the selected value is passed to the parameter and can be referenced by other steps.

Here is an example:

In the “Build” step, enter the command in the “Exec shell” input box.

#!/bin/bash

echo "current command: git clone $branch http://192.168.176.154/root/test-helloworld.git"

Save and execute the job.

During the build, you can pull the code based on the selected branch from the drop-down list. Please test the build result yourself.

File Parameter #

The file parameter is used to accept a file from a browser form submission and pass it as a build parameter. The uploaded file will be placed in the specified location in the current workspace ($WORKSPACE), and you can access and use it in the build job.

Here is an example:

Note:

The file name in the form submission is the path of the file, and it is visible in the environment variables. However, when referencing the file, you can use the custom file path directly. For example, if you put the file in the “test” directory under the current working directory (which will be created if it doesn’t exist), you can use the file path directly when needed, without using a variable.

In the “Execute shell” input box under the “Build” step, enter the command:

#!/bin/bash

cat $WORKSPACE/test/test.xml

After saving, you can execute the job and view the content of the file.

Extend choice Parameter #

As the name implies, the extend choice parameter allows you to define multiple parameter options and assign different values to each option, compared to the choice parameter that can only use a single parameter option. This parameter uses the Extended Choice Parameter Plug-In plugin.

First, let’s take a look at the parameter types supported by this parameter:

Among them:

The “Name and Description” parameter is customizable. This parameter mainly supports single-select, multi-select checkboxes, and input boxes. The hidden option is not very useful, so it will not be discussed here.

Single Select Parameter #

Single Select and Radio Butions are both single selection options.

First, let’s take a look at the Single Select type. After selecting this type, multiple parameters will be combined into a drop-down list when clicked on during the build process.

Where:

Name: The name of the parameter.
Description: The description of the parameter.
Parameter Type: The parameter type, here we select single select.
Number of Visible Items: The number of parameters available.
Delimiter: If multiple parameters are set, the delimiter between each parameter.

Parameter value settings:

Explanation:

Choose Source for Value: The value of the parameter, this is a required field.
Choose Source for Default Value: The default value of the parameter, not required.
Choose Source for Value Description: The description of the parameter value, not required. If this option is not set, the value of the parameter will be directly displayed in the drop-down list after the parameter when executing the job. If set, the description of the parameter value will be displayed in the drop-down list after the parameter when executing the job, which means that the value set for this parameter needs attention. If this parameter is set, the number of parameter values must be the same as the number of values set. If the quantities are different, the last value will be filled with the value set in Value, and the effect can be seen below.

In the “Build” step, in the “Exec shell” input box, enter the command:

#!/bin/bash
  
echo $test_extend_choice

The execution result is as shown below:

Explanation:

When configuring the job, if the description value of the last job is not filled in, the value of the value will be displayed directly here. When selecting “para1” and executing it, the value “value1” will be printed.

If the basic parameter type is set to Radio Butions, the display during job construction is as follows:

Here, you can see that there is a scrollbar when selecting parameter values. This is due to setting a value that is less than the actual number of parameters for “Number of Visible Items”. Therefore, for aesthetics, it is recommended to set “Number of Visible Items” to the same as the number of parameters.

Other settings and usage are the same as when using Single Select, so I won’t say more here. You can try it out yourself if interested.

Multiple-choice parameters #

If a checkbox is set, when executing the Jenkins task, multiple option parameters can be set, and the values specified by these parameters can be used. The types of checkboxes are Multi Select and Check Boxes. First, let’s look at the basic version.

Enter the following in the “Exec Shell” input box:

#!/bin/bash

echo $key

Let’s test it out. The selected key value will be output when executed.

The value corresponding to the selected parameter will be output.

Instead of using a single Extend Choice Parameter, multiple Extend Choice Parameters can also be created and used together.

Example

For example, in the deployment of microservices applications, there is often a situation where multiple microservices applications depend on the same common service. At this time, when deploying multiple microservices applications, the common service can be built before building the application service.

First, if multiple projects depend on a common service, the first Extend Choice Parameter parameter can use the radio button type. For aesthetics and a clearer display of the common service list, I use the parameter type of Radio Buttons, as shown below:

Explanation:

Define a dependency service parameter with a single-choice parameter type. Define two parameter values, build and not_build, with corresponding descriptions of “Build Dependency Service” and “Do Not Build Dependency Service”.

The configuration of the second Extend Choice Parameter is as follows:

Explanation:

The parameter name is app_service, and the description is Application Service.

Enter the following script in the “Exec Shell” input box:

#!/bin/bash

string=$app_service
array=(${string//,/ })

build_job(){
    for service in ${array[@]}
    do
    {
        echo "Parallel build $service " 
    }&
    done
    wait

}

if [ "$dependency_service" == "build" ]
then
    echo "Build Dependency Service xxx"
    build_job
else
    echo "Do Not Build Dependency Service"
    build_job

fi

Execute as follows:

The result is as follows:

Secondly, if there are multiple common services, you can use a multiple-choice checkbox type parameter for configuration, referring to the configuration of the application service in the example above.

In addition to using Check Boxes as multiple-choice selection parameters, you can also use Multi Select, but this parameter requires pressing the Ctrl key when selecting multiple parameter options, which is slightly more cumbersome than Check Boxes. There are no other special changes. I won’t demonstrate it here. If you’re interested, you can try it yourself.

Input Type Parameters #

Input type parameters are relatively simple. After defining the parameters, the parameter type is directly set as Text Box. Then, when building, you can enter the value of the parameter. However, this type is not commonly used.

Git Parameter #

Git Parameter is mainly used to retrieve the git tags of the source code repository which is set in the “Source Code Management” step before the job is built. The supported git tags include tags, branches, branches or tags, revisions, and pull requests. Based on the retrieved tag, the git code is pulled and built.

As shown below, when clicking on “Build with Parameter,” the git tags of the set source code repository will be automatically listed (the listed tags may vary depending on the type of git tag set. In this example, the branch tag is used).

The job is set as follows:

Where:

  • The parameter type can be selected according to the actual situation.
  • The default value must be filled in.

At this point, when setting the “Source Code Management,” the branch should be set as the parameter variable created above.

Note:

  • Although the name of Branches to build is specified as branch, it can be used for all the git tags mentioned above.

Password Parameter #

This parameter is used when configuring Jenkins tasks to hide plain text passwords from appearing in the job or console log. The following example shows how to set a default value for this parameter.

For instance, this parameter can be used when logging into a private Docker Hub repository:

#!/bin/bash

docker login 192.168.176.155 -u admin -p $test_password_para

Although the entire process is encrypted, the plain text password can still be obtained by using the echo $test_password_para command in the exec shell. When it comes to password usage, using Jenkins credentials is more advantageous than using this parameter. Therefore, it is recommended to use this parameter based on individual circumstances.

String Parameter #

String parameters are the most common type of parameters, similar to the input type parameter in “Extend Choice Parameter”. They are relatively simple, so I won’t provide a demonstration here. If you are interested, you can try it yourself.

That’s all for the introduction of parameterized builds.

Variables #

In addition to using custom variables in Jenkins jobs, you can also use built-in environment variables in Jenkins. These built-in environment variables can be used in any configuration step of a job. You can get a list of all built-in variables by visiting http://Jenkins_URL/env-vars.html/. Here is an example:

…

There are many variables, but only a few of them are commonly used in work scenarios. For example, the WORKSPACE variable represents the current job’s workspace and is the absolute path of the job on the Jenkins server. The BUILD_NUMBER variable represents the current job’s build ID. The JOB_NAME variable represents the current job’s name, which is the project name in Jenkins. For example, in the “Exec shell” step, you can input:

echo $WORKSPACE $BUILD_NUMBER $BUILD_ID $JOB_NAME

After building the job, the output will be as follows:

You can try out other variables by yourself. I won’t provide a detailed introduction here.

Views #

When using Jenkins, if you have a large number of jobs and want to quickly locate the job you want to build or modify, or if you want to manage jobs in the same project group in a unified manner, you can create views in Jenkins to manage jobs. Views in Jenkins are similar to folders on a computer. By default, Jenkins has an “All” view, which lists all projects under this view.

Create a view #

Below is how to create a view.

On the main panel of Jenkins, click on the “New View” option (or click on the “+” button next to the All view). In the redirected page, enter the name of the view as shown in the figure below:

Where:

  • The List view option is relatively simple. It allows you to select specific jobs from the global job list to be included in this view. When selecting jobs, you can filter them based on conditions or match them with regular expressions. You can also customize the field names of the job information displayed in this view, as shown below:

Configure it according to your actual needs.

  • The My View option adds all the jobs that the current user can see to the newly created view.

  • The Pipeline Aggregator View option is used to display the staeg and job build attribute information of pipeline-type jobs in the Jenkins system in full screen. It is generally not used much.

After configuring, click on “Save” to create the view.

If you want to delete a view, simply click on the view name and then click on “Delete View” on the Jenkins panel. Please note that deleting a view will not delete the job tasks associated with it.

Credentials #

Credentials are the authentication information that Jenkins uses to access third-party applications. Credentials can be a username/password, SSH key, encrypted file, etc. Jenkins can interact with other third-party applications within a trusted and controllable scope by using the configured credentials. To improve security, Jenkins encrypts and stores the credentials, and uses the credential ID and authentication information of the third-party application by default when using the credentials.

By default, Jenkins can store the following types of credentials:

  • Secret text: Tokens such as API tokens (such as GitHub personal access tokens)
  • Username and password: Username and password
  • Secret file: Encrypted content stored in a file
  • SSH Username with private key: SSH public/private key pair
  • Certificate: PKCS#12 certificate file with an optional password

If plugins like Docker, Kubernetes, or OpenShift are installed, additional credential types for these systems will be available:

  • Docker Host Certificate Authentication: Docker repository authentication information
  • Kubernetes configuration (kubeconfig): Authentication for Kubernetes container orchestration system
  • OpenShift username password: Authentication for OpenShift system login

Creating credentials #

Click on “Credentials” -> “System” -> “Global credentials (unrestricted)” in the Jenkins main panel as shown below:

Click on “Add credentials” in the redirected interface to create credentials of type Username with password.

As shown below:

Let’s talk about the ID parameter here. The value of the ID parameter can be customized. If it is not filled in, Jenkins will automatically generate an ID. How to use this credential will be explained in the subsection “Creating Jenkins projects” below.

Jenkins credentials are used quite frequently in the process of continuous delivery and deployment. Various types of credentials creation will be introduced in later sections. The content related to credentials in this section is simply introduced here.

Configuring Master-Slave #

When using Jenkins, in order to avoid excessive resource consumption of the host where the Jenkins service is located, which affects the performance of the Jenkins service, one or more slave nodes are often added to specifically execute Jenkins tasks. This is the well-known Jenkins Master/Slave architecture.

The Jenkins Master/Slave architecture is equivalent to the Server and agent concepts. The Master provides a web interface for users to manage jobs and slaves. Jobs can run on the master machine or be assigned to run on slaves. A Master can be associated with multiple slaves to serve different jobs or different configurations of the same job.

Configuring a Jenkins slave node does not require installing the Jenkins service. It only requires installing and configuring some basic tools (such as JDK, Maven, Git, Ansible, Docker, Sonar, etc.) used by the Jenkins main node. Jenkins slave nodes can be virtual machines or containers, and they can be static host resources or dynamic container resources. Considering that using dynamic container resources requires knowledge of related Jenkins plugin aspects, here, we will first introduce how to add static host nodes.

Click “Manage Jenkins” -> “Manage Nodes” to see that there is currently only one master node. Click “New Node” on the left side to set a name for the slave node, for example, “slave1”, and click OK,

Note:

  • of executors: Indicates the number of concurrent build tasks. Fill in according to your situation.

  • Remote root directory: A required field that is used to save the pulled application code. Set according to your situation.

  • Labels: The label of the slave node. In the Jenkins project, you can match the slave node with this label.

  • Usage: Used to set the usage policy of this node. It can be set to use this node as much as possible (as shown above), or set it to only build jobs with label expressions matching this node, which means that only when the specified job task is set to run on this node in the Jenkins job, this node will be used.

  • Launch metheod: Used to configure the launch method of the Jenkins slave node, mainly divided into SSH and JNLP. SSH means that the master actively connects to the slave node, and JNLP means that the slave node actively connects to the agent. The configuration on the image uses the SSH method.

Host: Enter the address of the Jenkins Slave server here.

Credentials: Add the username and password for logging in to the Slave server here.

Advanced: Used to set some related information of the server.

Port: If the SSH port of the server is not 22, you can set it to another port.

JavaPath: Set the absolute path of the Java executable file on the slave server here. For example, my configuration is (/usr/local/jdk1.8.0_231/bin/java).

After the settings are completed, click the Save button at the bottom. In the redirected interface, click the launch Agent button. The log below indicates that the node was added successfully.

After the node is added successfully, you can modify the Jenkins project configuration, select Restrict where this project can be run, and enter the name or label of the slave node in the box that appears. After saving, build the project again, and it will be built on the new added node. As shown below:

In addition to using a VM as a Jenkins slave node, a Docker container can also be used as a Jenkins slave node. At the same time, the slave node can be orchestrated through container orchestration tools. These contents will be introduced in later chapters, and the content about using a dynamic slave as the environment for job execution will also be explained. Stay tuned!

The content about Jenkins project configuration ends here. We will enter the practical stage in the following chapters.