jenkins-jobs(1)

. .

.

\\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2]

. RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1

. RE

jenkins-jobs - Jenkins Job Builder Documentation

Jenkins Job Builder takes simple descriptions of \%Jenkins jobs in \%YAML or \%JSON format and uses them to configure Jenkins. You can keep your job descriptions in human readable text format in a version control system to make changes and auditing easier. It also has a flexible template system, so creating many similarly configured jobs is easy.

To install:

$ pip install --user jenkins-job-builder

Online documentation:

\%https://jenkins-job-builder.readthedocs.io/en/latest/

Bug report:

\%https://storyboard.openstack.org/#!/project/723

Repository:

\%https://opendev.org/jjb/jenkins-job-builder

Cloning:

git clone https://opendev.org/jjb/jenkins-job-builder.git

Install pre-commit from \%https://pre-commit.com/#intro in order to run some minimal testing on your commits.

A virtual environment is recommended for development. For example, Jenkins Job Builder may be installed from the top level directory:

$ virtualenv .venv $ source .venv/bin/activate $ pip install -r test-requirements.txt -e .

Patches are submitted via Gerrit at:

\%https://review.opendev.org

Please do not submit GitHub pull requests, they will be automatically closed.

Mailing list:

\%https://groups.google.com/forum/#!forum/jenkins-job-builder

IRC:

#openstack-jjb on OFTC

More details on how you can contribute is available on our wiki at:

\%https://docs.openstack.org/infra/manual/developers.html

We ask that all code submissions be \%pep8 and \%pyflakes clean. The easiest way to do that is to run \%tox before submitting code for review in Gerrit. It will run pep8 and pyflakes in the same manner as the automated test suite that will run on proposed patchsets.

When creating new YAML components, please observe the following style conventions:

All YAML identifiers (including component names and arguments) should be lower-case and multiple word identifiers should use hyphens. E.g., \(dqbuild-trigger\(dq.

The Python functions that implement components should have the same name as the YAML keyword, but should use underscores instead of hyphens. E.g., \(dqbuild_trigger\(dq.

This consistency will help users avoid simple mistakes when writing YAML, as well as developers when matching YAML components to Python implementation.

Unit tests have been included and are in the tests folder. Many unit tests samples are included as examples in our documentation to ensure that examples are kept current with existing behaviour. To run the unit tests, execute the command:

tox -e py34,py27

Note: View tox.ini to run tests on other versions of Python, generating the documentation and additionally for any special notes on running the test to validate documentation external URLs from behind proxies.

For YAML support, you will need \%libyaml installed.

Mac OS X:

$ brew install libyaml

Then install the required python packages using \%pip:

$ sudo pip install PyYAML python-jenkins

This guide was made with the impatient in mind so explanation is sparse. It will guide users through a set of typical use cases for JJB using the same job definitions we use to test JJB.

Clone the \%repository to get the JJB job definition \%examples

The \%Installation can be either from \%pypi (released version) or from the clone (master).

Usage of the commands below assumes that you are at the root of the cloned directory.

JJB creates Jenkins XML configuration file from a YAML/JSON definition file and just uploads it to Jenkins. JJB provides a convenient test command to allow you to validate the XML before you attempt to upload it to Jenkins.

Test a YAML job definition:

jenkins-jobs test tests/yamlparser/fixtures/templates002.yaml

The above command prints the generated Jenkins XML to the console. If you prefer to send it to a directory:

jenkins-jobs test -o output tests/yamlparser/fixtures/templates002.yaml

The output directory will contain files with the XML configurations.

Once you\(aqve tested your job definition and are happy with it then you can use the update command to deploy the job to Jenkins. The update command requires a configuration file. An example file is supplied in the etc folder, you should update it to match your Jenkins master:

jenkins-jobs --conf etc/jenkins_jobs.ini-sample update tests/yamlparser/fixtures/templates002.yaml

The above command will update your Jenkins master with the generated jobs.

Caution: JJB caches Jenkins job information locally. Changes made using the Jenkins UI will not update that cache, which may lead to confusion. See \%Updating Jobs for more information.

You can also define your jobs in json instead of yaml:

jenkins-jobs --conf etc/jenkins_jobs.ini-sample update tests/jsonparser/fixtures/simple.json

The above command just uses a simple job definition. You can also convert any of the YAML examples to JSON and feed that to JJB.

To delete a job:

jenkins-jobs --conf etc/jenkins_jobs.ini-sample delete simple

The above command deletes the job simple from the Jenkins master.

To generate a plugins info, using an account with Administrator rights:

jenkins-jobs get-plugins-info -o plugins_info.yaml

To run JJB update using the plugins_info.yaml:

jenkins-jobs update -p plugins_info.yaml ./myjobs

Please refer to the jenkins-jobs \%Command Reference and the \%Job Definitions pages for more details.

To install Jenkins Job Builder from source, run:

pip install --user jenkins-job-builder

A virtual environment is recommended for development. For example, Jenkins Job Builder may be installed from the top level directory:

$ virtualenv .venv $ source .venv/bin/activate $ pip install -r test-requirements.txt -e .

Alternatively, the current release can be installed from pypi:

sudo pip install jenkins-job-builder

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 docs

The generated documentation is then available under doc/build/html/index.html.

As over time URLs change or become stale there is also a testenv available to verify any links added. To run locally execute the command:

tox -e docs-linkcheck

Note: When behind a proxy it is necessary to use TOX_TESTENV_PASSENV to pass any proxy settings for this test to be able to check links are valid.

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.

To measure test coverage, execute the command:

tox -e cover

After installation, you will need to create a configuration file. By default, jenkins-jobs looks for ~/.config/jenkins_jobs/jenkins_jobs.ini,