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. One of

    ~/.config/jenkins_jobs/jenkins_jobs.ini
    /etc/jenkins_jobs/jenkins_jobs.ini

or 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.
Instead of using your jenkins password, use an *API Token*. To retrieve your token go
to Jenkins via a Webbrowser, click on your Username in the right corner, click on configure,
click on *Show API Toke...*.

jenkins_jobs.ini:

    [jenkins]
    user=my_user_name
    password=my_api_token
    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:

Use 'key: |' to keep new lines in multiline values, e.g.:
  - shell: |
      echo hello
      echo world

See also:
* https://yaml-multiline.info/
* https://stackoverflow.com/a/21699210

- 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.

*Jenkins labels*

Most jenkins jobs should run a docker container and install all required
dependencies inside that, so we don't need to install them on the jenkins node.
These jobs don't need to set a label, they can just run on any generic jenkins
node that has docker available. So if you add a new job, you probably don't
need a label at all.

Existing jobs typically have a label set by the topic they belong to, e.g.:
- osmocom-master
- osmocom-gerrit
- ttcn3

Other labels indicate specific software/hardware works here, e.g.:
- coverity
- hdlc
- osmo-gsm-tester
- podman