To install Jenkins Job Builder, run:
sudo python setup.py install
The OpenStack project uses Puppet to manage its infrastructure systems, including Jenkins. If you use Puppet, you can use the OpenStack Jenkins module to install Jenkins Job Builder.
Documentation is included in the doc folder. To generate docs locally execute the command:
tox -e doc
The generated documentation is then available under doc/build/html/index.html.
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
After installation, you will need to create a configuration file. By default, jenkins-jobs looks in /etc/jenkins_jobs/jenkins_jobs.ini but you may specify an alternative location when running jenkins-jobs. The file should have the following format:
[job_builder]
ignore_cache=True
keep_descriptions=False
[jenkins]
user=jenkins
password=1234567890abcdef1234567890abcdef
url=https://jenkins.example.com
##### This is deprecated, use job_builder section instead
#ignore_cache=True
After it’s installed and configured, you can invoke Jenkins Job Builder by running jenkins-jobs. You won’t be able to do anything useful just yet without a configuration which is discussed in the next section.
usage: jenkins-jobs.py [-h] [--conf CONF] [-l LOG_LEVEL] [--ignore-cache]
[--flush-cache]
{update,test,delete,delete-all} ...
positional arguments:
{update,test,delete,delete-all}
update, test or delete job
delete-all delete *ALL* jobs from Jenkins server, including those
not managed by Jenkins Job Builder.
optional arguments:
-h, --help show this help message and exit
--conf CONF configuration file
-l LOG_LEVEL, --log_level LOG_LEVEL
log level (default: info)
--ignore-cache ignore the cache and update the jobs anyhow (that will
only flush the specified jobs cache)
--flush-cache flush all the cache entries before updating
Once you have a configuration defined, you can test the job builder by running:
jenkins-jobs test /path/to/config -o /path/to/output
which will write XML files to the output directory for all of the jobs defined in the configuration directory.
If you want to run a simple test with just a single YAML file and see the XML output on stdout:
jenkins-jobs test /path/to/config
When you’re satisfied with the generated XML from the test, you can run:
jenkins-jobs update /path/to/config
which will upload the configurations to Jenkins if needed. Jenkins Job Builder maintains, for each host, a cache [1] of previously configured jobs, so that you can run that command as often as you like, and it will only update the configuration in Jenkins if the defined configuration has changed since the last time it was run. Note: if you modify a job directly in Jenkins, jenkins-jobs will not know about it and will not update it.
To update a specific list of jobs, simply pass them as additional arguments after the configuration path. To update Foo1 and Foo2 run:
jenkins-jobs update /path/to/config Foo1 Foo2
Footnotes
[1] | The cache default location is at ~/.cache/jenkins_jobs, which can be overridden by setting the XDG_CACHE_HOME environment variable. |