Simple CI Setup

In software engineering, terms like Agile methodology and integration are quite common. In Agile, development is done in iterations, with each iteration adding new features to the product. At any point of time, there is a working product ready to be used. Integrations are also done on a regular basis. Manually running integration tests can be a painful chore if done too many times.

Recently, I was reading about Continuous Integration(Google it up yourself, as it is not the main topic of this post). I basically involves workflow planning and establishing a Revision Control System(RCS)branching mechanism to be enforced on the team. Thinking it might be useful to have a CI server to test pull requests by team members for my upcoming software engineering projects in the coming semester, I decided to try setting up my own Jenkins server to figure out the required configurations. The following content is a simple guide that triggers a Jenkins build job whenever a pull request is submitted on GitHub. This guide will be using a bare minimal Java project on Arch Linux. You can figure out the equivalent of the mentioned steps by yourself.

Requirements

  • Java Runtime Environment
  • Java Development Kit if you are going to run java command in your execution script

Install Jenkins

  1. Install jenkins.(#sudo pacman -S jenkins)
  2. Get the path to the WAR file(#cat /etc/conf.d/jenkins)
  3. Create a script /usr/local/bin/startjenkins that executes the command java -jar <path_to_war_file>
  4. Run startjenkins. You should be able to access the configuration page on localhost:8080.

*Note: For Windows users, steps 2 to 4 is most likely unnecessary if you install Jenkins as a service.

Setup Project and Repository

  1. Create a repository called jenkinstest. Clone it onto your PC.
  2. Write whatever code or unit tests. Push to the remote repository.
  3. Create a new branch. Make some changes. Commit and push. DO NOT MERGE into master!

Configuring Jenkins

  1. Click on Manage Jenkins -> Manage Plugins, and install Git Plugin, GitHub Plugin and Git Client Plugin, GitHub API Plugin, and GitHub Pull Request Builder Plugin. Restart Jenkins if needed.
  2. Go to your router’s configuration page, use IP address reservation or static IP address to fix your server’s private IP address.
  3. Configure port forwarding to allow Internet access to your server. (Google it up if you need to)
  4. Google “what is my ip”. Use this public IP address with the port that you have set to forward to your server to access Jenkins. It should show the same thing as localhost:8080.
  5. Click on Manage Jenkins -> Configure System.
  6. Under GitHub Pull Request Builder, enter the GitHub API URL as https://api.github.com.
  7. Add your GitHub login credentials and test by clicking Test Credentials.
  8. Click on Create API Token to generate an OAuth token in GitHub. Copy the token string.
  9. Under GitHub Web Hook, enter https://api.github.com as API URL. Enter your GitHub username and paste the OAuth token.
  10. Save and return to Jenkins home page.

Adding Jenkins service to GitHub Repository

  1. On GitHub, navigate to jenkinstest repository.
  2. Click on settings, followed by Webhooks & Services.
  3. Click Add Service and choose Jenkins(GitHub plugin).
  4. Enter Jenkins hook URL. This is http://<your_public_ip>:<port_number>/github-webhook/.
    Note that port number is the port used to do the port forwarding.
  5. Check the Active checkbox and click Update Service.

Create Build Job

  1. On Jenkins home page, click New Item. Enter a job name and select the appropriate project type and click OK.
  2. Enter the URL(without the .git extension) to GitHub project in the ‘GitHub project’ field.
  3. Under Source Code Management, select Git.
  4. For repository URL, enter the URL(with .git extension) of the repository.
  5. Select your GitHub login credentials.
  6. Click on Advanced, in Refspec field, enter ‘+refs/pull/*:refs/remotes/origin/pr/*’.
  7. For Branches to Build, add ‘${sha1}’.
  8. Select GitHub Pull Request Builder for Build Triggers.
  9. Check the use github hooks for build triggering checkbox.
  10. Below this checkbox, click on Advanced. Enter the GitHub usernames of all users to be whitelisted. Being whitelisted means that user’s pull requests are automatically built and tested.
  11. Add build step(s) and/or any other configurations you need.(I added ‘execute shell’ since I am using Java command line tool to build and run my unit tests)
  12. Click Save.

If all is set up properly, a build is triggered whenever you create pull requests or push more commits under the same pull request. You will be notified of the build outcome when the build finishes. If you encounter any mistakes in any of the steps above, please highlight it in the comments below.

The benefits of having a CI server automating the unit/integration tests is that you can detect changes in the pull request that can break the whole product before you merge it. It will be very troublesome to try to revert the merge. However, the success of having CI server hinges on enforcing unit tests for everything that can be tested and knowing how to write scripts to do a thorough run of the tests. Also, the path coverage of the tests should be as high as possible to make the tests meaningful.

This marks the end of another long guide post. Will be making another post for integrating Jenkins for Bitbucket after I have figured out the configuration details as I may be needing the integration with Bitbucket for my upcoming school projects. Do pardon me if this post seems somewhat haphazard: I had a hard time writing out the steps in a way that is easy to follow. Hope this guide helps if you are starting out in using CI to improve your development workflow or for quality assurance.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s