These jenkins.osmocom.org job definitions, managed by
https://docs.openstack.org/infra/jenkins-job-builder/index.html[Jenkins Job Builder]

*Prepare:*

Install jenkins-job-builder:

  apt-get install jenkins-job-builder

Have a jenkins-job-builder.ini file. Convenient is to place a system wide one,
if you're the only one using the system, at /etc/jenkins_jobs/jenkins_jobs.ini;
otherwise place one in here and pass it to jenkins-jobs using the --conf file.

Make sure the file not world readable to minimally safeguard your jenkins password.

jenkins_jobs.ini:

    [jenkins]
    user=my_user_name
    password=my_password
    url=https://jenkins.osmocom.org/jenkins

and

    chmod go-rwx jenkins_jobs.ini

*Update a single job on jenkins.osmocom.org:*

    jenkins-jobs --conf jenkins_jobs.ini update gerrit-verifications.yml gerrit-osmo-msc

NOTE: when you supply a name not defined in that yml file, you will not get an
error message, just nothing will happen.

*Update all jobs of one file:*

    jenkins-jobs --conf jenkins_jobs.ini update gerrit-verifications.yml

*Update all jobs in all files:*

    jenkins-jobs --conf jenkins_jobs.ini update ./

*Troubleshooting:*

- 'jenkins.JenkinsException: create[gerrit-osmo-msc] failed'

jenkins.osmocom.org is not reachable, or URL in the config file is erratic.
Make sure it is exactly

    url=https://jenkins.osmocom.org/jenkins

- newlines:

The build commands may be multiline, but especially in the
gerrit-verifications.yml, where the commands are first stored in 'cmd' and
later inserted in a 'shell' section, the newlines between individual shell
lines don't all survive. Interestingly enough, only a line that has more
indenting than the first line also receives an actual newline in the resulting
jenkins Execute Shell section; take a look at the job's config page on jenkins.
Hence we often have a '# keep first line with less indent' comment. Note that
issuing backslashes to span a shell command across several lines will break the
command if the newlines are not preserved, so we need a '# keep...' comment
where there are more than one shell command, and where there are backslashes
'\' to join multiple lines.

- jobs named on cmdline are not updated:

Make sure the job name is correct, or just issue an entire yml file without
individual job names.

Also be aware that jobs are only actually updated when anything changed.