Learning Jenkins?

Jenkins, a free continuous integration tool, is fantastic for handling large projects, and its abilities within its domain are practically limitless. But this benefit is a hindrance, too — getting started can be befuddling!

 

The fundamentals of Jenkins are straightforward, but there’s a significant gap between basics and practical, real-life use. Little material exists to bridge that gap.

 

Here, then, are two examples meant for that exact purpose. You can skim them for the general idea or you can follow along line by line.

 

Project 1: Version Control & Email Feedback

This example demonstrates some of Jenkins’ fine controls. It uses the Email Extension Plugin, which allows customization of Jenkins’ existing email abilities, along with some standard plugins such as the Git plugin.

 

We’ll assume you have Git set up on your machine; if not, here’s some info on getting it set up. The link is for CentOS 7 as that is what this example uses (if you’re using a different system, only minor adaptations should be necessary).

 

Let’s set up a Git repository, and associate it with source code already existing in version control. To parallel this exact example, set up a repository on BitBucket, a popular source control website (it’s free).

 

On your machine, first install Apache server.

sudo yum -y install httpd
sudo service httpd restart

Then, install Git, replacing <name> and <email> with your name and email, respectively. The latter lines of this section simply set information in Git’s internal system so it knows who is writing what code.

sudo yum -y install git
sudo git config --global user.name "<name>"
sudo git config --global user.email "<email>"

Then, create a directory in the public webserve location and initialize a repository.

cd /var/www/html
sudo mkdir jenkinscontroltest

Depending on your user, you may now need to run the following to give yourself control of the location:

sudo chown -R <user> jenkinscontroltest

Now, let’s setup the code repository. Replace <remote code location> with the location of your repository. If you created a BitBucket repo, yours will follow a format of https://<username>@bitbucket.org/<repo owner>/<repo name>.git.

cd jenkinscontroltest
git init
git remote add origin <remote code location>
echo "Martin Berlove" >> contributors.txt
git add -A
git commit -am 'Initial commit.'
git push -u origin master

The echo command writes to a file, in this case contributors.txt. The git add command says to add all new files to the file tracking system that Git employs, git commit says you are done writing for now and the files you have edited are ready to be sent to the remote location, the central repo. Git push is what actually sends the files.

 

So now our local code is linked up to the code on BitBucket (or wherever you have chosen to place your remote code).

 

Next, create the new project! This follows the same basic steps as before, only this time, on the configuration page, we add a few changes. First, we select Git as our version control, which is available to us due to the plugin we previously installed. Specify your repo URL; in this case, mine is https://mberlove@bitbucket.org/mberlove/jenkinscontroltest.git.

 

You will need to add credentials; for BitBucket, this is a simple user/password pair.

 

We also want to create a build trigger to tell Jenkins when to run — i.e. not just manually! In the Build Triggers section we check Poll SCM (that’s software configuration management, meaning that Jenkins is going to check on the source control system to see if there are changes according to a schedule we’re about to specify).

In the Schedule box, we enter H/5 * * * *. This means that Jenkins will poll the system every five minutes (the little question mark next to this box contains useful information on this field). We’ll add an “execute shell” build script to run

git status

and then add a single post-build action: Editable E-mail Notification. If you’re following along, you can see that the fields here are auto-populated with default representative variables.

 

Next, add yourself as a recipient in the project recipient list, replacing the existing variable. Click on Advanced Settings to reveal a number of new options, including the Triggers area, where you can control when and why an email gets sent. Add a new trigger and select Always, indicating Jenkins will send this email any time it runs this job, then save the configuration.

 

Now, we can make a change in the code repository to trigger the Jenkins job. We’ll run the following to make a new file and then add it, commit it, and push it to the repo:

touch file1
git add -A
git commit -am "Added a new file."
git push -u origin master

Wait a few minutes for the poll to happen…and sure enough, the following email is sent:

 

Clicking on the link in the email brings us to the job run information page, which conveniently contains the record of my most recent commit!

And as always you can go to Console Output from here to see more details.

 

You can also see the broad results of this and other jobs on the dashboard (Jenkins home):

Project 2: TODO Comment Monitor

 

This next example has a good deal of grounding in the practical. It monitors specified files for comments marked “TODO.” This kind of comment pops up commonly in software projects, and it can indicate incomplete work, so even if a project compiles and functions, you may not want it considered “complete”, so you can set Jenkins to watch for this, and change the status of a build based on whether TODO comments are found in a file.

 

As previously, start off with a new project. We’ll link it in to the same BitBucket project as before and give it the same polling schedule. However, this requires a new plugin, Jenkins Text Finder, which you can install the same way as previously shown. This provides the ability to search through files using regular expressions, and modify the outcome of a build based on the results of the search.

 

Now add a new post-build step, selecting the Jenkins Text Finder option, which exposes a new form. Here you can set what files to search, the pattern for which to search, and what to do if they are found. We’ll set Jenkins to check just the file1 file in the jenkinscontroltest directory, to look for “TODO”, and to set the build to unstable if this pattern is found.

The location of your file must be specified relative to the Jenkins workspace for this job. In the example, it was necessary to ascend several levels in the directory from the user folder where Jenkins was operating.

 

When this is configured, save the job configuration, and then make a change to the file and push:

cd /var/www/html/jenkinscontroltest/
 echo "TODO something to do" >> file1
 git commit -am "Added a comment."
 git push -u origin master

A few minutes later, a job build shows up on the project page:

The color of the status orb is different this time, and if we hover over the build information, we get a status showing that the build was unstable. Jumping to the console output, we can see that, indeed, the Jenkins plugin found the pattern we specified and changed the status of an otherwise healthy build to be unstable, just like we wanted:

View post on imgur.com

 

Typical projects will often call for more in-depth setups than those demonstrated here, but hopefully these examples will give you some direction to jumpstart your Jenkins journey. Thanks for reading and best of luck!