1

Basic Jenkins Operation

In this lab, you will get a chance to work with a simple Freestyle project and
explore the basic features of Jenkins.
Freestyle projects can be used to do anything. Freestyle projects give you the ability
to call any build system, invoke a REST API, run arbitrary code, transfer files, build
containers, create reports, email statistics, record data in a database or any other
task you might perform in the process of preparing for and completing a build.
In this lab, we will create a hand coded Freestyle project script to explore the basic
build features provided by Jenkins. In a real world setting much of the work we will
in this lab would automatically be handled by various Jenkins tools and plugins,
however our goal in this lab is to develop intuition for the way Jenkins works so that
when we face challenges using tools we will have the understanding necessary to
solve problems.

1. Creating a Freestyle Project

In this step, we will create a simple project, configure it to run a trivial shell script
and then test it.
Open up a browser and point it at your Jenkins server.
 2

Give you project a name and select the Freestyle type.

Choose OK to go to the project configuration screen.

In the configuration screen give your project a description and set it to delete
builds older than 3 days and also to keep no more than 10 builds.

At the bottom of the project configuration page add a build step to execute a shell
script:
 3

In this build step, we will simulate a software build. Add the following shell
script source to the build step:
echo ${BUILD_TAG} - compiling
sleep 3
echo "Compile successful!!"
exit 0

This will cause the build to display the project name and build number (the
BUILD_TAG environment variable is set by Jenkins prior to running your script)
followed by “- compiling”, pause for 3 seconds and then echo the success message
to the console log. The script exits with a code of 0, which is success in Unix terms.
Any other value is deemed a failure to Jenkins. Values from 0-255 are legal to
return. In a production setting you could imagine calling “make”, “grunt”, “rake”,
“ant” or some other build tool as part of this step.
Now add a second “Execute shell” build step to simulate running tests.

For this step add the following code:

 4

echo ${PWD} – running tests

sleep 3
echo "Tests successful!!"
exit 0

Next add a post build step:

Choose the Email Notification option and have Jenkins send an email to “user”
every time the build for this project is unstable.
 5

Click “Save” to complete the project configuration. This takes you to the project
home page.

2. Running a Build
Click the “Build now” link on the left to build you project. In production, most
projects you create will be triggered by some event, like a source code change or the
successful build of another project. For now, we will run our build manually.

You build should immediately appear running in the Build History display at the
bottom left. After 6 seconds the build should complete successfully.
 6

3. Exploring a Build
Build #1 now appears in the build history with a date and time and a blue ball
indicating success. Click on the #1 link to go to the build status page for this build

Notice that at the very top left of the window the Jenkins web application always
displays the navigation path to the current page.
 7

In our case we are looking at Build #1 under project testproj1 under the Jenkins
home. You can click on any part of the navigation chain to return to one of the
ancestor pages.
Next notice the “Keep this build forever” button on the top right.

We have configured builds in this project to automatically delete after three days or
ten builds (whichever comes first). This button will preserve the build independent
of the project deletion strategy. For example, if you configured the project to keep
10 builds and identified two builds with “Keep this build forever” you would end
up with 12 builds, the 10 under rotation and the 2 specifically preserved.
This is useful if a particular build has some quirk that you want to preserve so that
you can return to it for reference in the future.
Click the “Keep this build forever” button.
As you can see the button now reads “Don’t keep this build forever”. We’ll leave
the build protected for now, but it is nice to know that we can unprotect it in the
future if desired.
Notice that the page displays the date and time the build took place and the length
of time the build took to complete.

This can be very useful information when you are managing many builds on an
overloaded server. Builds that take a long time can be scheduled for less frequent
execution for example. We’ll look at managing build schedules later in the course

The “No changes” icon tells us that the build was not triggered because of a change
(for example in source code or another build’s state). We just ran the build because
we wanted to
 8

The icon below the changes link displays the initiator of the build, anonymous.
We have not setup Jenkins security yet, we will do this later. At the moment,
everyone using Jenkins is “Anonymous”, so Jenkins reports that Anonymous
started the build. In this default mode, anyone with access to the Jenkins server
can do anything anonymously (obviously this will need to be changed for almost
all production systems).
Now that we have examined the build status lets click on the “Console Output”
link in the left-hand side navigation list.

This causes Jenkins to display the console output (stdout and stderr) from the build
steps we provided. The console log is a critical reference for build monkeys (that’s
us).
As you can see the output shows that anonymous started the build and it also
reports the build workspace. The workspace is where all project files used to
generate the build are stored. Take a moment to list this directory:
ls -l /home/ubuntu/.jenkins/workspace/testproj1/

Our build is trivial and does not have any build source. In a production project we
would probably load a bunch of source files (.cpp, .java, .py, .rb, .html) here to build.
Typically, this is done by telling Jenkins to check the files out of a source code
control system. We’ll try that later.
The next part of the console output show that Jenkins executed our shell script using
“/bin/sh -xe”. It is important to note that this invokes the Bourne shell on *nix (not
the BASH shell). For this reason, the scripting code you provide must be Bourne
shell script. You can of course run a /bin/bash shell and pass it a bash script to
process from within the Bourne shell script if so desired. The -e switch causes the
 9

script to exit immediately if a command fails and the -x switch causes output to go
to stderr.
The remainder of the console log is the output from our two build step scripts.
Note that each script is executed independently and in the order, we specified. If
one build step fails the build terminates without executing the next step.
You can also see our Jenkins environment variables displayed in the console
log. The BUILD_TAG variable produced the string “Jenkins” followed by our
project name and build number. The PWD variable is a standard shell variable
which displays the current working directory,
/home/user/.jenkins/workspace/testproj1 in this case.
From the build menu to the left you can delete the build or add some notes to the
build using the “Edit Build Information” link. Click the “Edit Build Information”
link and add some build info to your build:

Save the build info when you are finished. Notice that the build page now shows
the name you supplied rather than the build number (#1). A build name can be much
more helpful than a number when organizing several old builds used for reference.

Return to the Jenkins dashboard by clicking the Jenkins link at the top left of the
window.
 10

Your project now shows on the dashboard. We have a blue ball and the sun is
shining, nice!
4. Running more Builds:
Run the project again by clicking the “Schedule build” button at the right of your
project entry.

This icon is called the “Schedule build” button because your build will be scheduled,
placed in the build queue. When an executor slot on one of the build nodes is free
then your build will run. On a busy system, it may be some time before your build
executes. On our lab machine the build will execute almost immediately.

While your build is running you should see the project listed in the executor status
display with a new build number to the right (#2). You can cancel a long running
build by clicking on the red X to the right of the build number.
Note that the “Build Executor Status” text is a link. Click it to access the “Nodes”
screen.
 11

This displays the build systems (nodes) in your Jenkins cluster. At present, we only
have our one master machine. In later labs, we will add some slave build systems
to our build cluster. The Nodes display tells you the role of each computer in the
cluster, its architecture (OS), how much free space it has (important if builds are
generating lots of output) and how responsive it is (0 milliseconds is good!).
Return to the dashboard and click on your project link.

As you can see our project now has a bit more information. The build history shows
our (locked) first build and the new second build. We also have links to the Last
build, the last stable build and the last successful build. Remember that stable means
the compile worked (i.e. all of the steps we defined returned 0) and all tests passed
(as we will see later, Jenkins can examine test results to determine build stability).
We don’t have any tests so Jenkins assumes all is well.

5. Failed Builds
Now let’s see what a failed build looks like. Edit your project configuration by
clicking the “Configure” link to the left of the project home page. Change the first
build script to exit with a 5 instead of a 0:
 12

Now save and build your project by clicking “Build Now”

On completion, the build will display a red ball:

Return to the Jenkins dashboard.

As you can see it is getting cloudy. Mouse over the clouds:

Our project is now at 66% build success over the last several builds.

Navigate to the console display of the failed build:

 13

We have two problems:

1. Our build failed: Build step 'Execute shell' marked build as failure
• This is because we returned 5 from the first build step
2. We have no mail server configured and therefore Jenkins could not send
out the build failure email we asked for
• In a later lab, we will setup a simple mail server to test email
notifications. Leave the mailer un-configured for now.

Repair your project by entering the configure screen for the project and setting step
1 to exit with a value of 0 again. Also delete the email notification post build step.
Test build your project to ensure that is completes successfully again.
 14

6. Build rotation
Return to the dash board and quickly click the “Schedule build” button for your
project 5 times.

Jenkins accepts your request to queue a build for the project. However, your project
is not enabled for parallel builds so Jenkins will only allow your project to build on
one executor at a time. Also, Jenkins will not allow your project to be queued more
than once.

Keep building your project until you have 15 builds completed (build #15 complete).
Return to your project home page and examine the build history:

Because you configured your project to allow only 10 builds before builds are
deleted we only have 11 builds, the ten most recent builds and “First Build” (which
we locked).
 15

In the terminal of your lab system examine the build directory for your project:

As you can see, each build has its own directory under the project builds directory.
The most recent builds with each status type also have symlinks to them. For
example, to display the contents of the last stable build directory we can use the
following command:

The -l switch displays a long listing and the -L switch displays the directory the
link points to rather than the link itself. Each build includes a “log” file. This is the
console log displayed by Jenkins for the build:
 16

The build.xml contains metadata about the build and the changelog.xml includes
information regarding the event which triggered the build (none in our case because
the build was executed manually).

Configuring Jenkins to remove old builds causes Jenkins to delete the build
directory and update any symlinks as necessary.

This completes the Basic Jenkins Operations Lab.