pythonjenkins - Man Page
Name
pythonjenkins — Python Jenkins Documentation
Python Jenkins is a python wrapper for the Jenkins REST API which aims to provide a more conventionally pythonic way of controlling a Jenkins server. It provides a higher-level API containing a number of convenience functions.
We like to use python-jenkins to automate our Jenkins servers. Here are some of the things you can use it for:
- Create new jobs
- Copy existing jobs
- Delete jobs
- Update jobs
- Get a job's build information
- Get Jenkins master version information
- Get Jenkins plugin information
- Start a build on a job
- Create nodes
- Enable/Disable nodes
- Get information on nodes
- Create/delete/reconfig views
- Put server in shutdown mode (quiet down)
- List running builds
- Delete builds
- Wipeout job workspace
- Create/delete/update folders [1]
- Set the next build number [2]
- Install plugins
- and many more..
To install:
$ sudo python setup.py install
Online documentation:
Developers
Bug report:
Repository:
Cloning:
- git clone https://opendev.org/jjb/python-jenkins
Patches are submitted via Gerrit at:
Please do not submit GitHub pull requests, they will be automatically closed.
The python-jenkins developers communicate in the #openstack-jjb channel on Freenode's IRC network.
More details on how you can contribute is available on our wiki at:
Writing a Patch
Be sure that you lint code before created an code review. The easiest way to do this is to install git pre-commit hooks.
Installing Without setup.py
Then install the required python packages using pip:
$ sudo pip install python-jenkins
Footnotes
- [1]
The free Cloudbees Folders Plugin provides support for a subset of the full folders functionality. For the complete capabilities you will need the paid for version of the plugin.
- [2]
The Next Build Number Plugin provides support for setting the next build number.
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 API reference 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.
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.
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.
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.
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.
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.
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.
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 get_plugins_info() method is documented in the API reference doc.
Example 6: Working with Jenkins Nodes
This is an example showing how to add, configure, enable and delete Jenkins nodes.
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.
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 for Jenkins.
This is an example showing how to create, configure and delete Jenkins folders.
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 for Jenkins.
This is an example showing how to update the next build number for a Jenkins job.
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 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:
<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.
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.
# 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.
Installing
The module is known to pip and Debian-based distributions as python-jenkins.
pip:
pip install python-jenkins
easy_install:
easy_install python-jenkins
The module has been packaged since Ubuntu Oneiric (11.10):
apt-get install python-jenkins
And on Fedora 19 and later:
yum install python-jenkins
For development:
python setup.py develop
Documentation
Documentation is included in the doc folder. To generate docs locally execute the command:
tox -e docs
The generated documentation is then available under doc/build/html/index.html.
Unit Tests
Unit tests have been included and are in the tests folder. We recently started including unit tests as examples in our documentation so to keep the examples up to date it is very important that we include unit tests for every module. To run the unit tests, execute the command:
tox -e py27
- Note: View tox.ini to run tests on other versions of Python.
Due to how the tests are split up into a dedicated class per API method, it is possible to execute tests against a single API at a time. To execute the tests for the Jenkins.get_version() API execute the command:
tox -e py27 -- tests.test_version.JenkinsVersionTest
For further details on how to list tests available and different ways to execute them, see https://wiki.openstack.org/wiki/Testr.
Test Coverage
To measure test coverage, execute the command:
tox -e cover
- Index
- Module Index
- Search Page
Author
Ken Conley, James Page, Tully Foote, Matthew Gertner
Copyright
2023, Willow Garage