Automate Builds [2 Easy Steps For Your First Jenkins Job]

The Jenkins automation server allows you to automate builds and tests of any software project. In this tutorial, we will see how can we automate the building and testing of a fictitious software project.

Why To Automate Builds?

You may ask, why should I bother to automate builds. When you build your software project manually, you may find it error-prone and time-consuming.

Suppose, you are developing a learning software named abc. The source code of your abc project is already located in git repository in my-git.com machine and can be accessed via ssh protocol – ssh://root@my-git.com/projects/abc.git.

Your workflow for building your software is simple. First, you clone the git repository to your local machine, then manually invoke the build tools. Clone repository and manually build

Manual Build Of The Project
 user@abc-01:~ # env GIT_SSH_COMMAND='ssh -i abc.key' git clone ssh://root@my-git.com/projects/abc.git
 Cloning into 'abc'...
 remote: Counting objects: 6, done.
 remote: Compressing objects: 100% (3/3), done.
 remote: Total 6 (delta 0), reused 0 (delta 0)
 Receiving objects: 100% (6/6), done.
 Checking connectivity... done.
 user@abc-01:~ # cd abc
 user@abc-01:~/abc # echo 'Invoke commands to build the software'
 ...

After several builds, you find that this workflow is error prone and time consuming. You decide to automate the build process. In the following steps – we will see how Jenkins can help you with this task.

Build Manually With Jenkins

First, we need to write a script which will be used by Jenkins to build and test our software. In the following steps, we will tell Jenkins to run this script every time there is a change in our source tree and to report us the results. In other words, when we commit or push changeset to our git repository, Jenkins will invoke this script and when the script is done, It will notify us via email whether the build process was successful.

From Jenkins viewpoint, we can invoke any command or build tool to build and test our software. Jenkins will consider the build process as successful if the exit code of this command or build tool is 0. Any other exit code will be is a sign that the build has failed.

First, Clone our git repository to our development machine:

Clone our git repository of the project
 user@abc-01:~ # env GIT_SSH_COMMAND='ssh -i abc.key' git clone ssh://root@my-git.com/projects/abc.git
 Cloning into 'abc'...
 remote: Counting objects: 6, done.
 remote: Compressing objects: 100% (3/3), done.
 remote: Total 6 (delta 0), reused 0 (delta 0)
 Receiving objects: 100% (6/6), done.
 Checking connectivity... done.
 user@abc-01:~ # cd abc
 user@abc-01:~/abc #

Now, Create a new build.sh. In this tutorial, this script will simply print that it was invoked and exit. In real life, this script will call our build tools (For example make, ant, rake … ).

Create the build script
 echo 'Hello from build script :-)'
 exit 0

Now, add, commit this file and push the changes:

Add the build script to the git repository
 user@abc-01:~/abc # git add build.sh
 user@abc-01:~/abc # git commit -m "adding build script"
 [master 67e9a97] adding build script
  1 file changed, 0 insertions(+), 0 deletions(-)
  create mode 100644 build.sh
 user@abc-01:~/abc # env GIT_SSH_COMMAND='ssh -i abc.key' git push
 ...
 To ssh://root@my-git.com/projects/abc.git
  8be7ded..1935cca  master -> master

Now, Open Jenkins on your web browser. Go to New Item. The following screen should appear:

  • In item name enter abc
  • select Freestyle project and click OK

Now , Go to Source Code Management section and select git :

New Jenkins Job - Source Code Management
New Jenkins Job – Source Code Management
  • Fill Repository URL – in this tutorial, The repository URL is ssh://my-git.com/projects/abc.git
  • Click add button to the left of Credentials field and select Jenkins and add your credentials. In this tutorial we use user with private key method.
New Jenkins Job - Credentials For Source Code Management
New Jenkins Job – Credentials For Source Code Management

After clicking OK, a new abc key credential will appear in credentials list. select it and wait – If Jenkins can connect to the repository, you will not see any red error message.

Go to Build section, click in Add build step, select Execute shell and enter the following script which call our build.sh and return its exit code:

Add build step
 bash -ex build.sh
 exit $?
New Jenkins Job - Add "Execute Shell" Build Step
New Jenkins Job – Add “Execute Shell” Build Step

Click the Save button in the bottom of the page to apply the changes. We are now ready to test our build.

Testing Build Process

Click Build now, You should see a new build in job list display.

The build results list of Jenkines
The build results list of Jenkines

When you click on the build, Jenkins shows more details about build process.

Automate Builds With Jenkins – Build When We Make Changes

In this step, we trigger the build each time a commit is pushed to our git repository and request Jenkins to send us an email with the results of the build.

First , Go to Manage Jenkins > Manage Plugins and install Build Authorization Token Root Plugin which allows to trigger build even when anonymous users cannot see Jenkins.

Automate Builds With Jenkins - Trigger Build Remotely As Anonymous User
Automate Builds With Jenkins – Trigger Build Remotely As Anonymous User

Go To Configure > Build Triggers and select Trigger builds remotely (e.g., from scripts). In Authentication Token enter your token. This token should be keeped private as any one who knows it will be able to trigger a build. In this tutorial, we will enter SECRET. Now, we apply the changes by clicking the Save button in the bottom of the page.

Now, You can trigger a build for the current job abc by accessing the url http://my-jenkins.com/buildByToken/build?job=abc&token=SECRET.

We will use this triggering method to build the software every time a commit is pushed to our git repository. git allows running scripts located at hooks when certain events occur. The post-update will be invoked after a commit is pushed to our git repository. So, we trigger a build by accessing the above URL (using curl).

Add git post trigger method
 user@abc-01:~# ssh my-git.com
 root@my-git:~# nano /projects/abc.git/hooks/post-update

Now, enter the following commands and save the file:

Inform Jenkins about the new push
 #!/bin/sh
 echo "Trigger a build"
 curl -s 'http://my-jenkins.com/buildByToken/build?job=abc&token=SECRET'

Now, we make it executable:

Make the script executable
root@my-git:~# chmod 555 /projects/abc.git/hooks/post-update

Jenkins can notify us about the build results via email. Go to Configure > Post-build Actions and click Add post-build action and select E-mail notification

Jenkins Job Post-build Actions - Email Notifications
Jenkins Job Post-build Actions – Email Notifications

By default, email will be sent for every build failure or for every successful build after a failed one. Unchecking Send e-mail for every unstable build, will change this default behavior – Now, email will be sent for every build failure after successful one.

The Recipients of the mail notifications can be set in the Recipients field. You can also send notifications of build failures to users which change files at the current build, by checking Send separate e-mails to individuals who broke the build checkbox.

Click the Save button in the bottom of the page

Congratulations, you automate the build of your software. Now, Let’s test it

Test Automatic Build – Build Become Unstable

Change the build.sh to failure by exiting with code 1

Test a build failure
echo 'Hello from build script :-)'
exit 1
Push changes
 user@abc-01:~/abc # git commit -a -m "Build Failed"
 user@abc-01:~/abc # env GIT_SSH_COMMAND='ssh -i abc.key' git push

A new build should be triggered. when the build is done – you should receive an email about the failed build.

Test Automatic Build - Build Failed
Test Automatic Build – Build Failed

Test Automatic Build – Build Become Stable Again

Now, Change the build.sh to success again by exiting with code 0

Test a build success
echo 'Hello from build script :-)'
exit 0
push changes
user@abc-01:~/abc # git commit -a -m "Build Ok"
user@abc-01:~/abc # env GIT_SSH_COMMAND='ssh -i abc.key' git push

A new build should be triggered. When the build is done – you should recieve an email about the successful build.

Automate Builds - Build Become Stable Again
Automate Builds – Build Become Stable Again

Leave a Reply

Your email address will not be published. Required fields are marked *