Home Tutorials Training Consulting Products Books Company Donate Contact us

Get more...

Training Events

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 allows to identify errors as early as possible.

Jenkins is a popular open source tool to perform continuous integration and build automation. The basic functionality of Jenkins is to execute a predefined list of steps, e.g. to compile Java source code and build a JAR from the resulting classes. 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.

Possible steps executed by Jenkins are for example:

  • perform a software build using a build system like Apache Maven or Gradle

  • execute a shell script

  • archive a build result

  • running software tests

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

Jenkins can be extended by additional plug-ins. For example, you can install plug-ins to support building and testing Android applications.

2. Installation and setup of Jenkins

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

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.1.1. Using the .war file to start 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/

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


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
chown tomcat7:nogroup .jenkins

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

3. Configure Jenkins

3.1. Connect to Jenkins for the initial configuration

After installation, open a browser and connect to it. The default port of Jenkins is :8080, therefore on your local machine you find it under the following URL:


You will need to copy the initial password from the file system of the server.

Afterwards you can select to install plug-ins. Select the Install suggested plug-ins to get a typical configuration.

Create an admin user and press Save and Finish.

3.2. User management Jenkins

Select 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

3.3. Create a new 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.4. 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

The public key must be uploaded to the service you are using, e.g., Github.

3.5. Configure the default port of the Jenkins build server

sudo vim /etc/default/jenkins

4. Setting up a Jenkins job

The build of a project is handled via jobs in Jenkins. Select New Item. Afterwards, enter a name for the job and select Freestyle Job and press OK.

Setting up a Jenkins job

Enter a description for the job and configure how many old jobs should be retained.

Setting up a Jenkins job

Configure how the source code can be retrieved. 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 analyze the build errors.

5. Build Pipelines

Jenkins pipelines help you align the build process of a project. This is done by specifying tasks and the order in which they are executed. There are all kinds of possible tasks that a jenkins pipeline can do for you. For example, build assets, send an email on error or send the build artifacts via SSH to your application server.

5.1. Setup using a Jenkinsfile

Jenkins allows to specify pipelines using a Jenkinsfile. This is just a textfile that contains the necessary data for jenkins to execute the pipeline. It is called Jenkinsfile (notice: no file extension) and should be placed in the root of your project.

This file should be checked into version control as it is needed on your Jenkins instance.

Jenkins supports two different syntaxes.

  1. Declarative (since Pipeline version 2.5)

  2. Scripted

For this tutorial we will focus on the declarative approach.

The following example shows a pipeline with 2 stages:

pipeline {
    agent any (1)

    stages {
        stage('Build Assets') {
            agent any (1)
            steps {
                echo 'Building Assets'
        stage('Test') {
            agent any
            steps {
                echo 'Testing stuff...'
1 The agent directive tells jenkins to allocate a workspace and an executor for the pipeline. Without it, the pipeline is not valid and therefore required.

5.2. Setup using the Blue Ocean plugin

The above process can also be done using the Blue Ocean Jenkins plugin.

5.2.1. Installation

To install the plugin go to Manage Jenkins  Manage Plugins  Available and select the Blue Ocean plugin.

After the installation is finished you have an additional menu entry called Open Blue Ocean in your main Jenkins navigation.

jenkins pipeline10

5.2.2. Creating a new pipeline

Click on New Pipeline to create a new pipeline.

jenkins pipeline20

Select your version control provider.

jenkins pipeline21
For this example we will use a github repository

Depending on your provider you will need to pass some kind of credentials.

Github provides the ability to generate access-tokens that applications can use to access the platform with your user. You can also restrict what the acess-token can do.

The Blue Ocean application will provide a link to the GitHub page you need visit. The necessary permissions that Blue Ocean needs to operate are already selected. Add a description and click on Generate Token at the bottom of the page.

Copy the generated token and paste it in the Blue Ocean mask.

Select the account the repository belongs to and select the repository.

jenkins pipeline30

If you already have a Jenkinsfile with pipelines in the repository it will show up in the last step. If not Blue Ocean offers to create one for you.

5.2.3. Adding steps to your pipeline

In the next screen you will see a visual representation of your pipeline. Here you can add or remove steps.

jenkins pipeline40

To create a new stage click on + in the canvas. A menu will open on the right that lets you specify a name and what steps you want to perform.

jenkins pipeline50

After you have finished editing the pipeline Blue Ocean offers to commit the newly created pipeline to your repository.

Under the hood Blue Ocean only created a valid Jenkinsfile for jenkins to use.

After committing Jenkins will build the project using the newly modified pipelines.

7. vogella training and consulting support

Copyright © 2012-2019 vogella GmbH. Free use of the software examples is granted under the terms of the Eclipse Public License 2.0. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.