17b8942733
Specify if is python, xml or bash the code blocks in examples. Fixes a couple doc build warnings Change-Id: I3ea9f3aabe23656752c23c843c297f3872454a17
274 lines
8.9 KiB
ReStructuredText
274 lines
8.9 KiB
ReStructuredText
Using Python-Jenkins
|
|
====================
|
|
|
|
The python-jenkins library allows management of a Jenkins server through
|
|
the Jenkins REST endpoints. Below are examples to get you started using
|
|
the library. If you need further help take a look at the :doc:`api`
|
|
docs for more details.
|
|
|
|
|
|
Example 1: Get version of Jenkins
|
|
---------------------------------
|
|
|
|
This is an example showing how to connect to a Jenkins instance and
|
|
retrieve the Jenkins server version.
|
|
|
|
.. code-block:: python
|
|
|
|
import jenkins
|
|
|
|
server = jenkins.Jenkins('http://localhost:8080', username='myuser', password='mypassword')
|
|
user = server.get_whoami()
|
|
version = server.get_version()
|
|
print('Hello %s from Jenkins %s' % (user['fullName'], version))
|
|
|
|
The above code prints the fullName attribute of the user and the version of
|
|
the Jenkins master running on 'localhost:8080'. For example, it may print
|
|
"Hello John from Jenkins 2.0".
|
|
|
|
From Jenkins version 1.426 onward you can specify an API token instead of your
|
|
real password while authenticating the user against the Jenkins instance.
|
|
Refer to the `Jenkins Authentication`_ wiki for details about how you
|
|
can generate an API token. Once you have an API token you can pass the API token
|
|
instead of a real password while creating a Jenkins instance.
|
|
|
|
.. _Jenkins Authentication: https://wiki.jenkins-ci.org/display/JENKINS/Authenticating+scripted+clients
|
|
|
|
Example 2: Logging into Jenkins using kerberos
|
|
----------------------------------------------
|
|
|
|
Kerberos support is only enabled if you have "kerberos" python package installed.
|
|
You can install the "kerberos" package from PyPI using the obvious pip command.
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install kerberos
|
|
|
|
.. note:: This might require python header files as well
|
|
as kerberos header files.
|
|
|
|
If you have "kerberos" python package installed, python-jenkins tries to authenticate
|
|
using kerberos automatically when the Jenkins server replies "401 Unauthorized"
|
|
and indicates it supports kerberos. That is, kerberos authentication should
|
|
work automagically. For a quick test, just try the following.
|
|
|
|
.. code-block:: python
|
|
|
|
import jenkins
|
|
|
|
server = jenkins.Jenkins('http://localhost:8080')
|
|
print server.jobs_count()
|
|
|
|
.. note:: Jenkins as such does not support kerberos, it needs to be supported by
|
|
the Servlet container or a reverse proxy sitting in front of Jenkins.
|
|
|
|
|
|
Example 3: Working with Jenkins Jobs
|
|
------------------------------------
|
|
|
|
This is an example showing how to create, configure and delete Jenkins jobs.
|
|
|
|
.. code-block:: python
|
|
|
|
server.create_job('empty', jenkins.EMPTY_CONFIG_XML)
|
|
jobs = server.get_jobs()
|
|
print jobs
|
|
my_job = server.get_job_config('cool-job')
|
|
print(my_job) # prints XML configuration
|
|
server.build_job('empty')
|
|
server.disable_job('empty')
|
|
server.copy_job('empty', 'empty_copy')
|
|
server.enable_job('empty_copy')
|
|
server.reconfig_job('empty_copy', jenkins.RECONFIG_XML)
|
|
|
|
server.delete_job('empty')
|
|
server.delete_job('empty_copy')
|
|
|
|
# build a parameterized job
|
|
# requires creating and configuring the api-test job to accept 'param1' & 'param2'
|
|
server.build_job('api-test', {'param1': 'test value 1', 'param2': 'test value 2'})
|
|
last_build_number = server.get_job_info('api-test')['lastCompletedBuild']['number']
|
|
build_info = server.get_build_info('api-test', last_build_number)
|
|
print build_info
|
|
|
|
# get all jobs from the specific view
|
|
jobs = server.get_jobs(view_name='View Name')
|
|
print jobs
|
|
|
|
|
|
Example 4: Working with Jenkins Views
|
|
-------------------------------------
|
|
|
|
This is an example showing how to create, configure and delete Jenkins views.
|
|
|
|
.. code-block:: python
|
|
|
|
server.create_view('EMPTY', jenkins.EMPTY_VIEW_CONFIG_XML)
|
|
view_config = server.get_view_config('EMPTY')
|
|
views = server.get_views()
|
|
server.delete_view('EMPTY')
|
|
print views
|
|
|
|
|
|
Example 5: Working with Jenkins Plugins
|
|
---------------------------------------
|
|
|
|
This is an example showing how to retrieve Jenkins plugins information.
|
|
|
|
.. code-block:: python
|
|
|
|
plugins = server.get_plugins_info()
|
|
print plugins
|
|
|
|
The above example will print a dictionary containing all the plugins that
|
|
are installed on the Jenkins server. An example of what you can expect
|
|
from the :func:`get_plugins_info` method is documented in the :doc:`api`
|
|
doc.
|
|
|
|
|
|
Example 6: Working with Jenkins Nodes
|
|
-------------------------------------
|
|
|
|
This is an example showing how to add, configure, enable and delete Jenkins nodes.
|
|
|
|
.. code-block:: python
|
|
|
|
server.create_node('slave1')
|
|
nodes = get_nodes()
|
|
print nodes
|
|
node_config = server.get_node_info('slave1')
|
|
print node_config
|
|
server.disable_node('slave1')
|
|
server.enable_node('slave1')
|
|
|
|
# create node with parameters
|
|
params = {
|
|
'port': '22',
|
|
'username': 'juser',
|
|
'credentialsId': '10f3a3c8-be35-327e-b60b-a3e5edb0e45f',
|
|
'host': 'my.jenkins.slave1'
|
|
}
|
|
server.create_node(
|
|
'slave1',
|
|
nodeDescription='my test slave',
|
|
remoteFS='/home/juser',
|
|
labels='precise',
|
|
exclusive=True,
|
|
launcher=jenkins.LAUNCHER_SSH,
|
|
launcher_params=params)
|
|
|
|
Example 7: Working with Jenkins Build Queue
|
|
-------------------------------------------
|
|
|
|
This is an example showing how to retrieve information on the Jenkins queue.
|
|
|
|
.. code-block:: python
|
|
|
|
server.build_job('foo')
|
|
queue_info = server.get_queue_info()
|
|
id = queue_info[0].get('id')
|
|
server.cancel_queue(id)
|
|
|
|
|
|
Example 8: Working with Jenkins Cloudbees Folders
|
|
-------------------------------------------------
|
|
|
|
Requires the `Cloudbees Folders Plugin
|
|
<https://wiki.jenkins-ci.org/display/JENKINS/CloudBees+Folders+Plugin>`_ for
|
|
Jenkins.
|
|
|
|
This is an example showing how to create, configure and delete Jenkins folders.
|
|
|
|
.. code-block:: python
|
|
|
|
server.create_job('folder', jenkins.EMPTY_FOLDER_XML)
|
|
server.create_job('folder/empty', jenkins.EMPTY_FOLDER_XML)
|
|
server.copy_job('folder/empty', 'folder/empty_copy')
|
|
server.delete_job('folder/empty_copy')
|
|
server.delete_job('folder')
|
|
|
|
|
|
Example 9: Updating Next Build Number
|
|
-------------------------------------
|
|
|
|
Requires the `Next Build Number Plugin
|
|
<https://wiki.jenkins-ci.org/display/JENKINS/Next+Build+Number+Plugin>`_
|
|
for Jenkins.
|
|
|
|
This is an example showing how to update the next build number for a
|
|
Jenkins job.
|
|
|
|
.. code-block:: python
|
|
|
|
next_bn = server.get_job_info('job_name')['nextBuildNumber']
|
|
server.set_next_build_number('job_name', next_bn + 50)
|
|
|
|
|
|
Example 9: Working with Build Promotions
|
|
----------------------------------------
|
|
|
|
Requires the `Promoted Builds Plugin
|
|
<https://wiki.jenkins-ci.org/display/JENKINS/Promoted+Builds+Plugin>`_
|
|
for Jenkins.
|
|
|
|
This is an example showing how to create, configure and delete a
|
|
promotion process for an existing job.
|
|
|
|
The job in this example is named *prom_job* and it needs to have this
|
|
config xml snippet before creating the promotion:
|
|
|
|
.. code-block:: xml
|
|
|
|
<properties>
|
|
<hudson.plugins.promoted__builds.JobPropertyImpl>
|
|
<activeProcessNames>
|
|
<string>prom_name</string>
|
|
</activeProcessNames>
|
|
</hudson.plugins.promoted__builds.JobPropertyImpl>
|
|
</properties>
|
|
|
|
where *prom_name* is the name of the promotion that will get added to the job.
|
|
|
|
.. code-block:: python
|
|
|
|
server.create_promotion('prom_name', 'prom_job', jenkins.EMPTY_PROMO_CONFIG_XML)
|
|
server.promotion_exists('prom_name', 'prom_job')
|
|
print server.get_promotions('prom_job')
|
|
|
|
server.reconfig_promotion('prom_name', 'prom_job', jenkins.PROMO_RECONFIG_XML)
|
|
print server.get_promotion_config('prom_name', 'prom_job')
|
|
|
|
server.delete_promotion('prom_name', 'prom_job')
|
|
|
|
|
|
Example 10: Waiting for Jenkins to be ready
|
|
-------------------------------------------
|
|
|
|
It is possible to ask the API to wait for Jenkins to be ready with a given
|
|
timeout. This can be used to aid launching of Jenkins and then waiting for the
|
|
REST API to be responsive before continuing with subsequent configuration.
|
|
|
|
.. code-block:: python
|
|
|
|
# timeout here is the socket connection timeout, for each connection
|
|
# attempt it will wait at most 5 seconds before assuming there is
|
|
# nothing listening. Useful where firewalls may black hole connections.
|
|
server = jenkins.Jenkins('http://localhost:8080', timeout=5)
|
|
|
|
# wait for at least 30 seconds for Jenkins to be ready
|
|
if server.wait_for_normal_op(30):
|
|
# actions once running
|
|
...
|
|
else:
|
|
print("Jenkins failed to be ready in sufficient time")
|
|
exit 2
|
|
|
|
Note that the timeout arg to `jenkins.Jenkins()` is the socket connection
|
|
timeout. If you set this to be more than the timeout value passed to
|
|
`wait_for_normal_op()`, then in cases where the underlying connection is not
|
|
rejected (firewall black-hole, or slow connection) then `wait_for_normal_op()`
|
|
may wait at least the connection timeout, or a multiple of it where multiple
|
|
connection attempts are made. A connection timeout of 5 seconds and a wait
|
|
timeout of 8 will result in potentially waiting 10 seconds if both connections
|
|
attempts do not get responses.
|