Python and the Jenkins API

Alan Christie 2018-06-18

Automation

The Python Jenkins module is a convenient wrapper for the Jenkins REST API that gives you control of a Jenkins server in a pythonic way. Here we’ll see how to grab all the jobs from a Jenkins server and also how these jobs can be re-created from the captured material.

Jenkins is one of the most populate CI/CD frameworks with plugins that provide you with the means to automate, build, test and deploy just about any project.

And Python? Well, we all know about Python, right?

The Python module we’ll be looking at here is available on PyPi. Just search for python-jenkins. You can reads its documentations on read the docs.

Connecting to the server

In order to interact with Jenkins you’ll need a JenkinsServer() instance, a Jenkins login ID and an API token.

You can find your Jenkins user ID and API token from the Jenkins console. When logged-in navigate the account’s Configure page, normally found using your login name, found in the top-right-hand part of the Jenkins console. From there you should be be able to expose your User ID and API Token by clicking Show API Token….

Rather than copying these directly into your Python code, create two environment variables to hold these values, say JENKINS_ID and JENKINS_TOKEN. These will allow you to commit your code to a revision control system while keeping your login credentials secret.

Here’s a code excerpt that can be used to create your server instance using the environment variables we’ve mentioned. Obviously change the J_ADDR value to match your Jenkins instance: -

import os
import jenkins

J_ID = os.environ['JENKINS_ID']
J_TOKEN = os.environ['JENKINS_TOKEN']
J_ADDR = 'myjenkins.com'

J_URL = 'https://%s:%s@%s' % (J_ID, J_TOKEN, J_ADDR)
J_SERVER =  jenkins.Jenkins(J_URL)

Of course you might want to protect the creation of the JS instance with a try/except block. For now I’ve left the error handling out of the code for the sake of clarity.

If SSL certificates are not properly installed you may need to defeat the built-in SSL validation that takes place. You can do this with the environment variable PYTHONHTTPSVERIFY by setting it to 0.

Reading job configurations

Armed with a connection to the server you can now call API methods. For now we’ll concentrate on getting all the Jobs from the server and writing each configuration to a file. We do this by first getting the Job names and then getting the Job configurations (which will be presented to us as a string of XML).

jobs = J_SERVER.get_jobs()
for job in jobs:
    job_name = job['name']
    job_config = J_SERVER.get_job_config(job_name)
    job_file = open(job_name + '.xml', 'w')
    job_file.write(job_config)
    job_file.close()

Writing job configurations

You can use the saved Job configurations to restore a Job on a Jenkins server using the create_job() or reconfig_job() API methods, depending on whether the Job already exists. For example, given a configuration file Project.xml you can create or restore the job with the following: -

job_name = `Project`
job_file = job_name + '.xml'
job_config = open(job_file, 'r').read()
if J_SERVER.job_exists(job_name):
    J_SEREVR.reconfig_job(job_name, job_config)
else:
    J_SERVER.create_job(job_name, job_config)

Obviously you can add structure to the code by creating class to represent the server instance and then add methods for the get() and set() operations.

Over to you

We’ve only covered the getting and setting of Job configurations but the Jenkins Python API exposes a lot more in order to fully automate the provisioning of a Jenkins server. Take a look at the documentation and see if there’s something of interest in there for you.

Addendum (25 Jun 2018)

We’ve published a simple Python module to PyPI (im-jenkins-utils) that contains the ability, via an ImJenkinsServer class, to read and write Job configurations from a Jenkins server (given its URL, user and token) as well as the ability to set secret text, file and username/password credentials.