This article describes how to use the Jenkins continuous integration build server.

1. Using the Jenkins build server

Continuous integration is a process in which all development work is integrated as early as possible. The resulting artifacts are automatically created and tested. This process should identify errors as very early in the process.

Jenkins is one open source tool to perform continuous integration and build automation. The basic functionality of Jenkins is to execute a predefined list of steps. The trigger for this execution can be time or event based. For example, every 20 minutes or after a new commit in a Git repository.

The list of steps can, for example, include:

  • perform a software build with Apache Maven or Gradle

  • Run a shell script

  • Archive the build result

  • Afterwards start the integration tests

Jenkins also monitors the execution of the steps and allows to stop the process if one of the steps fails. Jenkins can also send out notification about the build success or failure.

Jenkins can be extended by additional plug-ins, e.g., for building and testing Android applications or to support the Git version control system.

2. Installation of Jenkins

Jenkins can be started via the command line or can run in a web application server. Under Linux you can also install Jenkins as a system service.

For most platforms you have native packages, see the Jenkins Homepage.

If you installed Jenkins locally, you find it running under the following URL: http://localhost:8080/

2.1. Installing of the Jenkins server on Ubuntu

Jenkins provides Debian/Ubuntu packages which install Jenkins and register Jenkins as start service. See the Install Jenkins on Ubuntu description The Linux installation creates a /etc/init.d/jenkins script which starts Jenkins automatically at boot time.

Jenkins stores all the settings, logs and build artifacts in its home directory. The default installation directory is /var/lib/jenkins under Ubuntu.

2.2. Using the .WAR file of Jenkins

Download the jenkins.war file from Jenkins Homepage. From this file you can start Jenkins directly via the command line with java -jar jenkins*.war.

If you start it locally, you find it running under the following URL: http://localhost:8080/">http://localhost:8080/</ulink>;

To run it in your Tomcat server, put the .WAR file into the webapps directory. If you start Tomcat, your Jenkins installation will be available under http://localhost:8080/jenkins.

If the jenkins.war is deployed in your webapps directory, but cannot be started and the tomcat manager says FAIL - Application at context path /jenkins could not be started , you may need to grant the permissons for JENKINS_HOME.

sudo mkdir .jenkins
sudo
chown tomcat7:nogroup .jenkins
---

This makes the .jenkins folder writable and Jenkins can use it.

3. Configure Jenkins

3.1. Configuration the JDK location

Before using Jenkins to build Java applications, you need to configure the location or it where your JDK installation is. Select Manage Jenkins and afterwards Configure System.

Jenkins at first startup

Enter the correct path to your JDK, Apache Ant and Maven and press the btn:[Save] button below. Jenkins can also install these for your automatically.

Configuring Jenkins

3.2. Secure Jenkins

It is recommended to secure Jenkins. Manage Jenkins and then Configure Global Security. Select the Enable security flag. The easiest way is to use Jenkins own user database. Create at least the user "Anonymous" with read access. Also create entries for the users you want to add in the next step.

Access restrictions

On the login page, select Create an account to create the users you just gave access.

Create Jenkins account
Sign up a new Jenkins user

Go to_Manage Jenkins_, Manage and Assign Roles and then Assign Roles to grant the newly created user additional access rights.

Sign up a new Jenkins user

Navigate to Manage Roles to define access restrictions in detail. Pattern is a regex value of the job name. The following grants unregistered users read-only access to your build jobs that start with the C-MASTER or M-MASTER prefix and only those.

Sign up a new Jenkins user

3.3. Generate ssh key for Jenkins user

If you want to access a private Git repo, for example at Github, you need to generate an ssh key-pair. Create a SSH key with the following command.

sudo -u jenkins ssh-keygen

4. Jenkins management

4.1. Plug-in management

Jenkins can be extended via additional plug-ins with more functionality. You can configure your plug-ins via the menu:Manage Jenkins[Manager Plugins] link.

To install plugins in Jenkins select use the menu:Manage Jenkins[Manager Plugins] link and search for the plugin you want to install. Select it from the list and select to install it and restart Jenkins.

The following table is a summary of commonly used plug-ins.

Table 1. Table Jenkins plug-ins
Plug-in name Description URL

Git Plugin

This plugin allows use of Git as a build SCM.

https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin

Xvnc plugin

This plugin allows projects to run xvnc during a build. This allows for example to run tests which requires a display to run on a virtual display. To use this plug-in you need to connect once to your vncserver on the command line to provide a password. Use for example the following commands.

[source,java] ---- # install vncserver apt-get install vnc4server

# switch to jenkins user sudo su jenkins

# connect to vncserver which creates the password vncserver :10 ----

wiki.jenkins-ci.org/display/JENKINS/Xvnc+Plugin

Gradle Plugin

This plugin allows to run Gradle builds, e.g., as required for Android, via Jenkins.

https://wiki.jenkins-ci.org/display/JENKINS/Gradle+Plugin

Maven Plugin

This plugin allows to run Maven builds.

https://wiki.jenkins-ci.org/display/JENKINS/Maven+Project+Plugin

GitHub plugin

This plugin integrates Jenkins with Github projects.

https://wiki.jenkins-ci.org/display/JENKINS/Github+Plugin

Publish Over SSH Plugin

This plugin allows to publish build artifacts via ssh

https://wiki.jenkins-ci.org/display/JENKINS/Publish+Over+SSH+Plugin

Workspace Cleanup Plugin

This plugin allows to delete the workspace before the build or when a build is finished and artifacts saved.

https://wiki.jenkins-ci.org/display/JENKINS/Workspace+Cleanup+Plugin

Github Pull Request Builder

This plugin allows to build Github Pull Requests

https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin

4.2. Restart your Jenkins

You can manually restart Jenkins by adding restart as URL parameter.

How to manually restart Jenkins

5. Support for the Git version control systems

Jenkins supports the Git version control system via a plugin. Select the menu:Manage Jenkins[Manager Plugins] link. Here you have to install the Git Plugin.

To clone a Git repostory via Jenkins you need to enter the email and user name for your Jenkins system. For this switch into your job directory and run the git config command.

# Need to configure the Git email and user for the Jenkins job

# switch to the job directory
cd /var/lib/jenkins/jobs/Android/workspace

# setup name and email
sudo git config user.name "jenkins"
sudo git config user.email "test@gmail.com"

6. Setting up a Jenkins job

The build of a project is handled via jobs in Jenkins. Select New Item from the menu

Setting up a Jenkins job

Afterwards enter a name for the job and select Freestyle Job. Press OK.

The next page allows you to configure your job. If you for example using Git, enter the URL to the Git repository. If the repository is not public, you may also need to configure the credentials.

Setting up a Jenkins job

Specify when and how your build should be triggered. The following example polls the Git repository every 15 min. It triggers a build, if something has changed in the repo.

Setting up a Jenkins job

I typically delete the workspace before a build to avoid any side-effect. In the Build section you can add a build step, e.g., a Maven build.

Setting up a Jenkins job

Press Save to finish the job definition. Press _Build Now _ on the job page to validate the job works as expected.

Setting up a Jenkins job

After a while the job should go to green or blue (depending on your configuration), if successful. Click on the job and afterwards on Console Output to see the log file. Here you can analyse build errors.

Setting up a Jenkins job

7. Jenkins backup and copying files

Jenkins stores all the settings, logs and build artifacts in its home directory. For example, in /var/lib/jenkins under the default install location of Ubuntu.

To create a backup of your Jenkins setup, just copy this directory.

The jobs directory contains the individual jobs configured in the Jenkins install. You can move a job from one Jenkins installation to another by copying the corresponding job directory. You can also copy a job directory to clone a job or rename the directory.

Click btn:[reload config] button in the Jenkins web user interface to force Jenkins to reload configuration from the disk.

7.1. Managing Jenkins with Git

Jenkins supports the https://wiki.jenkins-ci.org/display/JENKINS/SCM+Sync+configuration+plugin plug-in which allows you to store every change in a Git repo.

It is also possible to manually maintain the Jenkins configuration in a Git repo.