1PYTHONJENKINS(1) Python Jenkins PYTHONJENKINS(1)
2
6 pythonjenkins - Python Jenkins Documentation
7 Python Jenkins is a python wrapper for the Jenkins REST API which aims
9 to provide a more conventionally pythonic way of controlling a Jenkins
10 server. It provides a higher-level API containing a number of conve‐
11 nience functions.
12 We like to use python-jenkins to automate our Jenkins servers. Here are
14 some of the things you can use it for:
15 • Create new jobs
17 • Copy existing jobs
19 • Delete jobs
21 • Update jobs
23 • Get a job's build information
25 • Get Jenkins master version information
27 • Get Jenkins plugin information
29 • Start a build on a job
31 • Create nodes
33 • Enable/Disable nodes
35 • Get information on nodes
37 • Create/delete/reconfig views
39 • Put server in shutdown mode (quiet down)
41 • List running builds
43 • Delete builds
45 • Wipeout job workspace
47 • Create/delete/update folders [1]
49 • Set the next build number [2]
51 • Install plugins
53 • and many more..
55 To install:
57 $ sudo python setup.py install
59 Online documentation:
61 • http://python-jenkins.readthedocs.org/en/latest/
63
65 Bug report:
66 • https://bugs.launchpad.net/python-jenkins
68 Repository:
70 • https://git.openstack.org/cgit/openstack/python-jenkins
72 Cloning:
74 • git clone https://git.openstack.org/openstack/python-jenkins
76 Patches are submitted via Gerrit at:
78 • https://review.openstack.org/
80 Please do not submit GitHub pull requests, they will be automatically
82 closed.
83 The python-jenkins developers communicate in the #openstack-jjb channel
85 on Freenode's IRC network.
86 More details on how you can contribute is available on our wiki at:
88 • http://docs.openstack.org/infra/manual/developers.html
90
92 Be sure that you lint code before created an code review. The easiest
93 way to do this is to install git pre-commit hooks.
94
96 Then install the required python packages using pip:
97 $ sudo pip install python-jenkins
99
101 [1] The free Cloudbees Folders Plugin provides support for a subset of
102 the full folders functionality. For the complete capabilities you
103 will need the paid for version of the plugin.
104 [2] The Next Build Number Plugin provides support for setting the next
106 build number.
107
109 See examples at Using Python-Jenkins
110 exception jenkins.JenkinsException
112 General exception type for jenkins-API-related failures.
113 exception jenkins.NotFoundException
115 A special exception to call out the case of receiving a 404.
116 exception jenkins.EmptyResponseException
118 A special exception to call out the case receiving an empty re‐
119 sponse.
120 exception jenkins.BadHTTPException
122 A special exception to call out the case of a broken HTTP re‐
123 sponse.
124 exception jenkins.TimeoutException
126 A special exception to call out in the case of a socket timeout.
127 class jenkins.WrappedSession
129 A wrapper for requests.Session to override 'verify' property,
130 ignoring REQUESTS_CA_BUNDLE environment variable.
131 This is a workaround for
133 https://github.com/kennethreitz/requests/issues/3829 (will be
134 fixed in requests 3.0.0)
135 merge_environment_settings(url, proxies, stream, verify, *args,
137 **kwargs)
138 Check the environment and merge it with some settings.
139 Return type
141 dict
142 class jenkins.Jenkins(url, username=None, password=None, timeout=<ob‐
144 ject object>)
145 Create handle to Jenkins instance.
146 All methods will raise JenkinsException on failure.
148 Parameters
150 • url -- URL of Jenkins server, str
152 • username -- Server username, str
154 • password -- Server password, str
156 • timeout -- Server connection timeout in secs (default:
158 not set), int
159 maybe_add_crumb(req)
161 get_job_info(name, depth=0, fetch_all_builds=False)
163 Get job information dictionary.
164 Parameters
166 • name -- Job name, str
168 • depth -- JSON depth, int
170 • fetch_all_builds -- If true, all builds will be
172 retrieved from Jenkins. Otherwise, Jenkins will
173 only return the most recent 100 builds. This
174 comes at the expense of an additional API call
175 which may return significant amounts of data.
176 bool
177 Returns
179 dictionary of job information
180 get_job_info_regex(pattern, depth=0, folder_depth=0,
182 folder_depth_per_request=10)
183 Get a list of jobs information that contain names which
185 match the
186 regex pattern.
187 Parameters
189 • pattern -- regex pattern, str
191 • depth -- JSON depth, int
193 • folder_depth -- folder level depth to search int
195 • folder_depth_per_request -- Number of levels to
197 fetch at once, int. See get_all_jobs().
198 Returns
200 List of jobs info, list
201 get_job_name(name)
203 Return the name of a job using the API.
204 That is roughly an identity method which can be used to
206 quickly verify a job exists or is accessible without
207 causing too much stress on the server side.
208 Parameters
210 name -- Job name, str
211 Returns
213 Name of job or None
214 debug_job_info(job_name)
216 Print out job info in more readable format.
217 jenkins_open(req, add_crumb=True, resolve_auth=True)
219 Return the HTTP response body from a requests.Request.
220 Returns
222 str
223 jenkins_request(req, add_crumb=True, resolve_auth=True)
225 Utility routine for opening an HTTP request to a Jenkins
226 server.
227 Parameters
229 • req -- A requests.Request to submit.
231 • add_crumb -- If True, try to add a crumb header
233 to this req before submitting. Defaults to True.
234 • resolve_auth -- If True, maybe add authentica‐
236 tion. Defaults to True.
237 Returns
239 A requests.Response object.
240 get_queue_item(number, depth=0)
242 Get information about a queued item (to-be-created job).
243 The returned dict will have a "why" key if the queued
245 item is still waiting for an executor.
246 The returned dict will have an "executable" key if the
248 queued item is running on an executor, or has completed
249 running. Use this to determine the job number / URL.
250 Parameters
252 name -- queue number, int
253 Returns
255 dictionary of queued information, dict
256 get_build_info(name, number, depth=0)
258 Get build information dictionary.
259 Parameters
261 • name -- Job name, str
263 • number -- Build number, int
265 • depth -- JSON depth, int
267 Returns
269 dictionary of build information, dict
270 Example:
272 >>> next_build_number = server.get_job_info('build_name')['nextBuildNumber']
274 >>> output = server.build_job('build_name')
275 >>> from time import sleep; sleep(10)
276 >>> build_info = server.get_build_info('build_name', next_build_number)
277 >>> print(build_info)
278 {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'}
279 get_build_env_vars(name, number, depth=0)
281 Get build environment variables.
282 Parameters
284 • name -- Job name, str
286 • number -- Build number, int
288 • depth -- JSON depth, int
290 Returns
292 dictionary of build env vars, dict or None for
293 workflow jobs, or if InjectEnvVars plugin not in‐
294 stalled
295 get_build_test_report(name, number, depth=0)
297 Get test results report.
298 Parameters
300 • name -- Job name, str
302 • number -- Build number, int
304 Returns
306 dictionary of test report results, dict or None if
307 there is no Test Report
308 get_queue_info()
310 Returns
312 list of job dictionaries, [dict]
313 Example::
315 >>> queue_info = server.get_queue_info()
317 >>> print(queue_info[0])
318 {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}
319 cancel_queue(id)
321 Cancel a queued build.
322 Parameters
324 id -- Jenkins job id number for the build, int
325 get_info(item='', query=None)
327 Get information on this Master or item on Master.
328 This information includes job list and view information
330 and can be used to retreive information on items such as
331 job folders.
332 Parameters
334 • item -- item to get information about on this
336 Master
337 • query -- xpath to extract information about on
339 this Master
340 Returns
342 dictionary of information about Master or item,
343 dict
344 Example:
346 >>> info = server.get_info()
348 >>> jobs = info['jobs']
349 >>> print(jobs[0])
350 {u'url': u'http://your_url_here/job/my_job/', u'color': u'blue',
351 u'name': u'my_job'}
352 get_whoami(depth=0)
354 Get information about the user account that authenticated
355 to Jenkins. This is a simple way to verify that your cre‐
356 dentials are correct.
357 Returns
359 Information about the current user dict
360 Example:
362 >>> me = server.get_whoami()
364 >>> print me['fullName']
365 >>> 'John'
366 get_version()
368 Get the version of this Master.
369 Returns
371 This master's version number str
372 Example:
374 >>> info = server.get_version()
376 >>> print info
377 >>> 1.541
378 get_plugins_info(depth=2)
380 Get all installed plugins information on this Master.
381 This method retrieves information about each plugin that
383 is installed on master returning the raw plugin data in a
384 JSON format.
385 Deprecated since version 0.4.9: Use get_plugins() in‐
387 stead.
388 Parameters
391 depth -- JSON depth, int
392 Returns
394 info on all plugins [dict]
395 Example:
397 >>> info = server.get_plugins_info()
399 >>> print(info)
400 [{u'backupVersion': None, u'version': u'0.0.4', u'deleted': False,
401 u'supportsDynamicLoad': u'MAYBE', u'hasUpdate': True,
402 u'enabled': True, u'pinned': False, u'downgradable': False,
403 u'dependencies': [], u'url':
404 u'http://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin',
405 u'longName': u'Gearman Plugin', u'active': True, u'shortName':
406 u'gearman-plugin', u'bundled': False}, ..]
407 get_plugin_info(name, depth=2)
409 Get an installed plugin information on this Master.
410 This method retrieves information about a specific plugin
412 and returns the raw plugin data in a JSON format. The
413 passed in plugin name (short or long) must be an exact
414 match.
415 NOTE:
417 Calling this method will query Jenkins fresh for the
418 information for all plugins on each call. If you need
419 to retrieve information for multiple plugins it's rec‐
420 ommended to use get_plugins() instead, which will re‐
421 turn a multi key dictionary that can be accessed via
422 either the short or long name of the plugin.
423 Parameters
425 • name -- Name (short or long) of plugin, str
427 • depth -- JSON depth, int
429 Returns
431 a specific plugin dict
432 Example:
434 >>> info = server.get_plugin_info("Gearman Plugin")
436 >>> print(info)
437 {u'backupVersion': None, u'version': u'0.0.4', u'deleted': False,
438 u'supportsDynamicLoad': u'MAYBE', u'hasUpdate': True,
439 u'enabled': True, u'pinned': False, u'downgradable': False,
440 u'dependencies': [], u'url':
441 u'http://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin',
442 u'longName': u'Gearman Plugin', u'active': True, u'shortName':
443 u'gearman-plugin', u'bundled': False}
444 get_plugins(depth=2)
446 Return plugins info using helper class for version com‐
447 parison
448 This method retrieves information about all the installed
450 plugins and uses a Plugin helper class to simplify ver‐
451 sion comparison. Also uses a multi key dict to allow re‐
452 trieval via either short or long names.
453 When printing/dumping the data, the version will trans‐
455 parently return a unicode string, which is exactly what
456 was previously returned by the API.
457 Parameters
459 depth -- JSON depth, int
460 Returns
462 info on all plugins [dict]
463 Example:
465 >>> j = Jenkins()
467 >>> info = j.get_plugins()
468 >>> print(info)
469 {('gearman-plugin', 'Gearman Plugin'):
470 {u'backupVersion': None, u'version': u'0.0.4',
471 u'deleted': False, u'supportsDynamicLoad': u'MAYBE',
472 u'hasUpdate': True, u'enabled': True, u'pinned': False,
473 u'downgradable': False, u'dependencies': [], u'url':
474 u'http://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin',
475 u'longName': u'Gearman Plugin', u'active': True, u'shortName':
476 u'gearman-plugin', u'bundled': False}, ...}
477 get_jobs(folder_depth=0, folder_depth_per_request=10,
479 view_name=None)
480 Get list of jobs.
481 Each job is a dictionary with 'name', 'url', 'color' and
483 'fullname' keys.
484 If the view_name parameter is present, the list of jobs
486 will be limited to only those configured in the specified
487 view. In this case, the job dictionary 'fullname' key
488 would be equal to the job name.
489 Parameters
491 • folder_depth -- Number of levels to search, int.
493 By default 0, which will limit search to
494 toplevel. None disables the limit.
495 • folder_depth_per_request -- Number of levels to
497 fetch at once, int. See get_all_jobs().
498 • view_name -- Name of a Jenkins view for which to
500 retrieve jobs, str. By default, the job list is
501 not limited to a specific view.
502 Returns
504 list of jobs, [{str: str, str: str, str: str, str:
505 str}]
506 Example:
508 >>> jobs = server.get_jobs()
510 >>> print(jobs)
511 [{
512 u'name': u'all_tests',
513 u'url': u'http://your_url.here/job/all_tests/',
514 u'color': u'blue',
515 u'fullname': u'all_tests'
516 }]
517 get_all_jobs(folder_depth=None, folder_depth_per_request=10)
519 Get list of all jobs recursively to the given folder
520 depth.
521 Each job is a dictionary with 'name', 'url', 'color' and
523 'fullname' keys.
524 Parameters
526 • folder_depth -- Number of levels to search, int.
528 By default None, which will search all levels. 0
529 limits to toplevel.
530 • folder_depth_per_request -- Number of levels to
532 fetch at once, int. By default 10, which is usu‐
533 ally enough to fetch all jobs using a single re‐
534 quest and still easily fits into an HTTP re‐
535 quest.
536 Returns
538 list of jobs, [ { str: str} ]
539 NOTE:
541 On instances with many folders it would not be effi‐
542 cient to fetch each folder separately, hence
543 folder_depth_per_request levels are fetched at once
544 using the tree query parameter:
545 ?tree=jobs[url,color,name,jobs[...,jobs[...,jobs[...,jobs]]]]
547 If there are more folder levels than the query asks
549 for, Jenkins returns empty [1] objects at the deepest
550 level:
551 {"name": "folder", "url": "...", "jobs": [{}, {}, ...]}
553 This makes it possible to detect when additional re‐
555 quests are needed.
556 [1] Actually recent Jenkins includes a _class field
558 everywhere, but it's missing the requested
559 fields.
560 copy_job(from_name, to_name)
562 Copy a Jenkins job.
563 Will raise an exception whenever the source and destina‐
565 tion folder for this jobs won't be the same.
566 Parameters
568 • from_name -- Name of Jenkins job to copy from,
570 str
571 • to_name -- Name of Jenkins job to copy to, str
573 Throws JenkinsException whenever the source and destina‐
575 tion folder are not the same
576 rename_job(from_name, to_name)
578 Rename an existing Jenkins job
579 Will raise an exception whenever the source and destina‐
581 tion folder for this jobs won't be the same.
582 Parameters
584 • from_name -- Name of Jenkins job to rename, str
586 • to_name -- New Jenkins job name, str
588 Throws JenkinsException whenever the source and destina‐
590 tion folder are not the same
591 delete_job(name)
593 Delete Jenkins job permanently.
594 Parameters
596 name -- Name of Jenkins job, str
597 enable_job(name)
599 Enable Jenkins job.
600 Parameters
602 name -- Name of Jenkins job, str
603 disable_job(name)
605 Disable Jenkins job.
606 To re-enable, call Jenkins.enable_job().
608 Parameters
610 name -- Name of Jenkins job, str
611 set_next_build_number(name, number)
613 Set a job's next build number.
614 The current next build number is contained within the job
616 information retrieved using Jenkins.get_job_info(). If
617 the specified next build number is less than the last
618 build number, Jenkins will ignore the request.
619 Note that the Next Build Number Plugin must be installed
621 to enable this functionality.
622 Parameters
624 • name -- Name of Jenkins job, str
626 • number -- Next build number to set, int
628 Example:
630 >>> next_bn = server.get_job_info('job_name')['nextBuildNumber']
632 >>> server.set_next_build_number('job_name', next_bn + 50)
633 job_exists(name)
635 Check whether a job exists
636 Parameters
638 name -- Name of Jenkins job, str
639 Returns
641 True if Jenkins job exists
642 jobs_count()
644 Get the number of jobs on the Jenkins server
645 Returns
647 Total number of jobs, int
648 assert_job_exists(name, exception_message='job[%s] does not ex‐
650 ist')
651 Raise an exception if a job does not exist
652 Parameters
654 • name -- Name of Jenkins job, str
656 • exception_message -- Message to use for the ex‐
658 ception. Formatted with name
659 Throws JenkinsException whenever the job does not exist
661 create_folder(folder_name, ignore_failures=False)
663 Create a new Jenkins folder
664 Parameters
666 • folder_name -- Name of Jenkins Folder, str
668 • ignore_failures -- if True, don't raise if it
670 was not possible to create the folder, bool
671 upsert_job(name, config_xml)
673 Create a new Jenkins job or reconfigures it if it exists
674 Parameters
676 • name -- Name of Jenkins job, str
678 • config_xml -- config file text, str
680 check_jenkinsfile_syntax(jenkinsfile)
682 Checks if a Pipeline Jenkinsfile has a valid syntax
683 Parameters
685 jenkinsfile -- Jenkinsfile text, str
686 Returns
688 List of errors in the Jenkinsfile. Empty list if
689 no errors.
690 create_job(name, config_xml)
692 Create a new Jenkins job
693 Parameters
695 • name -- Name of Jenkins job, str
697 • config_xml -- config file text, str
699 get_job_config(name)
701 Get configuration of existing Jenkins job.
702 Parameters
704 name -- Name of Jenkins job, str
705 Returns
707 job configuration (XML format)
708 reconfig_job(name, config_xml)
710 Change configuration of existing Jenkins job.
711 To create a new job, see Jenkins.create_job().
713 Parameters
715 • name -- Name of Jenkins job, str
717 • config_xml -- New XML configuration, str
719 build_job_url(name, parameters=None, token=None)
721 Get URL to trigger build job.
722 Authenticated setups may require configuring a token on
724 the server side.
725 Use list of two membered tuples to supply parameters with
727 multi select options.
728 Parameters
730 • name -- Name of Jenkins job, str
732 • parameters -- parameters for job, or None., dict
734 or list of two membered tuples
735 • token -- (optional) token for building job, str
737 Returns
739 URL for building job
740 build_job(name, parameters=None, token=None)
742 Trigger build job.
743 This method returns a queue item number that you can pass
745 to Jenkins.get_queue_item(). Note that this queue number
746 is only valid for about five minutes after the job com‐
747 pletes, so you should get/poll the queue information as
748 soon as possible to determine the job's URL.
749 Parameters
751 • name -- name of job
753 • parameters -- parameters for job, or None, dict
755 • token -- Jenkins API token
757 Returns
759 int queue item
760 run_script(script, node=None)
762 Execute a groovy script on the jenkins master or on a
763 node if specified..
764 Parameters
766 • script -- The groovy script, string
768 • node -- Node to run the script on, defaults to
770 None (master).
771 Returns
773 The result of the script run.
774 Example::
776 >>> info = server.run_script("println(Jenkins.instance.pluginManager.plugins)")
778 >>> print(info)
779 u'[Plugin:windows-slaves, Plugin:ssh-slaves, Plugin:translation,
780 Plugin:cvs, Plugin:nodelabelparameter, Plugin:external-monitor-job,
781 Plugin:mailer, Plugin:jquery, Plugin:antisamy-markup-formatter,
782 Plugin:maven-plugin, Plugin:pam-auth]'
783 install_plugin(name, include_dependencies=True)
785 Install a plugin and its dependencies from the Jenkins
786 public repository at
787 http://repo.jenkins-ci.org/repo/org/jenkins-ci/plugins
788 Parameters
790 • name -- The plugin short name, string
792 • include_dependencies -- Install the plugin's de‐
794 pendencies, bool
795 Returns
797 Whether a Jenkins restart is required, bool
798 Example::
800 >>> info = server.install_plugin("jabber")
802 >>> print(info)
803 True
804 stop_build(name, number)
806 Stop a running Jenkins build.
807 Parameters
809 • name -- Name of Jenkins job, str
811 • number -- Jenkins build number for the job, int
813 delete_build(name, number)
815 Delete a Jenkins build.
816 Parameters
818 • name -- Name of Jenkins job, str
820 • number -- Jenkins build number for the job, int
822 wipeout_job_workspace(name)
824 Wipe out workspace for given Jenkins job.
825 Parameters
827 name -- Name of Jenkins job, str
828 get_running_builds()
830 Return list of running builds.
831 Each build is a dict with keys 'name', 'number', 'url',
833 'node', and 'executor'.
834 Returns
836 List of builds, [ { str: str, str: int, str:str,
837 str: str, str: int} ]
838 Example::
840 >>> builds = server.get_running_builds()
842 >>> print(builds)
843 [{'node': 'foo-slave', 'url': 'https://localhost/job/test/15/',
844 'executor': 0, 'name': 'test', 'number': 15}]
845 get_nodes(depth=0)
847 Get a list of nodes connected to the Master
848 Each node is a dict with keys 'name' and 'offline'
850 Returns
852 List of nodes, [ { str: str, str: bool} ]
853 get_node_info(name, depth=0)
855 Get node information dictionary
856 Parameters
858 • name -- Node name, str
860 • depth -- JSON depth, int
862 Returns
864 Dictionary of node info, dict
865 node_exists(name)
867 Check whether a node exists
868 Parameters
870 name -- Name of Jenkins node, str
871 Returns
873 True if Jenkins node exists
874 assert_node_exists(name, exception_message='node[%s] does not
876 exist')
877 Raise an exception if a node does not exist
878 Parameters
880 • name -- Name of Jenkins node, str
882 • exception_message -- Message to use for the ex‐
884 ception. Formatted with name
885 Throws JenkinsException whenever the node does not exist
887 delete_node(name)
889 Delete Jenkins node permanently.
890 Parameters
892 name -- Name of Jenkins node, str
893 disable_node(name, msg='')
895 Disable a node
896 Parameters
898 • name -- Jenkins node name, str
900 • msg -- Offline message, str
902 enable_node(name)
904 Enable a node
905 Parameters
907 name -- Jenkins node name, str
908 create_node(name, numExecutors=2, nodeDescription=None, re‐
910 moteFS='/var/lib/jenkins', labels=None, exclusive=False,
911 launcher='hudson.slaves.CommandLauncher', launcher_params={})
912 Create a node
913 Parameters
915 • name -- name of node to create, str
917 • numExecutors -- number of executors for node,
919 int
920 • nodeDescription -- Description of node, str
922 • remoteFS -- Remote filesystem location to use,
924 str
925 • labels -- Labels to associate with node, str
927 • exclusive -- Use this node for tied jobs only,
929 bool
930 • launcher -- The launch method for the slave,
932 jenkins.LAUNCHER_COMMAND, jenk‐
933 ins.LAUNCHER_SSH, jenkins.LAUNCHER_JNLP, jenk‐
934 ins.LAUNCHER_WINDOWS_SERVICE
935 • launcher_params -- Additional parameters for the
937 launcher, dict
938 get_node_config(name)
940 Get the configuration for a node.
941 Parameters
943 name -- Jenkins node name, str
944 reconfig_node(name, config_xml)
946 Change the configuration for an existing node.
947 Parameters
949 • name -- Jenkins node name, str
951 • config_xml -- New XML configuration, str
953 get_build_console_output(name, number)
955 Get build console text.
956 Parameters
958 • name -- Job name, str
960 • number -- Build number, int
962 Returns
964 Build console output, str
965 get_view_name(name)
967 Return the name of a view using the API.
968 That is roughly an identity method which can be used to
970 quickly verify a view exists or is accessible without
971 causing too much stress on the server side.
972 Parameters
974 name -- View name, str
975 Returns
977 Name of view or None
978 assert_view_exists(name, exception_message='view[%s] does not
980 exist')
981 Raise an exception if a view does not exist
982 Parameters
984 • name -- Name of Jenkins view, str
986 • exception_message -- Message to use for the ex‐
988 ception. Formatted with name
989 Throws JenkinsException whenever the view does not exist
991 view_exists(name)
993 Check whether a view exists
994 Parameters
996 name -- Name of Jenkins view, str
997 Returns
999 True if Jenkins view exists
1000 get_views()
1002 Get list of views running.
1003 Each view is a dictionary with 'name' and 'url' keys.
1005 Returns
1007 list of views, [ { str: str} ]
1008 delete_view(name)
1010 Delete Jenkins view permanently.
1011 Parameters
1013 name -- Name of Jenkins view, str
1014 create_view(name, config_xml)
1016 Create a new Jenkins view
1017 Parameters
1019 • name -- Name of Jenkins view, str
1021 • config_xml -- config file text, str
1023 reconfig_view(name, config_xml)
1025 Change configuration of existing Jenkins view.
1026 To create a new view, see Jenkins.create_view().
1028 Parameters
1030 • name -- Name of Jenkins view, str
1032 • config_xml -- New XML configuration, str
1034 get_view_config(name)
1036 Get configuration of existing Jenkins view.
1037 Parameters
1039 name -- Name of Jenkins view, str
1040 Returns
1042 view configuration (XML format)
1043 get_promotion_name(name, job_name)
1045 Return the name of a promotion using the API.
1046 That is roughly an identity method which can be used to
1048 quickly verify a promotion exists for a job or is acces‐
1049 sible without causing too much stress on the server side.
1050 Parameters
1052 • name -- Promotion name, str
1054 • job_name -- Job name, str
1056 Returns
1058 Name of promotion or None
1059 assert_promotion_exists(name, job_name, exception_message='pro‐
1061 motion[%s] does not exist for job[%s]')
1062 Raise an exception if a job lacks a promotion
1063 Parameters
1065 • name -- Name of Jenkins promotion, str
1067 • job_name -- Job name, str
1069 • exception_message -- Message to use for the ex‐
1071 ception. Formatted with name and job_name
1072 Throws JenkinsException whenever the promotion does not
1074 exist on a job
1075 promotion_exists(name, job_name)
1077 Check whether a job has a certain promotion
1078 Parameters
1080 • name -- Name of Jenkins promotion, str
1082 • job_name -- Job name, str
1084 Returns
1086 True if Jenkins promotion exists
1087 get_promotions_info(job_name, depth=0)
1089 Get promotion information dictionary of a job
1090 Parameters
1092 • job_name -- job_name, str
1094 • depth -- JSON depth, int
1096 Returns
1098 Dictionary of promotion info, dict
1099 get_promotions(job_name)
1101 Get list of promotions running.
1102 Each promotion is a dictionary with 'name' and 'url'
1104 keys.
1105 Parameters
1107 job_name -- Job name, str
1108 Returns
1110 list of promotions, [ { str: str} ]
1111 delete_promotion(name, job_name)
1113 Delete Jenkins promotion permanently.
1114 Parameters
1116 • name -- Name of Jenkins promotion, str
1118 • job_name -- Job name, str
1120 create_promotion(name, job_name, config_xml)
1122 Create a new Jenkins promotion
1123 Parameters
1125 • name -- Name of Jenkins promotion, str
1127 • job_name -- Job name, str
1129 • config_xml -- config file text, str
1131 reconfig_promotion(name, job_name, config_xml)
1133 Change configuration of existing Jenkins promotion.
1134 To create a new promotion, see
1136 Jenkins.create_promotion().
1137 Parameters
1139 • name -- Name of Jenkins promotion, str
1141 • job_name -- Job name, str
1143 • config_xml -- New XML configuration, str
1145 get_promotion_config(name, job_name)
1147 Get configuration of existing Jenkins promotion.
1148 Parameters
1150 • name -- Name of Jenkins promotion, str
1152 • job_name -- Job name, str
1154 Returns
1156 promotion configuration (XML format)
1157 assert_folder(name, exception_message='job[%s] is not a folder')
1159 Raise an exception if job is not Cloudbees Folder
1160 Parameters
1162 • name -- Name of job, str
1164 • exception_message -- Message to use for the ex‐
1166 ception.
1167 Throws JenkinsException whenever the job is not Cloudbees
1169 Folder
1170 is_folder(name)
1172 Check whether a job is Cloudbees Folder
1173 Parameters
1175 name -- Job name, str
1176 Returns
1178 True if job is folder, False otherwise
1179 assert_credential_exists(name, folder_name, domain_name='_', ex‐
1181 ception_message='credential[%s] does not exist in the domain[%s]
1182 of [%s]')
1183 Raise an exception if credential does not exist in domain
1184 of folder
1185 Parameters
1187 • name -- Name of credential, str
1189 • folder_name -- Folder name, str
1191 • domain_name -- Domain name, default is '_', str
1193 • exception_message -- Message to use for the ex‐
1195 ception. Formatted with name, domain_name, and
1196 folder_name
1197 Throws JenkinsException whenever the credentail does not
1199 exist in domain of folder
1200 credential_exists(name, folder_name, domain_name='_')
1202 Check whether a credentail exists in domain of folder
1203 Parameters
1205 • name -- Name of credentail, str
1207 • folder_name -- Folder name, str
1209 • domain_name -- Domain name, default is '_', str
1211 Returns
1213 True if credentail exists, False otherwise
1214 get_credential_info(name, folder_name, domain_name='_')
1216 Get credential information dictionary in domain of folder
1217 Parameters
1219 • name -- Name of credentail, str
1221 • folder_name -- folder_name, str
1223 • domain_name -- Domain name, default is '_', str
1225 Returns
1227 Dictionary of credential info, dict
1228 get_credential_config(name, folder_name, domain_name='_')
1230 Get configuration of credential in domain of folder.
1231 Parameters
1233 • name -- Name of credentail, str
1235 • folder_name -- Folder name, str
1237 • domain_name -- Domain name, default is '_', str
1239 Returns
1241 Credential configuration (XML format)
1242 create_credential(folder_name, config_xml, domain_name='_')
1244 Create credentail in domain of folder
1245 Parameters
1247 • folder_name -- Folder name, str
1249 • config_xml -- New XML configuration, str
1251 • domain_name -- Domain name, default is '_', str
1253 delete_credential(name, folder_name, domain_name='_')
1255 Delete credential from domain of folder
1256 Parameters
1258 • name -- Name of credentail, str
1260 • folder_name -- Folder name, str
1262 • domain_name -- Domain name, default is '_', str
1264 reconfig_credential(folder_name, config_xml, domain_name='_')
1266 Reconfig credential with new config in domain of folder
1267 Parameters
1269 • folder_name -- Folder name, str
1271 • config_xml -- New XML configuration, str
1273 • domain_name -- Domain name, default is '_', str
1275 list_credentials(folder_name, domain_name='_')
1277 List credentials in domain of folder
1278 Parameters
1280 • folder_name -- Folder name, str
1282 • domain_name -- Domain name, default is '_', str
1284 Returns
1286 Credentials list, list
1287 quiet_down()
1289 Prepare Jenkins for shutdown.
1290 No new builds will be started allowing running builds to
1292 complete prior to shutdown of the server.
1293 wait_for_normal_op(timeout)
1295 Wait for jenkins to enter normal operation mode.
1296 Parameters
1298 timeout -- number of seconds to wait, int Note
1299 this is not the same as the connection timeout set
1300 via __init__ as that controls the socket timeout.
1301 Instead this is how long to wait until the status
1302 returned.
1303 Returns
1305 True if Jenkins became ready in time, False other‐
1306 wise.
1307 Setting timeout to be less than the configured connection
1309 timeout may result in this waiting for at least the con‐
1310 nection timeout length of time before returning. It is
1311 recommended that the timeout here should be at least as
1312 long as any set connection timeout.
1313 class jenkins.plugins.Plugin(*args, **kwargs)
1315 Dictionary object containing plugin metadata.
1316 Populates dictionary using json object input.
1318 accepts same arguments as python dict class.
1320 class jenkins.plugins.PluginVersion(version)
1322 Class providing comparison capabilities for plugin versions.
1323 Parse plugin version and store it for comparison.
1325
1327 The python-jenkins library allows management of a Jenkins server
1328 through the Jenkins REST endpoints. Below are examples to get you
1329 started using the library. If you need further help take a look at the
1330 API reference docs for more details.
1331 Example 1: Get version of Jenkins
1333 This is an example showing how to connect to a Jenkins instance and re‐
1334 trieve the Jenkins server version.
1335 import jenkins
1337 server = jenkins.Jenkins('http://localhost:8080', username='myuser', password='mypassword')
1339 user = server.get_whoami()
1340 version = server.get_version()
1341 print('Hello %s from Jenkins %s' % (user['fullName'], version))
1342 The above code prints the fullName attribute of the user and the ver‐
1344 sion of the Jenkins master running on 'localhost:8080'. For example, it
1345 may print "Hello John from Jenkins 2.0".
1346 From Jenkins version 1.426 onward you can specify an API token instead
1348 of your real password while authenticating the user against the Jenkins
1349 instance. Refer to the Jenkins Authentication wiki for details about
1350 how you can generate an API token. Once you have an API token you can
1351 pass the API token instead of a real password while creating a Jenkins
1352 instance.
1353 Example 2: Logging into Jenkins using kerberos
1355 Kerberos support is only enabled if you have "kerberos" python package
1356 installed. You can install the "kerberos" package from PyPI using the
1357 obvious pip command.
1358 pip install kerberos
1360 NOTE:
1362 This might require python header files as well as kerberos header
1363 files.
1364 If you have "kerberos" python package installed, python-jenkins tries
1366 to authenticate using kerberos automatically when the Jenkins server
1367 replies "401 Unauthorized" and indicates it supports kerberos. That
1368 is, kerberos authentication should work automagically. For a quick
1369 test, just try the following.
1370 import jenkins
1372 server = jenkins.Jenkins('http://localhost:8080')
1374 print server.jobs_count()
1375 NOTE:
1377 Jenkins as such does not support kerberos, it needs to be supported
1378 by the Servlet container or a reverse proxy sitting in front of
1379 Jenkins.
1380 Example 3: Working with Jenkins Jobs
1382 This is an example showing how to create, configure and delete Jenkins
1383 jobs.
1384 server.create_job('empty', jenkins.EMPTY_CONFIG_XML)
1386 jobs = server.get_jobs()
1387 print jobs
1388 my_job = server.get_job_config('cool-job')
1389 print(my_job) # prints XML configuration
1390 server.build_job('empty')
1391 server.disable_job('empty')
1392 server.copy_job('empty', 'empty_copy')
1393 server.enable_job('empty_copy')
1394 server.reconfig_job('empty_copy', jenkins.RECONFIG_XML)
1395 server.delete_job('empty')
1397 server.delete_job('empty_copy')
1398 # build a parameterized job
1400 # requires creating and configuring the api-test job to accept 'param1' & 'param2'
1401 server.build_job('api-test', {'param1': 'test value 1', 'param2': 'test value 2'})
1402 last_build_number = server.get_job_info('api-test')['lastCompletedBuild']['number']
1403 build_info = server.get_build_info('api-test', last_build_number)
1404 print build_info
1405 # get all jobs from the specific view
1407 jobs = server.get_jobs(view_name='View Name')
1408 print jobs
1409 Example 4: Working with Jenkins Views
1411 This is an example showing how to create, configure and delete Jenkins
1412 views.
1413 server.create_view('EMPTY', jenkins.EMPTY_VIEW_CONFIG_XML)
1415 view_config = server.get_view_config('EMPTY')
1416 views = server.get_views()
1417 server.delete_view('EMPTY')
1418 print views
1419 Example 5: Working with Jenkins Plugins
1421 This is an example showing how to retrieve Jenkins plugins information.
1422 plugins = server.get_plugins_info()
1424 print plugins
1425 The above example will print a dictionary containing all the plugins
1427 that are installed on the Jenkins server. An example of what you can
1428 expect from the get_plugins_info() method is documented in the API ref‐
1429 erence doc.
1430 Example 6: Working with Jenkins Nodes
1432 This is an example showing how to add, configure, enable and delete
1433 Jenkins nodes.
1434 server.create_node('slave1')
1436 nodes = get_nodes()
1437 print nodes
1438 node_config = server.get_node_info('slave1')
1439 print node_config
1440 server.disable_node('slave1')
1441 server.enable_node('slave1')
1442 # create node with parameters
1444 params = {
1445 'port': '22',
1446 'username': 'juser',
1447 'credentialsId': '10f3a3c8-be35-327e-b60b-a3e5edb0e45f',
1448 'host': 'my.jenkins.slave1'
1449 }
1450 server.create_node(
1451 'slave1',
1452 nodeDescription='my test slave',
1453 remoteFS='/home/juser',
1454 labels='precise',
1455 exclusive=True,
1456 launcher=jenkins.LAUNCHER_SSH,
1457 launcher_params=params)
1458 Example 7: Working with Jenkins Build Queue
1460 This is an example showing how to retrieve information on the Jenkins
1461 queue.
1462 server.build_job('foo')
1464 queue_info = server.get_queue_info()
1465 id = queue_info[0].get('id')
1466 server.cancel_queue(id)
1467 Example 8: Working with Jenkins Cloudbees Folders
1469 Requires the Cloudbees Folders Plugin for Jenkins.
1470 This is an example showing how to create, configure and delete Jenkins
1472 folders.
1473 server.create_job('folder', jenkins.EMPTY_FOLDER_XML)
1475 server.create_job('folder/empty', jenkins.EMPTY_FOLDER_XML)
1476 server.copy_job('folder/empty', 'folder/empty_copy')
1477 server.delete_job('folder/empty_copy')
1478 server.delete_job('folder')
1479 Example 9: Updating Next Build Number
1481 Requires the Next Build Number Plugin for Jenkins.
1482 This is an example showing how to update the next build number for a
1484 Jenkins job.
1485 next_bn = server.get_job_info('job_name')['nextBuildNumber']
1487 server.set_next_build_number('job_name', next_bn + 50)
1488 Example 9: Working with Build Promotions
1490 Requires the Promoted Builds Plugin for Jenkins.
1491 This is an example showing how to create, configure and delete a promo‐
1493 tion process for an existing job.
1494 The job in this example is named prom_job and it needs to have this
1496 config xml snippet before creating the promotion:
1497 <properties>
1499 <hudson.plugins.promoted__builds.JobPropertyImpl>
1500 <activeProcessNames>
1501 <string>prom_name</string>
1502 </activeProcessNames>
1503 </hudson.plugins.promoted__builds.JobPropertyImpl>
1504 </properties>
1505 where prom_name is the name of the promotion that will get added to the
1507 job.
1508 server.create_promotion('prom_name', 'prom_job', jenkins.EMPTY_PROMO_CONFIG_XML)
1510 server.promotion_exists('prom_name', 'prom_job')
1511 print server.get_promotions('prom_job')
1512 server.reconfig_promotion('prom_name', 'prom_job', jenkins.PROMO_RECONFIG_XML)
1514 print server.get_promotion_config('prom_name', 'prom_job')
1515 server.delete_promotion('prom_name', 'prom_job')
1517 Example 10: Waiting for Jenkins to be ready
1519 It is possible to ask the API to wait for Jenkins to be ready with a
1520 given timeout. This can be used to aid launching of Jenkins and then
1521 waiting for the REST API to be responsive before continuing with subse‐
1522 quent configuration.
1523 # timeout here is the socket connection timeout, for each connection
1525 # attempt it will wait at most 5 seconds before assuming there is
1526 # nothing listening. Useful where firewalls may black hole connections.
1527 server = jenkins.Jenkins('http://localhost:8080', timeout=5)
1528 # wait for at least 30 seconds for Jenkins to be ready
1530 if server.wait_for_normal_op(30):
1531 # actions once running
1532 ...
1533 else:
1534 print("Jenkins failed to be ready in sufficient time")
1535 exit 2
1536 Note that the timeout arg to jenkins.Jenkins() is the socket connection
1538 timeout. If you set this to be more than the timeout value passed to
1539 wait_for_normal_op(), then in cases where the underlying connection is
1540 not rejected (firewall black-hole, or slow connection) then
1541 wait_for_normal_op() may wait at least the connection timeout, or a
1542 multiple of it where multiple connection attempts are made. A connec‐
1543 tion timeout of 5 seconds and a wait timeout of 8 will result in poten‐
1544 tially waiting 10 seconds if both connections attempts do not get re‐
1545 sponses.
1546
1548 The module is known to pip and Debian-based distributions as
1549 python-jenkins.
1550 pip:
1552 pip install python-jenkins
1554 easy_install:
1556 easy_install python-jenkins
1558 The module has been packaged since Ubuntu Oneiric (11.10):
1560 apt-get install python-jenkins
1562 And on Fedora 19 and later:
1564 yum install python-jenkins
1566 For development:
1568 python setup.py develop
1570 Documentation
1572 Documentation is included in the doc folder. To generate docs locally
1573 execute the command:
1574 tox -e docs
1576 The generated documentation is then available under doc/build/html/in‐
1578 dex.html.
1579 Unit Tests
1581 Unit tests have been included and are in the tests folder. We recently
1582 started including unit tests as examples in our documentation so to
1583 keep the examples up to date it is very important that we include unit
1584 tests for every module. To run the unit tests, execute the command:
1585 tox -e py27
1587 • Note: View tox.ini to run tests on other versions of Python.
1589 Due to how the tests are split up into a dedicated class per API
1591 method, it is possible to execute tests against a single API at a time.
1592 To execute the tests for the Jenkins.get_version() API execute the com‐
1593 mand:
1594 tox -e py27 -- tests.test_version.JenkinsVersionTest
1596 For further details on how to list tests available and different ways
1598 to execute them, see https://wiki.openstack.org/wiki/Testr.
1599 Test Coverage
1601 To measure test coverage, execute the command:
1602 tox -e cover
1604 • Index
1606 • Module Index
1608 • Search Page
1610
1612 Ken Conley, James Page, Tully Foote, Matthew Gertner
1613
1615 2022, Willow Garage
16161.7.0 Jul 22, 2022 PYTHONJENKINS(1)