Skip to content

Creating Jenkins Jobs

Jump to bottom
Ben Heasly edited this page Jan 26, 2017 · 19 revisions

We have a Jenkins test server set up for testing and validating our code. The idea is that Jenkins can pull our code from GitHub, run tests on it, and report the results back to GitHub. You can also view detailed results at the Jenkins server's web interface. You can set up tests to run periodically, or in response to each GitHub push.

Setting up the Jenkins server is described at Installing Jenkins. It should be up and running at this address: 50.112.42.141.

This page is about how to add a new project to the Jenkins server, so that the new project can be automatically tested.

Accounts

##Jenkins To get started, you'll need an account on our Jenkins server. You will probably have to ask a Jenkins administrator to do this, like David, Nicolas, or Ben Heasly.

The steps for the admin would be:

  • Manage Jenkins -> Manage Users -> Create User
    • fill out the form
    • choose Create User
  • Manage Jenkins -> Manage and Assign Roles -> Assign Roles
    • under Global roles -> User/group to add, enter the user name of the new user
    • choose Add
    • in the Global roles table, check the "admin" box next to the name of the new user
    • choose Save

GitHub

You also need to make sure that Jenkins can access your repository at GitHub. The easiest way to do this is to make sure that the GitHub user named render-toolbox is an Owner in your GitHub organization. render-toolbox is a "robot" user that we use just for this purpose, so we have already set up the GitHub-Jenkins communication for it.

We could set up other users, too, but it would take a bit of fussing with the configuration. See GitHub Integration

Creating a Jenkins Job

Once you can log into Jenkins, you can create a new Job.

The Fast Way

The easiest way to create a new job is to find an existing job that's similar to what you want, copy it, and modify it.

To make the copy, log in to Jenkins, then:

  • New Item
    • enter a name for the new job
    • choose Freestyle project
    • for Copy from, enter the name of an existing job
    • choose OK

This will take you to a page with loads of things to configure. Most of it you won't need to touch. The things to change for your new job are probably:

  • General
    • Description
    • Project url for GitHub (this is the GitHub clone url, ending in .git)
  • Source Code Management
    • Repository URL (same as Project url, above)
    • under Additional Behaviors -> Check out to a subdirectory, Local subdirectory for repo (if any)
  • Build
    • Execute shell Command (see Generating a Job Script, below)
  • choose Save

The rest you can probably leave as it is. Of course, you can customize the job however you like. See below for more about configuring jobs from scratch.

The Full Way

Jenkins is a popular and complex tool, with lots of ways to configure it! This is daunting. We don't use most of its features. You could spend all day clicking on things and wondering what they do.

Here are the steps to configure a Jenkins job from scratch, similar to several jobs that we already have working.

Log in to Jenkins, then:

  • New Item
    • enter a name for the new job
    • choose Freestyle project
    • choose OK

This will take you to a page with loads of things to configure. Here's what has worked for us so far:

  • General
    • add a Description -- a sentence about the job, like "Nightly validations for IBIOColorDetect."
    • check GitHub project
      • enter the Project url (the GitHub clone url, ending with .git)
  • Source Code Management
    • choose "Git"
      • enter the Repository URL (same as Project url above)
    • under Additional Behaviours choose Add -> Check out to a sub-directory
      • enter the Local subdirectory for repo, like "IBIOColorDetect"
  • Build Triggers (choose one)
    • check GitHub hook trigger for GITScm polling (run tests for each GitPush)
    • check Build periodically
      • enter a Schedule, like "@daily @midnight" (click the help button for loads of other options)
  • Build Environment
    • check Delete workspace before build starts
  • Build
    • choose Add build step -> Set build status to "pending" on GitHub commit
    • choose Add build step -> Execute shell
      • paste in a command (see Generating a Job Script, below)
  • Post-build Actions
    • choose Add post-build action -> Set GitHub commit status (universal)
      • under What -> Status Result, choose One of default messages and statuses
    • choose Add post-build action -> Publish TAP Results
      • under Publish TAP Results -> Test results, enter "**/*.tap"
    • choose Add post-build action -> Delete workspace when build is done
  • choose Save

Testing a Job

Once you have created you job, you can test it out and view the results.

Manual Trigger

The easiest way to test a job is to trigger it manually.

From the Jenkins main page:

  • from the summary table, choose the name of a job, like "IBIOColorDetect"
  • choose Build Now

This will add a new build to the Build Table below. The job should start running in a few seconds. Note the number of the job, like "#8".

Viewing the Console Output

You view details of a completed or running job. The richest detail is probably the console output from the job run.

From the Jenkins main page:

  • from the summary table, choose the name of a job, like "IBIOColorDetect"
  • from the Build History table, choose a job number, like "#8"
  • choose Console Output

This will be a big execution log. For completed jobs, you can scroll around and search. For running, jobs, Jenkins will stream the latest output into the window so you can follow its execution.

GitHub Trigger

If your job is configured to run in response to GitHub pushes, you may want to test out the Jenkins-GitHub integration. One way to do this would be to go to GitHub and edit the README file.

If you are logged in to GitHub, you can do this right in the browser:

  • go to your GitHub repository, like IBIOColorDetect
  • choose README.md in the list of files
  • choose the "pen" icon to edit this file
  • find a typo and fix it
  • choose Commit changes

This should trigger a Jenkins build within a few seconds. On the Jenkins main page, you should see your new job listed in the Build Executor Status table.

Generating a Job Script

Part of creating a Jenkins job is filling in the command to run for the Execute shell Build step. In general, this could be any command that you want Jenkins to run.

For our purposes, we would like Jenkins to start up Matlab inside a Docker container, and to invoke the automated tests for our toolbox or project. Running the tests in Docker is good because it isolates each test run from the others Docker also allows us run tests locally using same container environment that Jenkins uses. This means that what we test can the same as what we'd use day to day, or during a big production run.

It takes several steps to set up a job like this:

  • decide the test command to run and the toolbox dependencies that need to be deployed
  • locate Matlab and make it available inside the Docker container
  • do other Docker container setup, like locating Java if needed
  • make the version of code that Jenkins is trying to tests available inside the Docker container
  • run the job and make Matlab exit with a status code that indicates success or failure

That could be a bit much to write by hand! MatlabJobSupport can help by generating a shell script that does all of the above. The idea is that you set up the tests you want to run, then let MatlabJobSupport print out a shell script that you can paste into your Jenkins job.

An good example is the script mjsExampleIsetbioValidations.m. This generates a Jenkins command that looks like this:

#!/bin/sh
## Begin script generated by mjsWriteDockerRunScript.m

# embed the Matlab job as JSON
JOB_JSON="{\"cleanupCommand\": \"\",\"diskGB\": null,\"jobCommand\": \"ieValidateFullAllAssert\",\"memoryGB\": null,\"name\": \"validateIsetbio\",\"setupCommand\": \"\",\"toolboxCommand\": \"tbUse(''isetbio'')\"}"

# find where Matlab is installed, dynamically
MATLAB_LINK="$(which matlab)"
MATLAB_EXECUTABLE="$(readlink -f "$MATLAB_LINK")"
MATLAB_BIN_DIR="$(dirname "$MATLAB_EXECUTABLE")"
MATLAB_DIR="$(dirname "$MATLAB_BIN_DIR")"

# use the Java that comes with with Matlab
JAVA_HOME="/usr/local/MATLAB/from-host/sys/java/jre/glnxa64/jre"

# refresh the Docker image
docker pull "ninjaben/mjs-base:latest"

# invoke "docker run" with lots of options 
# using conventions established in ninjaben/mjs-base
docker run --rm --net=host \
  -v "$MATLAB_DIR":/usr/local/MATLAB/from-host \
  -v "$WORKSPACE":/mjs/projects \
  -v "$WORKSPACE":/opt/toolboxes \
  -e "INPUT_DIR=/var/mjs" \
  -e "OUTPUT_DIR=/var/mjs" \
  -e "WORKING_DIR=/var/mjs" \
  -e "JAVA_HOME=$JAVA_HOME" \
  ninjaben/mjs-base:latest \
  -r "mjsRunJobAndExit('$JOB_JSON');"

## End script generated by mjsWriteDockerRunScript.m

Matlab Integration

Matlab Integration

Viewing TAP Test Results

Clone this wiki locally