See examples at Using Python-Jenkins
General exception type for jenkins-API-related failures.
A special exception to call out the case of receiving a 404.
A special exception to call out the case receiving an empty response.
A special exception to call out the case of a broken HTTP response.
A special exception to call out in the case of a socket timeout.
Simple implementation of HTTP Basic Authentication.
Returns the ‘Authentication’ header value.
Create handle to Jenkins instance.
All methods will raise JenkinsException on failure.
Parameters: |
|
---|
Get job information dictionary.
Parameters: |
|
---|---|
Returns: | dictionary of job information |
Parameters: |
|
---|---|
Returns: | List of jobs info, list |
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 |
Print out job info in more readable format.
Utility routine for opening an HTTP request to a Jenkins server.
This should only be used to extends the Jenkins API.
Get build information dictionary.
Parameters: |
|
---|---|
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'}
Returns: | list of job dictionaries, [dict] |
---|
>>> 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 a queued build.
Parameters: | id – Jenkins job id number for the build, int |
---|
Get information on this Master or item on Master.
This information includes job list and view information and can be used to retreive information on items such as job folders.
Parameters: |
|
---|---|
Returns: | dictionary of information about Master or item, 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 the version of this Master.
Returns: | This master’s version number str |
---|
Example:
>>> info = server.get_version()
>>> print info
>>> 1.541
Get all installed plugins information on this Master.
This method retrieves information about each plugin that is installed on master returning the raw plugin data in a JSON format.
Deprecated since version 0.4.9: Use get_plugins() instead.
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 an installed plugin information on this Master.
This method retrieves information about a specific plugin and returns the raw plugin data in a JSON format. The passed in plugin name (short or long) must be an exact match.
Note
Calling this method will query Jenkins fresh for the information for all plugins on each call. If you need to retrieve information for multiple plugins it’s recommended to use get_plugins() instead, which will return a multi key dictionary that can be accessed via either the short or long name of the plugin.
Parameters: |
|
---|---|
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}
Return plugins info using helper class for version comparison
This method retrieves information about all the installed plugins and uses a Plugin helper class to simplify version comparison. Also uses a multi key dict to allow retrieval via either short or long names.
When printing/dumping the data, the version will transparently return a unicode string, which is exactly what was previously returned by the API.
Parameters: | depth – JSON depth, int |
---|---|
Returns: | info on all plugins [dict] |
Example:
>>> j = Jenkins()
>>> info = j.get_plugins()
>>> print(info)
{('gearman-plugin', 'Gearman Plugin'):
{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 list of jobs.
Each job is a dictionary with ‘name’, ‘url’, ‘color’ and ‘fullname’ keys.
Parameters: | folder_depth – Number of levels to search, int. By default 0, which will limit search to toplevel. None disables the limit. |
---|---|
Returns: | list of jobs, [ { str: str} ] |
Get list of all jobs recursively to the given folder depth.
Each job is a dictionary with ‘name’, ‘url’, ‘color’ and ‘fullname’ keys.
Parameters: | folder_depth – Number of levels to search, int. By default None, which will search all levels. 0 limits to toplevel. |
---|---|
Returns: | list of jobs, [ { str: str} ] |
Note
On instances with many folders it may be more efficient to use the run_script method to retrieve all jobs instead.
Example:
server.run_script("""
import groovy.json.JsonBuilder;
// get all projects excluding matrix configuration
// as they are simply part of a matrix project.
// there may be better ways to get just jobs
items = Jenkins.instance.getAllItems(AbstractProject);
items.removeAll {
it instanceof hudson.matrix.MatrixConfiguration
};
def json = new JsonBuilder()
def root = json {
jobs items.collect {
[
name: it.name,
url: Jenkins.instance.getRootUrl() + it.getUrl(),
color: it.getIconColor().toString(),
fullname: it.getFullName()
]
}
}
// use json.toPrettyString() if viewing
println json.toString()
""")
Copy a Jenkins job.
Will raise an exception whenever the source and destination folder for this jobs won’t be the same.
Parameters: |
|
---|---|
Throws: | JenkinsException whenever the source and destination folder are not the same |
Rename an existing Jenkins job
Will raise an exception whenever the source and destination folder for this jobs won’t be the same.
Parameters: |
|
---|---|
Throws: | JenkinsException whenever the source and destination folder are not the same |
Delete Jenkins job permanently.
Parameters: | name – Name of Jenkins job, str |
---|
Enable Jenkins job.
Parameters: | name – Name of Jenkins job, str |
---|
Disable Jenkins job.
To re-enable, call Jenkins.enable_job().
Parameters: | name – Name of Jenkins job, str |
---|
Set a job’s next build number.
The current next build number is contained within the job information retrieved using Jenkins.get_job_info(). If the specified next build number is less than the last build number, Jenkins will ignore the request.
Note that the Next Build Number Plugin must be installed to enable this functionality.
Parameters: |
|
---|
Example:
>>> next_bn = server.get_job_info('job_name')['nextBuildNumber']
>>> server.set_next_build_number('job_name', next_bn + 50)
Check whether a job exists
Parameters: | name – Name of Jenkins job, str |
---|---|
Returns: | True if Jenkins job exists |
Get the number of jobs on the Jenkins server
Returns: | Total number of jobs, int |
---|
Note
On instances with many folders it may be more efficient to use the run_script method to retrieve the total number of jobs instead.
Example:
# get all projects excluding matrix configuration
# as they are simply part of a matrix project.
server.run_script(
"print(Hudson.instance.getAllItems("
" hudson.model.AbstractProject).count{"
" !(it instanceof hudson.matrix.MatrixConfiguration)"
" })")
Raise an exception if a job does not exist
Parameters: |
|
---|---|
Throws: | JenkinsException whenever the job does not exist |
Create a new Jenkins job
Parameters: |
|
---|
Get configuration of existing Jenkins job.
Parameters: | name – Name of Jenkins job, str |
---|---|
Returns: | job configuration (XML format) |
Change configuration of existing Jenkins job.
To create a new job, see Jenkins.create_job().
Parameters: |
|
---|
Get URL to trigger build job.
Authenticated setups may require configuring a token on the server side.
Parameters: |
|
---|---|
Returns: | URL for building job |
Trigger build job.
Parameters: |
|
---|
Execute a groovy script on the jenkins master.
Parameters: | script – The groovy script, string |
---|---|
Returns: | The result of the script run. |
>>> 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]'
Install a plugin and its dependencies from the Jenkins public repository at http://repo.jenkins-ci.org/repo/org/jenkins-ci/plugins
Parameters: |
|
---|---|
Returns: | Whether a Jenkins restart is required, bool |
>>> info = server.install_plugin("jabber")
>>> print(info)
True
Stop a running Jenkins build.
Parameters: |
|
---|
Return list of running builds.
Each build is a dict with keys ‘name’, ‘number’, ‘url’, ‘node’, and ‘executor’.
Returns: | List of builds, [ { str: str, str: int, str:str, str: str, str: int} ] |
---|
>>> builds = server.get_running_builds()
>>> print(builds)
[{'node': 'foo-slave', 'url': 'https://localhost/job/test/15/',
'executor': 0, 'name': 'test', 'number': 15}]
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 information dictionary
Parameters: |
|
---|---|
Returns: | Dictionary of node info, dict |
Check whether a node exists
Parameters: | name – Name of Jenkins node, str |
---|---|
Returns: | True if Jenkins node exists |
Raise an exception if a node does not exist
Parameters: |
|
---|---|
Throws: | JenkinsException whenever the node does not exist |
Delete Jenkins node permanently.
Parameters: | name – Name of Jenkins node, str |
---|
Disable a node
Parameters: |
|
---|
Enable a node
Parameters: | name – Jenkins node name, str |
---|
Create a node
Parameters: |
|
---|
Get the configuration for a node.
Parameters: | name – Jenkins node name, str |
---|
Change the configuration for an existing node.
Parameters: |
|
---|
Get build console text.
Parameters: |
|
---|---|
Returns: | Build console output, str |
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 |
Raise an exception if a view does not exist
Parameters: |
|
---|---|
Throws: | JenkinsException whenever the view does not exist |
Check whether a view exists
Parameters: | name – Name of Jenkins view, str |
---|---|
Returns: | True if Jenkins view exists |
Get list of views running.
Each view is a dictionary with ‘name’ and ‘url’ keys.
Returns: | list of views, [ { str: str} ] |
---|
Delete Jenkins view permanently.
Parameters: | name – Name of Jenkins view, str |
---|
Create a new Jenkins view
Parameters: |
|
---|
Change configuration of existing Jenkins view.
To create a new view, see Jenkins.create_view().
Parameters: |
|
---|
Get configuration of existing Jenkins view.
Parameters: | name – Name of Jenkins view, str |
---|---|
Returns: | view configuration (XML format) |
Prepare Jenkins for shutdown.
No new builds will be started allowing running builds to complete prior to shutdown of the server.
Dictionary object containing plugin metadata.
Populates dictionary using json object input.
accepts same arguments as python dict class.
Class providing comparison capabilities for plugin versions.
Parse plugin version and store it for comparison.