Welcome to api4jenkins’s documentation!

api4jenkins is an object oriented Python project that provides access to the Jenkins Remote access API programmatically. It assiciates/constructs python class/object with Jenkins’s items and JSON API.


It provides but not limits functionalities to control Job, Build, Node, View, Credential, BuildQueue, Plugins and System:

  • get/delete/create/move/rename/copy/build/enable/disable job or folder, iterate children jobs with depth, folder based views/credentials functionalities

  • get/iterate builds of project, stop/term/kill build, get progressive console output.

  • get/delete/create/iterate views for jenkins or folder. add/remove jobs to/from view.

  • get/delete/create/iterate credentials for system or folder.

  • get/delete/create/iterate nodes, run groovy script on node.

  • get/cancel/iterate queue item, get job/build from queue item.

  • restart/safe restart/quiet down/cancel quiet down/run groovy script for master

  • get item status(int, bool, str) by accessing attribute of python object.

  • install/uninstall/iterate plugin, check installation status, change update site and set proxy

Quick start

Here is an example to create job and start build, obtain build object the queue item, and pull progressive output until its completion, and obtain the build status.

>>> from api4jenkins import Jenkins
>>> j = Jenkins('http://127.0.0.1:8080/', auth=('admin', 'admin'))
>>> j.version
'2.176.2'
>>> xml = """<?xml version='1.1' encoding='UTF-8'?>
... <project>
...   <builders>
...     <hudson.tasks.Shell>
...       <command>echo $JENKINS_VERSION</command>
...     </hudson.tasks.Shell>
...   </builders>
... </project>"""
>>> j.create_job('freestylejob', xml)
>>> job = j.get_job('freestylejob')
>>> print(job)
<FreeStyleProject: http://127.0.0.1:8080/job/freestylejob/>
>>> print(job.parent)
<Jenkins: http://127.0.0.1:8080/>
>>> print(job.jenkins)
<Jenkins: http://127.0.0.1:8080/>
>>> import time
>>> item = job.build()
>>> while not item.get_build():
...      time.sleep(1)
>>> build = item.get_build()
>>> print(build)
<FreeStyleBuild: http://127.0.0.1:8080/job/freestylejob/1/>
>>> for line in build.progressive_output():
...     print(line)
...
Started by user admin
Running as SYSTEM
Building in workspace /var/jenkins_home/workspace/freestylejob
[freestylejob] $ /bin/sh -xe /tmp/jenkins2989549474028065940.sh
+ echo $JENKINS_VERSION
2.176.2
Finished: SUCCESS
>>> build.building
False
>>> build.result
'SUCCESS'

Indices and tables