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://git.openstack.org/cgit/openstack/python-jenkins
72
73       Cloning:
74
75       • git clone https://git.openstack.org/openstack/python-jenkins
76
77       Patches are submitted via Gerrit at:
78
79https://review.openstack.org/
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
89http://docs.openstack.org/infra/manual/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 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 doc.
211
212   Example 6: Working with Jenkins Nodes
213       This  is  an  example  showing how to add, configure, enable and delete
214       Jenkins nodes.
215
216          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
224          # 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
240   Example 7: Working with Jenkins Build Queue
241       This is an example showing how to retrieve information on  the  Jenkins
242       queue.
243
244          server.build_job('foo')
245          queue_info = server.get_queue_info()
246          id = queue_info[0].get('id')
247          server.cancel_queue(id)
248
249   Example 8: Working with Jenkins Cloudbees Folders
250       Requires the Cloudbees Folders Plugin for Jenkins.
251
252       This  is an example showing how to create, configure and delete Jenkins
253       folders.
254
255          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
261   Example 9: Updating Next Build Number
262       Requires the Next Build Number Plugin for Jenkins.
263
264       This is an example showing how to update the next build  number  for  a
265       Jenkins job.
266
267          next_bn = server.get_job_info('job_name')['nextBuildNumber']
268          server.set_next_build_number('job_name', next_bn + 50)
269
270   Example 9: Working with Build Promotions
271       Requires the Promoted Builds Plugin for Jenkins.
272
273       This is an example showing how to create, configure and delete a promo‐
274       tion process for an existing job.
275
276       The job in this example is named prom_job and it  needs  to  have  this
277       config xml snippet before creating the promotion:
278
279          <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
287       where prom_name is the name of the promotion that will get added to the
288       job.
289
290          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
294          server.reconfig_promotion('prom_name', 'prom_job', jenkins.PROMO_RECONFIG_XML)
295          print server.get_promotion_config('prom_name', 'prom_job')
296
297          server.delete_promotion('prom_name', 'prom_job')
298
299   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
305          # 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
310          # 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
318       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

INSTALLING

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

AUTHOR

393       Ken Conley, James Page, Tully Foote, Matthew Gertner
394
396       2022, Willow Garage
397
398
399
400
4011.7.0                            Jan 21, 2022                 PYTHONJENKINS(1)
Impressum