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 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 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 doc.
211 Example 6: Working with Jenkins Nodes
213 This is an example showing how to add, configure, enable and delete
214 Jenkins nodes.
215 server.create_node('slave1')
217 nodes = get_nodes()
218 print nodes
219 node_config = server.get_node_info('slave1')
220 print node_config
221 server.disable_node('slave1')
222 server.enable_node('slave1')
223 # create node with parameters
225 params = {
226 'port': '22',
227 'username': 'juser',
228 'credentialsId': '10f3a3c8-be35-327e-b60b-a3e5edb0e45f',
229 'host': 'my.jenkins.slave1'
230 }
231 server.create_node(
232 'slave1',
233 nodeDescription='my test slave',
234 remoteFS='/home/juser',
235 labels='precise',
236 exclusive=True,
237 launcher=jenkins.LAUNCHER_SSH,
238 launcher_params=params)
239 Example 7: Working with Jenkins Build Queue
241 This is an example showing how to retrieve information on the Jenkins
242 queue.
243 server.build_job('foo')
245 queue_info = server.get_queue_info()
246 id = queue_info[0].get('id')
247 server.cancel_queue(id)
248 Example 8: Working with Jenkins Cloudbees Folders
250 Requires the Cloudbees Folders Plugin for Jenkins.
251 This is an example showing how to create, configure and delete Jenkins
253 folders.
254 server.create_job('folder', jenkins.EMPTY_FOLDER_XML)
256 server.create_job('folder/empty', jenkins.EMPTY_FOLDER_XML)
257 server.copy_job('folder/empty', 'folder/empty_copy')
258 server.delete_job('folder/empty_copy')
259 server.delete_job('folder')
260 Example 9: Updating Next Build Number
262 Requires the Next Build Number Plugin for Jenkins.
263 This is an example showing how to update the next build number for a
265 Jenkins job.
266 next_bn = server.get_job_info('job_name')['nextBuildNumber']
268 server.set_next_build_number('job_name', next_bn + 50)
269 Example 9: Working with Build Promotions
271 Requires the Promoted Builds Plugin for Jenkins.
272 This is an example showing how to create, configure and delete a promo‐
274 tion process for an existing job.
275 The job in this example is named prom_job and it needs to have this
277 config xml snippet before creating the promotion:
278 <properties>
280 <hudson.plugins.promoted__builds.JobPropertyImpl>
281 <activeProcessNames>
282 <string>prom_name</string>
283 </activeProcessNames>
284 </hudson.plugins.promoted__builds.JobPropertyImpl>
285 </properties>
286 where prom_name is the name of the promotion that will get added to the
288 job.
289 server.create_promotion('prom_name', 'prom_job', jenkins.EMPTY_PROMO_CONFIG_XML)
291 server.promotion_exists('prom_name', 'prom_job')
292 print server.get_promotions('prom_job')
293 server.reconfig_promotion('prom_name', 'prom_job', jenkins.PROMO_RECONFIG_XML)
295 print server.get_promotion_config('prom_name', 'prom_job')
296 server.delete_promotion('prom_name', 'prom_job')
298 Example 10: Waiting for Jenkins to be ready
300 It is possible to ask the API to wait for Jenkins to be ready with a
301 given timeout. This can be used to aid launching of Jenkins and then
302 waiting for the REST API to be responsive before continuing with subse‐
303 quent configuration.
304 # timeout here is the socket connection timeout, for each connection
306 # attempt it will wait at most 5 seconds before assuming there is
307 # nothing listening. Useful where firewalls may black hole connections.
308 server = jenkins.Jenkins('http://localhost:8080', timeout=5)
309 # wait for at least 30 seconds for Jenkins to be ready
311 if server.wait_for_normal_op(30):
312 # actions once running
313 ...
314 else:
315 print("Jenkins failed to be ready in sufficient time")
316 exit 2
317 Note that the timeout arg to jenkins.Jenkins() is the socket connection
319 timeout. If you set this to be more than the timeout value passed to
320 wait_for_normal_op(), then in cases where the underlying connection is
321 not rejected (firewall black-hole, or slow connection) then
322 wait_for_normal_op() may wait at least the connection timeout, or a
323 multiple of it where multiple connection attempts are made. A connec‐
324 tion timeout of 5 seconds and a wait timeout of 8 will result in poten‐
325 tially waiting 10 seconds if both connections attempts do not get re‐
326 sponses.
327
329 The module is known to pip and Debian-based distributions as
330 python-jenkins.
331 pip:
333 pip install python-jenkins
335 easy_install:
337 easy_install python-jenkins
339 The module has been packaged since Ubuntu Oneiric (11.10):
341 apt-get install python-jenkins
343 And on Fedora 19 and later:
345 yum install python-jenkins
347 For development:
349 python setup.py develop
351 Documentation
353 Documentation is included in the doc folder. To generate docs locally
354 execute the command:
355 tox -e docs
357 The generated documentation is then available under doc/build/html/in‐
359 dex.html.
360 Unit Tests
362 Unit tests have been included and are in the tests folder. We recently
363 started including unit tests as examples in our documentation so to
364 keep the examples up to date it is very important that we include unit
365 tests for every module. To run the unit tests, execute the command:
366 tox -e py27
368 • Note: View tox.ini to run tests on other versions of Python.
370 Due to how the tests are split up into a dedicated class per API
372 method, it is possible to execute tests against a single API at a time.
373 To execute the tests for the Jenkins.get_version() API execute the com‐
374 mand:
375 tox -e py27 -- tests.test_version.JenkinsVersionTest
377 For further details on how to list tests available and different ways
379 to execute them, see https://wiki.openstack.org/wiki/Testr.
380 Test Coverage
382 To measure test coverage, execute the command:
383 tox -e cover
385 • genindex
387 • modindex
389 • search
391
393 Ken Conley, James Page, Tully Foote, Matthew Gertner
394
396 2022, Willow Garage
3971.7.0 Jan 21, 2022 PYTHONJENKINS(1)