Tutorial

This tutorial goes over the steps of installing and configuring jenkins-autojobs.

Installing

The latest stable version of jenkins-autojobs can be installed from pypi using pip.

$ pip install jenkins-autojobs

Jenkins-autojobs depends on a version of lxml with support for XML canonicalization (c14n). Setup will attempt to install one if it is not present on your system. You might have to install the libxml and libxslt development headers if you haven’t already done so:

On a Debian compatible OS:

$ apt-get install libxml2-dev libxslt1-dev

On a Redhat compatible OS:

$ yum install libxml2-devel libxslt-devel

On Arch Linux or derivatives:

$ pacman -S libxslt libxml2

Usage

If jenkins-autojobs was installed succesfully, you’ll find that there are three new scripts on your system:

• jenkins-makejobs-git
• jenkins-makejobs-svn
• jenkins-makejobs-hg

All scripts accept the same command-line options and arguments and nearly the same configuration files.

Usage: jenkins-makejobs-* [-rvdtjnyoupUYOP] <config.yaml>

General Options:
  -n dry run
  -v show version and exit
  -d debug config inheritance
  -t debug http requests

Repository Options:
  -r <arg> repository url
  -y <arg> scm username
  -o <arg> scm password
  -Y scm username (read from stdin)
  -O scm password (read from stdin)

Jenkins Options:
  -j <arg> jenkins url
  -u <arg> jenkins username
  -p <arg> jenkins password
  -U jenkins username (read from stdin)
  -P jenkins password (read from stdin)

Template Jobs

Autojobs creates jobs from template jobs. Subsequent changes to the template jobs are propagated to all derived jobs (this behavior is configurable). A template job can be any regular Jenkins job. Depending on the SCM plugin you are using, you have to configure certain fields:

Git:

* Source Code Management:
  * Git:
    * Repository URL:   https://your.domain/your-project.git
    * Branch Specifier: master
    * Checkout/merge to local branch (under advanced): master

Subversion:

* Source Code Management:
  * Subversion:
    * Repository URL:   https://your.domain/your-project
    * Local module directory (optional): .

Mercurial:

* Source Code Management:
  * Mercurial:
    * Repository URL:   https://your.domain/your-project

One usage pattern is to have the job that builds your trunk/master branch be your template job.

Configuration

Please refer to the annotated example configuration files for a description of all options and their defaults:

• Git
• Mercurial
• Subversion

For a git-specific walkthrough, see the use cases page.

Case Study: Git

Repository

For the purposes of this tutorial we will create a git repository with a few empty branches.

$ git init /tmp/repo
$ cd /tmp/repo
$ git commit --allow-empty --allow-empty-message  -m ''
$ git checkout -b develop
$ git checkout -b feature/one
$ git checkout -b feature/two
$ git checkout -b release/one
$ git show-ref | awk '{print $2}'
refs/heads/master
refs/heads/develop
refs/heads/feature/one
refs/heads/feature/two
refs/heads/release/one

Template Jobs

We create two template jobs - one for all release branches (master, release/one) and one for development branches (develop, feature/{one,two}). You can configure them in any way you like, as long a Branch Specifier and the Checkout/merge to local branch fields are not empty. In our case the two template jobs will be imaginatively named ‘release’ and ‘develop’.

Job Name: release
* Source Code Management:
  * Git:
    * Repository URL:   file:///tmp/repo
    * Branch Specifier: master
    * Checkout/merge to local branch (under advanced): master

Job Name: develop
* Source Code Management:
  * Git:
    * Repository URL:   file:///tmp/repo
    * Branch Specifier: develop
    * Checkout/merge to local branch (under advanced): develop

Initial Config

@Todo