After installation, you will need to create a configuration file. By default, jenkins-jobs looks for ~/.config/jenkins_jobs/jenkins_jobs.ini, <script directory>/jenkins_jobs.ini or /etc/jenkins_jobs/jenkins_jobs.ini (in that order), 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
include_path=.:scripts:~/git/
recursive=False
exclude=.*:manual:./development
allow_duplicates=False
[jenkins]
user=jenkins
password=1234567890abcdef1234567890abcdef
url=https://jenkins.example.com
query_plugins_info=False
##### This is deprecated, use job_builder section instead
#ignore_cache=True
[hipchat]
authtoken=dummy
[stash]
username=user
password=pass
This section is to control enabling of beta features or behaviour changes that deviate from previously released behaviour in ways that may require effort to convert existing JJB configs to adopt. This essentially will act as a method to share these new behaviours while under active development so they can be changed ahead of releases.
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; that is discussed in the next section.
Once you have a configuration defined, you can run the job builder in test mode.
If you want to run a simple test with just a single YAML job definition file and see the XML output on stdout:
jenkins-jobs test /path/to/foo.yaml
You can also pass JJB a directory containing multiple job definition files:
jenkins-jobs test /path/to/defs -o /path/to/output
which will write XML files to the output directory for all of the jobs defined in the defs directory.
When you’re satisfied with the generated XML from the test, you can run:
jenkins-jobs update /path/to/defs
which will upload the job definitions 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 jobs configurations in Jenkins if the defined definitions 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 the job names as additional arguments after the job definition path. To update Foo1 and Foo2 run:
jenkins-jobs update /path/to/defs Foo1 Foo2
You can also enable the parallel execution of the program passing the workers option with a value of 0, 2, or higher. Use 0 to run as many workers as cores in the host that runs it, and 2 or higher to specify the number of workers to use:
jenkins-jobs update --workers 0 /path/to/defs
It is possible to pass multiple paths to JJB using colons as a path separator on *nix systems and semi-colons on Windows systems. For example:
jenkins-jobs test /path/to/global:/path/to/instance:/path/to/instance/project
This helps when structuring directory layouts as you may selectively include directories in different ways to suit different needs. If you maintain multiple Jenkins instances suited to various needs you may want to share configuration between those instances (global). Furthermore, there may be various ways you would like to structure jobs within a given instance.
In addition to passing multiple paths to JJB it is also possible to enable recursive searching to process all yaml files in the tree beneath each path. For example:
For a tree:
/path/
to/
defs/
ci_jobs/
release_jobs/
globals/
macros/
templates/
jenkins-jobs update -r /path/to/defs:/path/to/globals
JJB will search defs/ci_jobs, defs/release_jobs, globals/macros and globals/templates in addition to the defs and globals trees.
To allow a complex tree of jobs where some jobs are managed differently without needing to explicitly provide each path, the recursive path processing supports excluding paths based on absolute paths, relative paths and patterns. For example:
For a tree:
/path/
to/
defs/
ci_jobs/
manual/
release_jobs/
manual/
qa_jobs/
globals/
macros/
templates/
special/
jenkins-jobs update -r -x man*:./qa_jobs -x /path/to/defs/globals/special \
/path/to/defs:/path/to/globals
JJB will search the given paths, ignoring the directories qa_jobs, ci_jobs/manual, release_jobs/manual, and globals/special when building the list of yaml files to be processed. Absolute paths are denoted by starting from the root, relative by containing the path separator, and patterns by having neither. Patterns use simple shell globing to match directories.
Jenkins Job Builder supports deleting jobs from Jenkins.
To delete a specific job:
jenkins-jobs delete Foo1
To delete a list of jobs, simply pass them as additional arguments after the command:
jenkins-jobs delete Foo1 Foo2
The update command includes a delete-old option to remove obsolete jobs:
jenkins-jobs update --delete-old /path/to/defs
Obsolete jobs are all jobs not managed by JJB, even jobs which were never managed by JJB.
There is also a command to delete all jobs. WARNING: Use with caution:
jenkins-jobs delete-all
Jenkins job builder supports globbed parameters to identify jobs from a set of definition files. This feature only supports JJB managed jobs.
To update jobs that only have ‘foo’ in their name:
jenkins-jobs update ./myjobs \*foo\*
To delete jobs that only have ‘foo’ in their name:
jenkins-jobs delete --path ./myjobs \*foo\*
usage: jenkins-jobs.py [-h] [--conf CONF] [-l LOG_LEVEL] [--ignore-cache]
[--flush-cache] [--version] [--allow-empty-variables]
[--user USER] [--password PASSWORD]
{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
--version show version
--allow-empty-variables
Don't fail if any of the variables inside any string
are not defined, replace with empty string instead
--user USER, -u USER The Jenkins user to use for authentication. This
overrides the user specified in the configuration file
--password PASSWORD, -p PASSWORD
Password or API token to use for authenticating
towards Jenkins. This overrides the password specified
in the configuration file.
usage: jenkins-jobs.py test [-h] [-r] [-x EXCLUDE] [-p PLUGINS_INFO_PATH]
[-o OUTPUT_DIR]
[path] [name [name ...]]
positional arguments:
path colon-separated list of paths to YAML files or
directories
name name(s) of job(s)
optional arguments:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x EXCLUDE, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
-p PLUGINS_INFO_PATH path to plugin info YAML file
-o OUTPUT_DIR path to output XML
usage: jenkins-jobs.py update [-h] [-r] [-x EXCLUDE] [--delete-old]
[--workers N_WORKERS]
path [names [names ...]]
positional arguments:
path colon-separated list of paths to YAML files or
directories
names name(s) of job(s)
optional arguments:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x EXCLUDE, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
--delete-old delete obsolete jobs
--workers N_WORKERS number of workers to use, 0 for autodetection and 1
for just one worker.
usage: jenkins-jobs.py delete-all [-h]
optional arguments:
-h, --help show this help message and exit
usage: jenkins-jobs.py delete [-h] [-r] [-x EXCLUDE] [-p PATH] name [name ...]
positional arguments:
name name of job
optional arguments:
-h, --help show this help message and exit
-r, --recursive look for yaml files recursively
-x EXCLUDE, --exclude EXCLUDE
paths to exclude when using recursive search, uses
standard globbing.
-p PATH, --path PATH colon-separated list of paths to YAML files or
directories
Footnotes
[1] | The cache default location is at ~/.cache/jenkins_jobs, which can be overridden by setting the XDG_CACHE_HOME environment variable. |