1PYTHONJENKINS(1)                Python Jenkins                PYTHONJENKINS(1)
2
3
4

NAME

6       pythonjenkins - Python Jenkins Documentation
7
8       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
13       We like to use python-jenkins to automate our Jenkins servers. Here are
14       some of the things you can use it for:
15
16       • Create new jobs
17
18       • Copy existing jobs
19
20       • Delete jobs
21
22       • Update jobs
23
24       • Get a job's build information
25
26       • Get Jenkins master version information
27
28       • Get Jenkins plugin information
29
30       • Start a build on a job
31
32       • Create nodes
33
34       • Enable/Disable nodes
35
36       • Get information on nodes
37
38       • Create/delete/reconfig views
39
40       • Put server in shutdown mode (quiet down)
41
42       • List running builds
43
44       • Delete builds
45
46       • Wipeout job workspace
47
48       • Create/delete/update folders [1]
49
50       • Set the next build number [2]
51
52       • Install plugins
53
54       • and many more..
55
56       To install:
57
58          $ sudo python setup.py install
59
60       Online documentation:
61
62http://python-jenkins.readthedocs.org/en/latest/
63

DEVELOPERS

65       Bug report:
66
67https://bugs.launchpad.net/python-jenkins
68
69       Repository:
70
71https://opendev.org/jjb/python-jenkins
72
73       Cloning:
74
75       • git clone https://opendev.org/jjb/python-jenkins
76
77       Patches are submitted via Gerrit at:
78
79https://review.opendev.org/#/q/project:jjb/python-jenkins
80
81       Please  do  not submit GitHub pull requests, they will be automatically
82       closed.
83
84       The python-jenkins developers communicate in the #openstack-jjb channel
85       on Freenode's IRC network.
86
87       More details on how you can contribute is available on our wiki at:
88
89https://docs.opendev.org/opendev/infra-manual/latest/developers.html
90

WRITING A PATCH

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

INSTALLING WITHOUT SETUP.PY

96       Then install the required python packages using pip:
97
98          $ sudo pip install python-jenkins
99

FOOTNOTES

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
105       [2]  The Next Build Number Plugin provides support for setting the next
106            build number.
107

USING PYTHON-JENKINS

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
114   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
118          import jenkins
119
120          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
125       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
129       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
136   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
141          pip install kerberos
142
143       NOTE:
144          This might require python header files as well  as  kerberos  header
145          files.
146
147       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
153          import jenkins
154
155          server = jenkins.Jenkins('http://localhost:8080')
156          print server.jobs_count()
157
158       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
163   Example 3: Working with Jenkins Jobs
164       This  is an example showing how to create, configure and delete Jenkins
165       jobs.
166
167          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
178          server.delete_job('empty')
179          server.delete_job('empty_copy')
180
181          # 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
188          # get all jobs from the specific view
189          jobs = server.get_jobs(view_name='View Name')
190          print jobs
191
192   Example 4: Working with Jenkins Views
193       This is an example showing how to create, configure and delete  Jenkins
194       views.
195
196          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
202   Example 5: Working with Jenkins Plugins
203       This is an example showing how to retrieve Jenkins plugins information.
204
205          plugins = server.get_plugins_info()
206          print plugins
207
208       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
213   Example 6: Working with Jenkins Nodes
214       This is an example showing how to add,  configure,  enable  and  delete
215       Jenkins nodes.
216
217          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
225          # 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
241   Example 7: Working with Jenkins Build Queue
242       This  is  an example showing how to retrieve information on the Jenkins
243       queue.
244
245          server.build_job('foo')
246          queue_info = server.get_queue_info()
247          id = queue_info[0].get('id')
248          server.cancel_queue(id)
249
250   Example 8: Working with Jenkins Cloudbees Folders
251       Requires the Cloudbees Folders Plugin for Jenkins.
252
253       This is an example showing how to create, configure and delete  Jenkins
254       folders.
255
256          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
262   Example 9: Updating Next Build Number
263       Requires the Next Build Number Plugin for Jenkins.
264
265       This  is  an  example showing how to update the next build number for a
266       Jenkins job.
267
268          next_bn = server.get_job_info('job_name')['nextBuildNumber']
269          server.set_next_build_number('job_name', next_bn + 50)
270
271   Example 9: Working with Build Promotions
272       Requires the Promoted Builds Plugin for Jenkins.
273
274       This is an example showing how to create, configure and delete a promo‐
275       tion process for an existing job.
276
277       The  job  in  this  example is named prom_job and it needs to have this
278       config xml snippet before creating the promotion:
279
280          <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
288       where prom_name is the name of the promotion that will get added to the
289       job.
290
291          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
295          server.reconfig_promotion('prom_name', 'prom_job', jenkins.PROMO_RECONFIG_XML)
296          print server.get_promotion_config('prom_name', 'prom_job')
297
298          server.delete_promotion('prom_name', 'prom_job')
299
300   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
306          # 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
311          # 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
319       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

INSTALLING

330       The  module  is  known  to  pip  and  Debian-based   distributions   as
331       python-jenkins.
332
333       pip:
334
335          pip install python-jenkins
336
337       easy_install:
338
339          easy_install python-jenkins
340
341       The module has been packaged since Ubuntu Oneiric (11.10):
342
343          apt-get install python-jenkins
344
345       And on Fedora 19 and later:
346
347          yum install python-jenkins
348
349       For development:
350
351          python setup.py develop
352
353   Documentation
354       Documentation  is  included in the doc folder. To generate docs locally
355       execute the command:
356
357          tox -e docs
358
359       The generated documentation is then available under  doc/build/html/in‐
360       dex.html.
361
362   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
368          tox -e py27
369
370       • Note: View tox.ini to run tests on other versions of Python.
371
372       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
377          tox -e py27 -- tests.test_version.JenkinsVersionTest
378
379       For  further  details on how to list tests available and different ways
380       to execute them, see https://wiki.openstack.org/wiki/Testr.
381
382   Test Coverage
383       To measure test coverage, execute the command:
384
385          tox -e cover
386
387Index
388
389Module Index
390
391Search Page
392

AUTHOR

394       Ken Conley, James Page, Tully Foote, Matthew Gertner
395
397       2023, Willow Garage
398
399
400
401
4021.8.0                            Jul 22, 2023                 PYTHONJENKINS(1)
Impressum