Welcome to AutoJenkins’s documentation!¶
AutoJenkins is a tool to automate or remote-control Jenkins. You can e.g. create and delete build jobs, trigger builds, read latest build results, etc.
Contents:
Introduction to AutoJenkins¶
AutoJenkins was written to handle automation (remote control) of Jenkins tasks.
Includes a class autojenkins.Jenkins
that you can use to drive Jenkins.
Things you can do with it:
- Copy a job (e.g. from a template job)
- Delete a job
- Obtain the
config.xml
file for that job - Trigger building of a job
- Obtain latest execution results
- ...
AutoJenkins may be used as an API or as a command-line tool.
AutoJenkins as API¶
Sample use:
from autojenkins import Jenkins
j = Jenkins('http://jenkins.pe.local')
# You can add verify_ssl_cert=False argument to the instantiation
# so that all requests will ignore SSL certificate errors, should you need that
# i.e. j = Jenkins('https://my.secure.jenkins', verify_ssl_cert=False)
# trigger a manual build and check results
j.build('warehouse-screens-us544_login')
j.last_result('warehouse-screens-us544_login')
# get only the result string (one of 'SUCCESS', 'UNSTABLE', 'FAILURE'):
j.last_result('warehouse-screens-us544_login')['result']
# get the configuration file for a job:
j.get_config_xml('template')
# Create a new job from a job named 'template', replacing variables
j.create_copy('my-new-job', 'template',
repo='mbf-warehouse-screens',
branch='us544_login',
package='warehouse_screens')
# build
j.build('my-new-job')
# check result and delete if successful:
result = j.last_result('my-new-job')['result']
if result == 'SUCCESS':
j.delete('my-new-job')
AutoJenkins from the Command Line¶
Available commands:
ajk-list
- list all jobs in a serverajk-create
- create a jobajk-build
- start building a jobajk-delete
- delete a job
ajk-list
¶
List all jobs in a Jenkins server. Each line in the output represents a job, and is colored according to the job’s last build state:
- Blue: success
- Yellow: unstable
- Red: failure
- Gray: not built
A *
symbol next to a job name indicates that the job is being built
right now.
If instead of colored output, you prefer a string stating the status
of the build, use the --no-color
option. This is useful if you
e.g. want to pipe the output into a grep
command that filters
jobs depending on status.
$ ajk-list -h
Usage: ajk-list host
Run autojenkins to list all jobs.
Options:
-h, --help show this help message and exit
-u USER, --user=USER
username
-p PASSWORD, --password=PASSWORD
password or token
-n, --no-color do not use colored output
-r, --raw only output job names, so that output is more usable for
piping to other processes
ajk-create
¶
Create a job from a template job, replacing variables that
use the django/jinja2 syntax {{ variable }}
.
Usage help:
$ ajk-create -h
Usage: ajk-create host [jobname] [options]
Run autojenkins to create a job.
Options:
-h, --help show this help message and exit
-u USER, --user=USER username
-p PASSWORD, --password=PASSWORD
password or token
-D VAR=VALUE substitution variables to be used in the template
-t TEMPLATE, --template=TEMPLATE
the template job to copy from
-b, --build start a build right after creation
Sample command:
$ ajk-create http://my.server my-job -t template -Dbranch=my-branch
ajk-build
¶
Trigger the building of a job, optionally waiting for it to complete.
When used with the --wait
flag, it will exit with a status different than
0 if the build is not successful. This makes it useful when including this in
shell scripts that depend on a successful build to take further action.
Usage help:
$ ajk-build -h
Usage: ajk-build host [jobname] [options]
Run autojenkins to build a job.
Options:
-h, --help show this help message and exit
-u USER, --user=USER username
-p PASSWORD, --password=PASSWORD
password or token
-w, --wait wait until the build completes
ajk-delete
¶
Delete a job from a Jenkins server.
Usage help:
$ ajk-delete -h
Usage: ajk-delete host [jobname]... [options]
Run autojenkins to delete one or more jobs.
Options:
-h, --help show this help message and exit
-u USER, --user=USER username
-p PASSWORD, --password=PASSWORD
password or token
More Info¶
Sources can be found in Github at https://github.com/txels/autojenkins
autojenkins.jobs
¶
-
class
autojenkins.jobs.
Jenkins
(base_url, auth=None, verify_ssl_cert=True, proxies={})¶ Main class to interact with a Jenkins server.
-
all_jobs
(include_colorless=False)¶ Get a list of tuples with (name, color) of all jobs in the server.
Color is
blue
,yellow
orred
depending on build results (SUCCESS, UNSTABLE or FAILED).
-
build
(jobname, params=None, wait=False, grace=10)¶ Trigger Jenkins to build a job.
Parameters: - params – If params are provided, use the “buildWithParameters” endpoint
- wait – If
True
, wait until job completes building before returning
-
build_console
(jobname, build_number=None)¶ Get the console output for the build of a job.
If no build number is specified, defaults to the most recent build.
-
build_info
(jobname, build_number=None)¶ Get information for a build of a job.
If no build number is specified, defaults to the most recent build.
-
console_text
(jobname, build_number='lastBuild')¶ Get console text output of last build.
-
copy
(jobname, copy_from='template')¶ Copy a job from another one (by default from one called
template
).
-
create
(jobname, config_file, **context)¶ Create a job from a configuration file.
-
create_copy
(jobname, template_job, enable=True, _force=False, **context)¶ Create a job from a template job.
-
delete
(jobname)¶ Delete a job.
-
disable
(jobname)¶ Trigger Jenkins to disable a job.
-
enable
(jobname)¶ Trigger Jenkins to enable a job.
-
get_config_xml
(jobname)¶ Get the
config.xml
file that contains the job definition.
-
is_building
(jobname)¶ Check if a job is building
-
job_info
(jobname)¶ Get all information for a job as a Python object (dicts & lists).
-
job_url
(jobname)¶ Get the human-browseable URL for a job.
-
last_build_console
(jobname)¶ Get the console output for the last build of a job.
-
last_build_info
(jobname)¶ Get information for last build of a job.
-
last_build_report
(jobname)¶ Get full report of last build.
-
last_result
(jobname)¶ Obtain results from last execution.
-
last_success
(jobname)¶ Return information about the last successful build.
-
set_config_xml
(jobname, config)¶ Replace the
config.xml
of an existing job.
-
transfer
(jobname, to_server)¶ Copy a job to another server.
-
wait_for_build
(jobname, poll_interval=3)¶ Wait until job has finished building
-
Sources can be found at https://github.com/txels/autojenkins