Continuous integration/Jenkins job builder

Jenkins Job builder is a python script to automatically generate job in Jenkins out of .yaml files describing them. It generates the .xml files and then update Jenkins installation using its Json API. Upstream documentation is available at: http://ci.openstack.org/jenkins-job-builder/.

Getting code
Wikimedia maintains its own fork under integration/jenkins-job-builder.git which let us push changes in production before having them reviewed by upstream. To install it on your computer simply clone WMF repository:

git clone ssh://gerrit.wikimedia.org/r/p/integration/jenkins-job-builder.git

Then enable the software using python setup.py develop. That will install the required dependencies and create a dummy site package pointing to your current working directory. Once completed, your should be able to run it using jenkins-jobs.

WMF configuration
The job configuration are hosted under integration/jenkins-job-builder-config.git and contains the yaml files describing our Jenkins jobs. You will want to clone that repository using the name config under your jenkins job builder working directory:

cd /path/to/jenkins-job-builder git clone -o gerrit ssh://gerrit.wikimedia.org:29418/integration/jenkins-job-builder-config.git config

Configuration
Create a file named jenkins_jobs.ini :

[jenkins] user=nobody password=none url=https://integration.mediawiki.org/ci/

Jenkins job builder require a Jenkins user and API token that would let it update the job. If you simply want to generate the XML files, you do not need any credentials.

Verify your installation
In your jenkins job builder working directory:

mkdir output # place where XML files will be written to jenkins-jobs test config/ -o output/

output/ should now contains some files (exact list depending on the current configuration fetched under config/):

$ ls -1 output/ mediawiki-core-install-sqlite mediawiki-core-lint mediawiki-core-merge mediawiki-core-phpunit-api mediawiki-core-phpunit-databaseless mediawiki-core-phpunit-misc mediawiki-core-phpunit-parser operations-puppet-validate $

Congratulations.

Modifying Jenkins jobs
Modifications are all about editing yaml files. You definitely want to read the documentation at http://ci.openstack.org/jenkins-job-builder/configuration.html. Also have a look at the existing files.

Your modifications should be sent to Gerrit for other people to validate them, so make sure to test them first using jenkins-jobs test (see below).

Refreshing Jenkins
To be able to update the configuration, you will need a username that is able to update jobs using the API and its API key. Wikimedia engineering should be able to use their labs credentials, else one could use jobbuilder-bot account. The configuration is done in jenkins_jobs.ini file:

[jenkins] user=jobbuilder-bot password=0123456789abcdef url=https://integration.mediawiki.org/ci/

Note: the labs instance is https://integration.wmflabs.org/ci/

Before updating the jobs, run the test command to make sure your .yaml files do not have typos: jenkins-jobs test config/ -o output/

Then update the Jenkins instance: $ jenkins-jobs --conf jenkins_jobs.ini update config/ INFO:root:Updating jobs in config/ (None) INFO:jenkins_jobs.builder:Reconfiguring jenkins job mediawiki-core-install-sqlite INFO:jenkins_jobs.builder:Reconfiguring jenkins job mediawiki-core-lint INFO:jenkins_jobs.builder:Reconfiguring jenkins job mediawiki-core-phpunit-api INFO:jenkins_jobs.builder:Reconfiguring jenkins job mediawiki-core-phpunit-databaseless INFO:jenkins_jobs.builder:Reconfiguring jenkins job mediawiki-core-phpunit-misc INFO:jenkins_jobs.builder:Reconfiguring jenkins job mediawiki-core-phpunit-parser INFO:jenkins_jobs.builder:Reconfiguring jenkins job operations-puppet-validate $

Ideally we would want to test the jobs in preproduction before deploying them on production.

notes:
 * Jenkins job builder maintains a cache of jobs and will not resubmit a job if it considers it already up to date. You will want to delete the file ~/.jenkins_jobs_cache.yml to force the update.
 * You can enable debugging output by passing -l debug