API referenceΒΆ
See examples at Example usage
-
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.
-
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
- name – Job name,
-
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:
>>> j = Jenkins() >>> next_build_number = j.get_job_info('build_name')['nextBuildNumber'] >>> output = j.build_job('build_name') >>> from time import sleep; sleep(10) >>> build_info = j.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'}
- name – Job name,
-
get_queue_info
() Returns: list of job dictionaries, [dict]
- Example::
>>> j = Jenkins() >>> queue_info = j.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:
>>> j = Jenkins() >>> info = j.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:
>>> j = Jenkins() >>> info = j.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:
>>> j = Jenkins() >>> info = j.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:
>>> j = Jenkins() >>> info = j.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}
- name – Name (short or long) of plugin,
-
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
- from_name – Name of Jenkins job to copy from,
-
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
- from_name – Name of Jenkins job to rename,
-
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- name – Name of Jenkins job,
-
create_job
(name, config_xml) Create a new Jenkins job
Parameters: - name – Name of Jenkins job,
str
- config_xml – config file text,
str
- name – Name of Jenkins job,
-
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
- name – Name of Jenkins job,
-
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
- parameters – parameters for job, or None.,
-
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::
>>> j = Jenkins() >>> info = j.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
- name – Name of Jenkins job,
-
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
- name – Node name,
-
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- name – Name of Jenkins node,
-
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
- name – Jenkins node name,
-
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
- name – name of node to create,
-
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
- name – Jenkins node name,
-
get_build_console_output
(name, number) Get build console text.
Parameters: - name – Job name,
str
- name – Build number,
int
Returns: Build console output,
str
- name – Job name,
-
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- name – Name of Jenkins view,
-
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
- name – Name of Jenkins view,
-
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
- name – Name of Jenkins view,
-
get_view_config
(name) Get configuration of existing Jenkins view.
Parameters: name – Name of Jenkins view, str
Returns: view configuration (XML format)
- username – Server username,