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://opendev.org/jjb/python-jenkins
72 Cloning:
74 • git clone https://opendev.org/jjb/python-jenkins
76 Patches are submitted via Gerrit at:
78 • https://review.opendev.org/#/q/project:jjb/python-jenkins
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 • https://docs.opendev.org/opendev/infra-manual/latest/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 The python-jenkins library allows management of a Jenkins server
110 through the Jenkins REST endpoints. Below are examples to get you
111 started using the library. If you need further help take a look at the
112 API reference docs for more details.
113 Example 1: Get version of Jenkins
115 This is an example showing how to connect to a Jenkins instance and re‐
116 trieve the Jenkins server version.
117 import jenkins
119 server = jenkins.Jenkins('http://localhost:8080', username='myuser', password='mypassword')
121 user = server.get_whoami()
122 version = server.get_version()
123 print('Hello %s from Jenkins %s' % (user['fullName'], version))
124 The above code prints the fullName attribute of the user and the ver‐
126 sion of the Jenkins master running on 'localhost:8080'. For example, it
127 may print "Hello John from Jenkins 2.0".
128 From Jenkins version 1.426 onward you can specify an API token instead
130 of your real password while authenticating the user against the Jenkins
131 instance. Refer to the Jenkins Authentication wiki for details about
132 how you can generate an API token. Once you have an API token you can
133 pass the API token instead of a real password while creating a Jenkins
134 instance.
135 Example 2: Logging into Jenkins using kerberos
137 Kerberos support is only enabled if you have "kerberos" python package
138 installed. You can install the "kerberos" package from PyPI using the
139 obvious pip command.
140 pip install kerberos
142 NOTE:
144 This might require python header files as well as kerberos header
145 files.
146 If you have "kerberos" python package installed, python-jenkins tries
148 to authenticate using kerberos automatically when the Jenkins server
149 replies "401 Unauthorized" and indicates it supports kerberos. That
150 is, kerberos authentication should work automagically. For a quick
151 test, just try the following.
152 import jenkins
154 server = jenkins.Jenkins('http://localhost:8080')
156 print server.jobs_count()
157 NOTE:
159 Jenkins as such does not support kerberos, it needs to be supported
160 by the Servlet container or a reverse proxy sitting in front of
161 Jenkins.
162 Example 3: Working with Jenkins Jobs
164 This is an example showing how to create, configure and delete Jenkins
165 jobs.
166 server.create_job('empty', jenkins.EMPTY_CONFIG_XML)
168 jobs = server.get_jobs()
169 print jobs
170 my_job = server.get_job_config('cool-job')
171 print(my_job) # prints XML configuration
172 server.build_job('empty')
173 server.disable_job('empty')
174 server.copy_job('empty', 'empty_copy')
175 server.enable_job('empty_copy')
176 server.reconfig_job('empty_copy', jenkins.RECONFIG_XML)
177 server.delete_job('empty')
179 server.delete_job('empty_copy')
180 # build a parameterized job
182 # requires creating and configuring the api-test job to accept 'param1' & 'param2'
183 server.build_job('api-test', {'param1': 'test value 1', 'param2': 'test value 2'})
184 last_build_number = server.get_job_info('api-test')['lastCompletedBuild']['number']
185 build_info = server.get_build_info('api-test', last_build_number)
186 print build_info
187 # get all jobs from the specific view
189 jobs = server.get_jobs(view_name='View Name')
190 print jobs
191 Example 4: Working with Jenkins Views
193 This is an example showing how to create, configure and delete Jenkins
194 views.
195 server.create_view('EMPTY', jenkins.EMPTY_VIEW_CONFIG_XML)
197 view_config = server.get_view_config('EMPTY')
198 views = server.get_views()
199 server.delete_view('EMPTY')
200 print views
201 Example 5: Working with Jenkins Plugins
203 This is an example showing how to retrieve Jenkins plugins information.
204 plugins = server.get_plugins_info()
206 print plugins
207 The above example will print a dictionary containing all the plugins
209 that are installed on the Jenkins server. An example of what you can
210 expect from the get_plugins_info() method is documented in the API ref‐
211 erence doc.
212 Example 6: Working with Jenkins Nodes
214 This is an example showing how to add, configure, enable and delete
215 Jenkins nodes.
216 server.create_node('slave1')
218 nodes = get_nodes()
219 print nodes
220 node_config = server.get_node_info('slave1')
221 print node_config
222 server.disable_node('slave1')
223 server.enable_node('slave1')
224 # create node with parameters
226 params = {
227 'port': '22',
228 'username': 'juser',
229 'credentialsId': '10f3a3c8-be35-327e-b60b-a3e5edb0e45f',
230 'host': 'my.jenkins.slave1'
231 }
232 server.create_node(
233 'slave1',
234 nodeDescription='my test slave',
235 remoteFS='/home/juser',
236 labels='precise',
237 exclusive=True,
238 launcher=jenkins.LAUNCHER_SSH,
239 launcher_params=params)
240 Example 7: Working with Jenkins Build Queue
242 This is an example showing how to retrieve information on the Jenkins
243 queue.
244 server.build_job('foo')
246 queue_info = server.get_queue_info()
247 id = queue_info[0].get('id')
248 server.cancel_queue(id)
249 Example 8: Working with Jenkins Cloudbees Folders
251 Requires the Cloudbees Folders Plugin for Jenkins.
252 This is an example showing how to create, configure and delete Jenkins
254 folders.
255 server.create_job('folder', jenkins.EMPTY_FOLDER_XML)
257 server.create_job('folder/empty', jenkins.EMPTY_FOLDER_XML)
258 server.copy_job('folder/empty', 'folder/empty_copy')
259 server.delete_job('folder/empty_copy')
260 server.delete_job('folder')
261 Example 9: Updating Next Build Number
263 Requires the Next Build Number Plugin for Jenkins.
264 This is an example showing how to update the next build number for a
266 Jenkins job.
267 next_bn = server.get_job_info('job_name')['nextBuildNumber']
269 server.set_next_build_number('job_name', next_bn + 50)
270 Example 9: Working with Build Promotions
272 Requires the Promoted Builds Plugin for Jenkins.
273 This is an example showing how to create, configure and delete a promo‐
275 tion process for an existing job.
276 The job in this example is named prom_job and it needs to have this
278 config xml snippet before creating the promotion:
279 <properties>
281 <hudson.plugins.promoted__builds.JobPropertyImpl>
282 <activeProcessNames>
283 <string>prom_name</string>
284 </activeProcessNames>
285 </hudson.plugins.promoted__builds.JobPropertyImpl>
286 </properties>
287 where prom_name is the name of the promotion that will get added to the
289 job.
290 server.create_promotion('prom_name', 'prom_job', jenkins.EMPTY_PROMO_CONFIG_XML)
292 server.promotion_exists('prom_name', 'prom_job')
293 print server.get_promotions('prom_job')
294 server.reconfig_promotion('prom_name', 'prom_job', jenkins.PROMO_RECONFIG_XML)
296 print server.get_promotion_config('prom_name', 'prom_job')
297 server.delete_promotion('prom_name', 'prom_job')
299 Example 10: Waiting for Jenkins to be ready
301 It is possible to ask the API to wait for Jenkins to be ready with a
302 given timeout. This can be used to aid launching of Jenkins and then
303 waiting for the REST API to be responsive before continuing with subse‐
304 quent configuration.
305 # timeout here is the socket connection timeout, for each connection
307 # attempt it will wait at most 5 seconds before assuming there is
308 # nothing listening. Useful where firewalls may black hole connections.
309 server = jenkins.Jenkins('http://localhost:8080', timeout=5)
310 # wait for at least 30 seconds for Jenkins to be ready
312 if server.wait_for_normal_op(30):
313 # actions once running
314 ...
315 else:
316 print("Jenkins failed to be ready in sufficient time")
317 exit 2
318 Note that the timeout arg to jenkins.Jenkins() is the socket connection
320 timeout. If you set this to be more than the timeout value passed to
321 wait_for_normal_op(), then in cases where the underlying connection is
322 not rejected (firewall black-hole, or slow connection) then
323 wait_for_normal_op() may wait at least the connection timeout, or a
324 multiple of it where multiple connection attempts are made. A connec‐
325 tion timeout of 5 seconds and a wait timeout of 8 will result in poten‐
326 tially waiting 10 seconds if both connections attempts do not get re‐
327 sponses.
328
330 The module is known to pip and Debian-based distributions as
331 python-jenkins.
332 pip:
334 pip install python-jenkins
336 easy_install:
338 easy_install python-jenkins
340 The module has been packaged since Ubuntu Oneiric (11.10):
342 apt-get install python-jenkins
344 And on Fedora 19 and later:
346 yum install python-jenkins
348 For development:
350 python setup.py develop
352 Documentation
354 Documentation is included in the doc folder. To generate docs locally
355 execute the command:
356 tox -e docs
358 The generated documentation is then available under doc/build/html/in‐
360 dex.html.
361 Unit Tests
363 Unit tests have been included and are in the tests folder. We recently
364 started including unit tests as examples in our documentation so to
365 keep the examples up to date it is very important that we include unit
366 tests for every module. To run the unit tests, execute the command:
367 tox -e py27
369 • Note: View tox.ini to run tests on other versions of Python.
371 Due to how the tests are split up into a dedicated class per API
373 method, it is possible to execute tests against a single API at a time.
374 To execute the tests for the Jenkins.get_version() API execute the com‐
375 mand:
376 tox -e py27 -- tests.test_version.JenkinsVersionTest
378 For further details on how to list tests available and different ways
380 to execute them, see https://wiki.openstack.org/wiki/Testr.
381 Test Coverage
383 To measure test coverage, execute the command:
384 tox -e cover
386 • Index
388 • Module Index
390 • Search Page
392
394 Ken Conley, James Page, Tully Foote, Matthew Gertner
395
397 2023, Willow Garage
3981.8.0 Jul 22, 2023 PYTHONJENKINS(1)