API reference

See examples at Using Python-Jenkins

exception jenkins.JenkinsException

General exception type for jenkins-API-related failures.

exception jenkins.NotFoundException

A special exception to call out the case of receiving a 404.

exception jenkins.EmptyResponseException

A special exception to call out the case receiving an empty response.

exception jenkins.BadHTTPException

A special exception to call out the case of a broken HTTP response.

exception jenkins.TimeoutException

A special exception to call out in the case of a socket timeout.

jenkins.auth_headers(username, password)

Simple implementation of HTTP Basic Authentication.

Returns the ‘Authentication’ header value.

class jenkins.Jenkins(url, username=None, password=None, timeout=<object object>)

Create handle to Jenkins instance.

All methods will raise JenkinsException on failure.

Parameters:
  • username – Server username, str
  • password – Server password, str
  • url – URL of Jenkins server, str
  • timeout – Server connection timeout in secs (default: not set), int
maybe_add_crumb(req)
get_job_info(name, depth=0)

Get job information dictionary.

Parameters:
  • name – Job name, str
  • depth – JSON depth, int
Returns:

dictionary of job information
get_job_info_regex(pattern, depth=0)
Get a list of jobs information that contain names which match the
regex pattern.
Parameters:
  • pattern – regex pattern, str
  • depth – JSON depth, int
Returns:

List of jobs info, list
get_job_name(name)

Return the name of a job using the API.

That is roughly an identity method which can be used to quickly verify a job exist or is accessible without causing too much stress on the server side.

Parameters:name – Job name, str
Returns:Name of job or None
debug_job_info(job_name)

Print out job info in more readable format.

jenkins_open(req, add_crumb=True)

Utility routine for opening an HTTP request to a Jenkins server.

This should only be used to extends the Jenkins API.

get_build_info(name, number, depth=0)

Get build information dictionary.

Parameters:
  • name – Job name, str
  • name – Build number, int
  • depth – JSON depth, int
Returns:

dictionary of build information, dict

Example:

>>> next_build_number = server.get_job_info('build_name')['nextBuildNumber']
>>> output = server.build_job('build_name')
>>> from time import sleep; sleep(10)
>>> build_info = server.get_build_info('build_name', next_build_number)
>>> print(build_info)
{u'building': False, u'changeSet': {u'items': [{u'date': u'2011-12-19T18:01:52.540557Z', u'msg': u'test', u'revision': 66, u'user': u'unknown', u'paths': [{u'editType': u'edit', u'file': u'/branches/demo/index.html'}]}], u'kind': u'svn', u'revisions': [{u'module': u'http://eaas-svn01.i3.level3.com/eaas', u'revision': 66}]}, u'builtOn': u'', u'description': None, u'artifacts': [{u'relativePath': u'dist/eaas-87-2011-12-19_18-01-57.war', u'displayPath': u'eaas-87-2011-12-19_18-01-57.war', u'fileName': u'eaas-87-2011-12-19_18-01-57.war'}, {u'relativePath': u'dist/eaas-87-2011-12-19_18-01-57.war.zip', u'displayPath': u'eaas-87-2011-12-19_18-01-57.war.zip', u'fileName': u'eaas-87-2011-12-19_18-01-57.war.zip'}], u'timestamp': 1324317717000, u'number': 87, u'actions': [{u'parameters': [{u'name': u'SERVICE_NAME', u'value': u'eaas'}, {u'name': u'PROJECT_NAME', u'value': u'demo'}]}, {u'causes': [{u'userName': u'anonymous', u'shortDescription': u'Started by user anonymous'}]}, {}, {}, {}], u'id': u'2011-12-19_18-01-57', u'keepLog': False, u'url': u'http://eaas-jenkins01.i3.level3.com:9080/job/build_war/87/', u'culprits': [{u'absoluteUrl': u'http://eaas-jenkins01.i3.level3.com:9080/user/unknown', u'fullName': u'unknown'}], u'result': u'SUCCESS', u'duration': 8826, u'fullDisplayName': u'build_war #87'}
get_queue_info()
Returns:list of job dictionaries, [dict]
Example::
>>> queue_info = server.get_queue_info()
>>> print(queue_info[0])
{u'task': {u'url': u'http://your_url/job/my_job/', u'color': u'aborted_anime', u'name': u'my_job'}, u'stuck': False, u'actions': [{u'causes': [{u'shortDescription': u'Started by timer'}]}], u'buildable': False, u'params': u'', u'buildableStartMilliseconds': 1315087293316, u'why': u'Build #2,532 is already in progress (ETA:10 min)', u'blocked': True}
cancel_queue(id)

Cancel a queued build.

Parameters:id – Jenkins job id number for the build, int
get_info()

Get information on this Master.

This information includes job list and view information.

Returns:dictionary of information about Master, dict

Example:

>>> info = server.get_info()
>>> jobs = info['jobs']
>>> print(jobs[0])
{u'url': u'http://your_url_here/job/my_job/', u'color': u'blue',
u'name': u'my_job'}
get_version()

Get the version of this Master.

Returns:This master’s version number str

Example:

>>> info = server.get_version()
>>> print info
>>> 1.541
get_plugins_info(depth=2)

Get all installed plugins information on this Master.

This method retrieves information about each plugin that is installed on master.

Parameters:depth – JSON depth, int
Returns:info on all plugins [dict]

Example:

>>> info = server.get_plugins_info()
>>> print(info)
[{u'backupVersion': None, u'version': u'0.0.4', u'deleted': False,
u'supportsDynamicLoad': u'MAYBE', u'hasUpdate': True,
u'enabled': True, u'pinned': False, u'downgradable': False,
u'dependencies': [], u'url':
u'http://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin',
u'longName': u'Gearman Plugin', u'active': True, u'shortName':
u'gearman-plugin', u'bundled': False}, ..]
get_plugin_info(name, depth=2)

Get an installed plugin information on this Master.

This method retrieves information about a speicifc plugin. The passed in plugin name (short or long) must be an exact match.

Parameters:
  • name – Name (short or long) of plugin, str
  • depth – JSON depth, int
Returns:

a specific plugin dict

Example:

>>> info = server.get_plugin_info("Gearman Plugin")
>>> print(info)
{u'backupVersion': None, u'version': u'0.0.4', u'deleted': False,
u'supportsDynamicLoad': u'MAYBE', u'hasUpdate': True,
u'enabled': True, u'pinned': False, u'downgradable': False,
u'dependencies': [], u'url':
u'http://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin',
u'longName': u'Gearman Plugin', u'active': True, u'shortName':
u'gearman-plugin', u'bundled': False}
get_jobs()

Get list of jobs running.

Each job is a dictionary with ‘name’, ‘url’, and ‘color’ keys.

Returns:list of jobs, [ { str: str} ]
copy_job(from_name, to_name)

Copy a Jenkins job

Parameters:
  • from_name – Name of Jenkins job to copy from, str
  • to_name – Name of Jenkins job to copy to, str
rename_job(from_name, to_name)

Rename an existing Jenkins job

Parameters:
  • from_name – Name of Jenkins job to rename, str
  • to_name – New Jenkins job name, str
delete_job(name)

Delete Jenkins job permanently.

Parameters:name – Name of Jenkins job, str
enable_job(name)

Enable Jenkins job.

Parameters:name – Name of Jenkins job, str
disable_job(name)

Disable Jenkins job.

To re-enable, call Jenkins.enable_job().

Parameters:name – Name of Jenkins job, str
job_exists(name)

Check whether a job exists

Parameters:name – Name of Jenkins job, str
Returns:True if Jenkins job exists
jobs_count()

Get the number of jobs on the Jenkins server

Returns:Total number of jobs, int
assert_job_exists(name, exception_message='job[%s] does not exist')

Raise an exception if a job does not exist

Parameters:
  • name – Name of Jenkins job, str
  • exception_message – Message to use for the exception. Formatted with name
Throws:

JenkinsException whenever the job does not exist
create_job(name, config_xml)

Create a new Jenkins job

Parameters:
  • name – Name of Jenkins job, str
  • config_xml – config file text, str
get_job_config(name)

Get configuration of existing Jenkins job.

Parameters:name – Name of Jenkins job, str
Returns:job configuration (XML format)
reconfig_job(name, config_xml)

Change configuration of existing Jenkins job.

To create a new job, see Jenkins.create_job().

Parameters:
  • name – Name of Jenkins job, str
  • config_xml – New XML configuration, str
build_job_url(name, parameters=None, token=None)

Get URL to trigger build job.

Authenticated setups may require configuring a token on the server side.

Parameters:
  • parameters – parameters for job, or None., dict
  • token – (optional) token for building job, str
Returns:

URL for building job
build_job(name, parameters=None, token=None)

Trigger build job.

Parameters:
  • name – name of job
  • parameters – parameters for job, or None, dict
  • token – Jenkins API token
run_script(script)

Execute a groovy script on the jenkins master.

Parameters:script – The groovy script, string
Returns:The result of the script run.
Example::
>>> info = server.run_script("println(Jenkins.instance.pluginManager.plugins)")
>>> print(info)
u'[Plugin:windows-slaves, Plugin:ssh-slaves, Plugin:translation,
Plugin:cvs, Plugin:nodelabelparameter, Plugin:external-monitor-job,
Plugin:mailer, Plugin:jquery, Plugin:antisamy-markup-formatter,
Plugin:maven-plugin, Plugin:pam-auth]'
stop_build(name, number)

Stop a running Jenkins build.

Parameters:
  • name – Name of Jenkins job, str
  • number – Jenkins build number for the job, int
get_nodes()

Get a list of nodes connected to the Master

Each node is a dict with keys ‘name’ and ‘offline’

Returns:List of nodes, [ { str: str, str: bool} ]
get_node_info(name, depth=0)

Get node information dictionary

Parameters:
  • name – Node name, str
  • depth – JSON depth, int
Returns:

Dictionary of node info, dict
node_exists(name)

Check whether a node exists

Parameters:name – Name of Jenkins node, str
Returns:True if Jenkins node exists
assert_node_exists(name, exception_message='node[%s] does not exist')

Raise an exception if a node does not exist

Parameters:
  • name – Name of Jenkins node, str
  • exception_message – Message to use for the exception. Formatted with name
Throws:

JenkinsException whenever the node does not exist
delete_node(name)

Delete Jenkins node permanently.

Parameters:name – Name of Jenkins node, str
disable_node(name, msg='')

Disable a node

Parameters:
  • name – Jenkins node name, str
  • msg – Offline message, str
enable_node(name)

Enable a node

Parameters:name – Jenkins node name, str
create_node(name, numExecutors=2, nodeDescription=None, remoteFS='/var/lib/jenkins', labels=None, exclusive=False, launcher='hudson.slaves.CommandLauncher', launcher_params={})

Create a node

Parameters:
  • name – name of node to create, str
  • numExecutors – number of executors for node, int
  • nodeDescription – Description of node, str
  • remoteFS – Remote filesystem location to use, str
  • labels – Labels to associate with node, str
  • exclusive – Use this node for tied jobs only, bool
  • launcher – The launch method for the slave, jenkins.LAUNCHER_COMMAND, jenkins.LAUNCHER_SSH, jenkins.LAUNCHER_JNLP, jenkins.LAUNCHER_WINDOWS_SERVICE
  • launcher_params – Additional parameters for the launcher, dict
get_node_config(name)

Get the configuration for a node.

Parameters:name – Jenkins node name, str
reconfig_node(name, config_xml)

Change the configuration for an existing node.

Parameters:
  • name – Jenkins node name, str
  • config_xml – New XML configuration, str
get_build_console_output(name, number)

Get build console text.

Parameters:
  • name – Job name, str
  • name – Build number, int
Returns:

Build console output, str
get_view_name(name)

Return the name of a view using the API.

That is roughly an identity method which can be used to quickly verify a view exists or is accessible without causing too much stress on the server side.

Parameters:name – View name, str
Returns:Name of view or None
assert_view_exists(name, exception_message='view[%s] does not exist')

Raise an exception if a view does not exist

Parameters:
  • name – Name of Jenkins view, str
  • exception_message – Message to use for the exception. Formatted with name
Throws:

JenkinsException whenever the view does not exist
view_exists(name)

Check whether a view exists

Parameters:name – Name of Jenkins view, str
Returns:True if Jenkins view exists
get_views()

Get list of views running.

Each view is a dictionary with ‘name’ and ‘url’ keys.

Returns:list of views, [ { str: str} ]
delete_view(name)

Delete Jenkins view permanently.

Parameters:name – Name of Jenkins view, str
create_view(name, config_xml)

Create a new Jenkins view

Parameters:
  • name – Name of Jenkins view, str
  • config_xml – config file text, str
reconfig_view(name, config_xml)

Change configuration of existing Jenkins view.

To create a new view, see Jenkins.create_view().

Parameters:
  • name – Name of Jenkins view, str
  • config_xml – New XML configuration, str
get_view_config(name)

Get configuration of existing Jenkins view.

Parameters:name – Name of Jenkins view, str
Returns:view configuration (XML format)