Jenkins and Python

I have spent a fair amount of time at work setting up a continuous integration server, Jenkins, with our Python applications. Jenkins is a nice piece of software. But it can get rough on edges sometimes.

I will go through:

• install Jenkins on Ubuntu
• clone and install a Python application in a virtualenv
• run tests using nose and publish tests results, code coverage and pylint reports
• have Github notify Jenkins when new code is pushed

Install Jenkins

With Ubuntu, Jenkins installs smoothly:

wget -q -O - http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key | sudo apt-key add -
sudo sh -c 'echo deb http://pkg.jenkins-ci.org/debian binary/ > /etc/apt/sources.list.d/jenkins.list'
sudo aptitude update
sudo aptitude install jenkins

Jenkins will start automatically on port 8080.


Setup a Jenkins job

Create a new job and call it something without spaces! Jenkins creates a directory of the same name on the filesystem, but pip (or virtualenv?) will choke on spaces. Then select "Build a free-style software project".

To clone a git repo, you can use the Jenkins GIT plugin. Once installed, go to "Configure System" and under "Git plugin" set the variables for Global "Config user.name" and "Global Config user.email" (required by the plugin to tag the source on each build).

Return to your project and under "Source Code Management", configure the repo you want to clone. I pass the git Read-Only URL.

If you run "Build Now", it should clone your Github repo. You can make sure the files show up under your project's "Workspace".

Run tests, build reports

Now we have the Python source code, we want to install it in a virtualenv. Under "Build", add a build step "Execute shell"

... and tweak the following code to fit your needs:

PYENV_HOME=$WORKSPACE/.pyenv/

# Delete previously built virtualenv
if [ -d $PYENV_HOME ]; then
    rm -rf $PYENV_HOME
fi

# Create virtualenv and install necessary packages
virtualenv --no-site-packages $PYENV_HOME
. $PYENV_HOME/bin/activate
pip install --quiet nosexcover
pip install --quiet pylint
pip install --quiet $WORKSPACE/  # where your setup.py lives
nosetests --with-xcoverage --with-xunit --cover-package=myapp --cover-erase
pylint -f parseable myapp/ | tee pylint.out

As much as I love virtualenvwrapper, don't use it -- it really doesn't make sense for automated tasks. Moveover, you want your job's workspace to be self-contained, whereas virtualenvwrapper wants to keep your virtualenvs in a common place, typically ~/.virtualenvs.

The environment variable $WORKSPACE is made available during the script execution, it's the path to where Jenkins creates your build, e.g., /var/lib/jenkins/jobs/foo/workspace/.

The package nosexcover (don't misread it) is a nose plugin that introduces the --with-xcoverage nose option. It generates Cobertura-style XML reports.


Interpreting reports

When nose runs, it will generate report files in your workspace that Jenkins has to interpret.

• nosetests.xml: This file is generated by the --with-xunit option and can be interpreted by checking "Publish JUnit test result report"

• coverage.xml: The coverage file is generated by --with-xcoverage. Jenkins can interpret this report after installing the Cobertura plugin. It will be available as "Publish Cobertura Coverage Report", and the report pattern must be **/coverage.xml.

• pylint.out: For this one, you have to install the Violations plugin, which will make the checkbox "Report Violations" available. The plugin supports a bunch of different reports. Look for "pylint" and enter **/pylint.out as the "XML filename pattern".

Run "Build Now" and tweak the Shell script until nose runs all the way through (regardless if your tests pass). Make sure the report files are generated. Eventually, you will get nice charts on your job's page.

Github, notify Jenkins!

Finally, we want to run the build every time your Github project receives new code (push). Let's have Jenkins ready to receive notifications from Github. We need to check "Trigger builds remotely (e.g., from scripts)".

NOTE: This checkbox only shows up if you check "Enable security" at the server configuration level and set a "Security Realm".

Once enabled, set the "Authentication Token" to, e.g., GIT_PUSH_NOTIFY.

Now go to your Github project page, click the "Admin" button to configure a "Post-Receive URLs" service hook, and copy/paste the URL given under the "Authentication Token" input field.

Finally replace, the JENKINS_URL part by the URL to your own Jenkins server. Github has a "Test hook" button to simulate a code push and trigger an actual HTTP call. Jenkins should start building your Python project automatically.