jenkins-autojobs documentation Release 0.17.4

Georgi Valkov

February 16, 2017

Contents

1 Installing 3

2 Changes 5 2.1 Changelog...... 5 2.2 Tutorial...... 8 2.3 Case Study: ...... 18

3 Development 23 3.1 Testing...... 23 3.2 Todo...... 23

4 Similar Projects 25

5 License 27

i ii jenkins-autojobs documentation, Release 0.17.4

Jenkins-autojobs is a set of scripts that automatically create Jenkins jobs from template jobs and the branches in an SCM repository. Jenkins-autojobs supports Git, and Subversion. A routine run goes through the following steps: • Read settings from a configuration file. • List branches or refs from SCM. • Creates or updates jobs as configured. In its most basic form, the configuration file specifies: • How to access Jenkins and the SCM repository. • Which branches to process and which to ignore. • Which template job to use for which branches. • How new jobs should be named. Autojobs can also: • Add newly created jobs to Jenkins views. • Cleanup jobs for which a branch no longer exists. • Perform text substitutions on all text elements of a job’s config.xml. • Update jobs when their template job is updated. • Set the enabled/disabled state of new jobs. A new job can inherit the state of its template job, but an updated job can keep its most recent state. Please refer to the tutorial and the example output to get started. You may also have a look at the annotated git, svn and hg config files. Notice: The documentation is in the process of being completely rewritten. Things may seem incomplete and out of place.

Contents 1 jenkins-autojobs documentation, Release 0.17.4

2 Contents CHAPTER 1

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 compatible OS: $ apt-get install libxml2-dev libxslt1-dev

On a Redhat compatible OS: $ yum install libxml2-devel libxslt-devel

On or derivatives: $ pacman -S libxslt libxml2

3 jenkins-autojobs documentation, Release 0.17.4

4 Chapter 1. Installing CHAPTER 2

Changes

Changelog

0.17.4 (Mar 03, 2016)

• More robust handling of the project description element (see ‘issue 56‘_). • Added the verify-ssl, cert-bundle, and client-cert config-file options and the command-line switches to match them. These control the SSL certificate verification to the Jenkins server.

0.17.3 (Feb 10, 2016)

• Fix error-prone handling of the //project/description config.xml element (see issue #54).

0.17.2 (Jan 21, 2016)

• Actually change the default tag method to description. This was announced as the default behaviour in 0.17.0, but was accidentally omitted from that release (issue #50). Version 0.17.1 was skipped because of a failed upload to PyPi (see issue #74).

0.17.0 (Oct 19, 2015)

• Jenkins-autojobs will now use the job description field to store its metadata. Expect to see (created by jenkins-autojobs) and (jenkins-autojobs-tag: $tagname [...]) lines appended to the description of all managed jobs. This metadata was previously stored as elements in the job’s config.xml. Unfortunately, any manual re- configuration of the job would cause Jenkins to remove these extra elements. This issue is described in greater detail in issue #28. The old behavior can be kept by setting the tag-method option to element. • Added the cleanup-filters configuration option, which filters the list of jobs that jenkins-autojobs con- siders for cleanup by view name or regular expression (thanks @bartoszj). Example usage: # Cleanup only jobs in the 'Feature' and 'Release' views as well as all jobs that start with 'scratch'. cleanup-filters: views: -'Feature'

5 jenkins-autojobs documentation, Release 0.17.4

-'Release' jobs: -'^scratch-. *'

• Added the list-closed option to the mercurial plugin, which controls the listing of closed branches. The old behaviour and current default value is true. Note that this feature currently works only for local mercurial repositories.

0.16.2 (Oct 02, 2015)

• Fix accidentally introduced import error (thanks @bartoszj).

0.16.1 (Sep 30, 2015)

• Fix cleanup functionality and improve performance (thanks @bartoszj).

0.16.0 (Sep 23, 2015)

• Add the build-on-create option, which triggers a build when the job is created (thanks @bartoszj). • Ignore permission denied errors during job cleanup (thanks @bartoszj). • Fix issue with listing local mercurial branches (thanks ‘@Myz‘_).

0.15.1 (May 05, 2015)

• The repo and repo-orig keys are now available to the namefmt and substitute options. They hold the sanitized and raw value of the repo top-level config key.

0.15.0 (Feb 16, 2015)

• The * wildcard can now be used in the branches config key of jenkins-makejobs-svn. Example usage: file:///repo/projects/*/branches.

0.14.3 (Jan 02, 2015)

• Fix sticky state when template job is enabled (thanks @d-a-n and @sustmi).

0.14.2 (Nov 24, 2014)

• Fix reading of scm-username and scm-password from stdin (thanks @yamikuronue). • Fix user input on Python 3. • Fix typo that was preveneting jenkins-autojobs from working on Python 2.6 (thanks @aklemp).

6 Chapter 2. Changes jenkins-autojobs documentation, Release 0.17.4

0.14.1 (Nov 23, 2014)

• Ignore the ‘All’ view when adding jobs to views (thanks ‘@myz‘_). • View creation now respects the dryrun (-n) option (thanks @aklemp). • Fix reporting of view creation (thanks @aklemp). • Fix the httpdebug (-t) option on Python 3. The httpdebug option is now available in the config file.

0.14.0 (Oct 27, 2014)

• Learn the ability to add generated jobs to specific views. • Fix compatiblity with newer version of the Jenkins Mercurial plugin (thanks @ThomasMatern).

0.13.1 (May 29, 2014)

• Add the tag config option to the subversion script (thanks @mrook).

0.13.0 (Apr 08, 2014)

• Add the tag config option. • The cleanup option now accepts a tag name. • The substitute option now has access to matched groups (thanks @traviscosgrave). • The substitute and namefmt options can now refer to named capture groups. For example: refs: -'refs/heads/feature-(\d\d)-(?P\w+)-(\d)': namefmt:'wip-{name}-{3}'

The above ref config will map the branch feature-random-10 to job wip-random-10.

0.12.0 (Mar 09, 2014)

• Fix a bug that made jenkins-autojobs remove all managed jobs if list_branches() failed with cleanup on (thanks @sja). • Use jenkins-webapi 0.2.0.

0.11.0 (Feb 04, 2014)

• Add the cleanup config option (thanks @timmipetit). If set to true, jenkins-autojobs will remove all jobs for which a branch no longer exists. • Jenkins-autojobs now adds a createdByJenkinsAutojobs element to the config.xml of jobs that it creates.

2.1. Changelog 7 jenkins-autojobs documentation, Release 0.17.4

0.10.0 (Jan 08, 2014)

• Add the sanitize config option (thanks @xgouchet). You can now substitute characters or whole patterns with the sanitize option: sanitize: '@!?#&|\^_$%*':'_' # replace any of '@!?#&|\^_$%*' with '_' 're:colou?r':'color' # replace regex 'colou?r' with 'color'

The default is ’@!?#&|\^_$%*’: ’_’, which is the list of characters that are not allowed in job names.

0.9.1 (Jan 08, 2014)

• Command line flags -u|-p properly overwrite username and password config keys (thanks @timmipetit).

0.9.0 (Nov 27, 2013)

• Add support for Python 3.x. • Add the ‘python’ option to the mercurial yaml config. This sets the Python executable that will be used to call mercurial. This is useful when the default Python in PATH is not Python 2.x. • Use jenkins-webapi instead of python-jenkins.

0.6.0 (Sep 05, 2012)

• Add mercurial support.

0.5.0 (Aug 06, 2012)

Initial Release.

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

8 Chapter 2. Changes jenkins-autojobs documentation, Release 0.17.4

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]

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

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

Jenkins Options: -j jenkins url -u jenkins username -p 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:

2.2. Tutorial 9 jenkins-autojobs documentation, Release 0.17.4

* 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

#------# Jenkins location, login credentials and SSL config. jenkins:'https://jenkins.yourdomain.com' username:'change-me' password:'change-me'

# Verify the SSL certificate of the Jenkins server (default: true). verify-ssl: true # optional

# A client certificate can be specified as a single file, containing the # private key and certificate) or as 'path/to/client.cert:path/to/client.key'. client-cert:'path/to/client.cert' # optional

# Path to a CA_BUNDLE file or a directory with certificates of trusted CAs. cert-bundle:'path/to/certs/' # optional

#------# Git repository location. This can be a local filesystem directory or an url. # If location is local, 'git show-ref' is used. If it is an url, 'git ls-remote' # is used. Keep in mind that these commands return ref names differently, which # is relevant for setting the 'repo' configuration key. repo:'file:///tmp/project-repo/' # or /tmp/project-repo

#------# Repository login credentials. scm-username:'change-me' scm-password:'change-me'

#------# Job to use as a template for new jobs. template:'new-job-template'

#------# Character with which to replace '/' in ref names. namesep:'-'

#------

10 Chapter 2. Changes jenkins-autojobs documentation, Release 0.17.4

# Template string to use for new job names. Several placeholder variables as # well as regex capture groups and backreferences from the 'refs' match are # available. Given a ref 'refs/heads/feature/one/two.three' and a regex # 'refs/heads/feature/(.*)/(.*)', the following placeholders are available: # # {shortref} feature-one.two.three # {shortref-orig} feature/one/two.three # {ref} refs-heads-feature-one-two.three # {ref-orig} refs/heads/feature/one/two.three # {repo} sanitized value of 'repo' config key # {repo-orig} value of 'repo' config key # {0} one # {1} two.three # # # It’s also possible to refer to regex capture groups. Given the same ref # and a regex 'refs/heads/(?P(?:feature|release))/(.*)/(.*)', we we # can refer to following placeholders: # # {0} feature # {1} one # {2} two.three # {type} feature # # The default is '{shortref}'. namefmt:'{shortref}'

#------# If false, a job will never be overwritten if it exists. # If true, a job will be overwritten if the new configration differs from the # old one (the default). overwrite: true

#------# If true, new jobs will be added to the build queue after creation. build-on-create: false

#------# State of newly created or overwritten jobs. Default is 'sticky'. One of: # true -> Jobs will be enabled. # false -> Jobs will be disabled. # 'template' -> Jobs will inherit the state of their template job. # 'sticky' -> New jobs inherit the state of the template job - # overwritten jobs keep their most recent state. enable:'sticky'

#------# Makes text substitutions throughout all text elements of a job’s config.xml. # This includes the body of all commands that you may have defined. This option # is useful for plugins that cannot introspect the name of the branch or job # themselves (e.g. Sidebar-Link). All placeholders available to the namefmt # option are also available here. substitute: '@@JOB_NAME@@':'{branch}' '@@REF_NAME@@':'ref-{shortref}' '@@STORAGE@@':'/storage/builds/'

#------

2.2. Tutorial 11 jenkins-autojobs documentation, Release 0.17.4

# Substitutions to perform on the ref and shortref. # The default is '@!?#&|\^_$%*': '_', which substitutes the characters # that cannot be in a Jenkins job name with '_'. sanitize: '@!?#&|\^_$%*':'_' # replace any of @!?#&|\^_$%* with _ 're:colou?r':'color' # replace regex 'colou?r' with 'color'

#------# List of refs to ignore (regular expressions). ignore: -'refs/heads/feature/. *-nobuild' -'refs/heads/scratch/. *'

#------# A list of regular expressions that specify which refs to process. # Global settings can be overwritten on a per-ref basis. # Defaults to all refs ('refs: ".*"'). refs: -'refs/heads/release/(. *)' -'refs/heads/feature/(. *)' -'refs/heads/scratch/(. *)': 'template':'scratch-template' 'namefmt':'wip-{shortref}' 'enable': false 'view':'scratch-view' 'tag':'group-1'

# Although you can match any ref returned by 'git show-ref' or 'git ls-remote' # (depending on whether the repo is local or remote), only refs under # 'refs/heads' can be safely used for the branchspec field of the Jenkins Git # plugin. You can still use the substitute option for such setups.

#------# View to which new jobs should be added. Cannot be 'All'. view:'view-name'

#------# Tag jobs with this string. The tag will be placed inside the config.xml of # new or updated jobs under the 'createByJenkinsAutojobs/tag' element. tag:'throw-away-jobs'

#------# If set to true, jenkins-autojobs will remove jobs for branches that were # deleted. It uses a special property in the job’s config.xml to determine if # the job was created by jenkins-autojobs. # # If set to a tag name, only jobs with that name will be cleaned. This is # useful if you have more than one instance of jenkins-autojobs running and you # don’t want them to mutually cleanup each others jobs. cleanup: true # or 'throw-away-jobs'

#------# Limit the number of jobs to consider for cleanup by view or job name regex. # This can be used to reduce the time needed to remove jobs with the cleanup # feature. The default is to process all jobs. cleanup-filters: views:

12 Chapter 2. Changes jenkins-autojobs documentation, Release 0.17.4

-'My View' jobs: -'. *'

#------# Method for writing tags and marking the build as created by jenkins-autojobs. # 'description' -> add special strings to the job's description (default). # 'element' -> add new xml elements to the job's config.xml. tag-method:'description'

Download git-config.yaml

Mercurial

#------# Jenkins location, login credentials and SSL config. jenkins:'https://jenkins.yourdomain.com' username:'change-me' password:'change-me'

# Verify the SSL certificate of the Jenkins server (default: true). verify-ssl: true # optional

# A client certificate can be specified as a single file, containing the # private key and certificate) or as 'path/to/client.cert:path/to/client.key'. client-cert:'path/to/client.cert' # optional

# Path to a CA_BUNDLE file or a directory with certificates of trusted CAs. cert-bundle:'path/to/certs/' # optional

#------# Mercurial repository url. repo:'file:///tmp/repo/'

#------# The Python binary to use when calling mercurial. Defaults to 'python'. python:'python2'

#------# Process closed branches. Note that this works only for local repositories at # the moment. Defaults to 'true'. list-closed: true

#------# Repository login credentials. scm-username:'change-me' scm-password:'change-me'

#------# Job to use as a template for new jobs. template:'new-job-template'

#------# Character with which to replace '/' in branch names. namesep:'-' #------# Template string to use for new job names. Several placeholder variables as

2.2. Tutorial 13 jenkins-autojobs documentation, Release 0.17.4

# well as regex capture groups and backreferences from the 'refs' match are # available. Given a ref 'refs/heads/feature/one/two.three' and a regex # 'refs/heads/feature/(.*)/(.*)', the following placeholders are available: # # {branch} feature-one.two.three # {branch-orig} feature/one/two.three # {repo} sanitized value of 'repo' config key # {repo-orig} value of 'repo' config key # {0} one # {1} two.three # # # The default is '{branch}'. namefmt:'{branch}'

#------# Template string to use for new job names. Several placeholder variables as # well as regex capture groups and backreferences from the 'refs' match are # available. Given a ref 'refs/heads/feature/one/two.three' and a regex # 'refs/heads/feature/(.*)/(.*)', the following placeholders are available:

# Template string for new job names # The following placeholders are available: # Given a branch feature/one # {branch} -> expands to the name of the branch (feature-one) # {n} -> nth backreference of the branch regex namefmt:'{branch}'

#------# If false, a job will never be overwritten if it exists. # If true, a job will be overwritten if the new configration differs from the # old one (the default). overwrite: true

#------# If true, new jobs will be added to the build queue after creation. build-on-create: false

#------# State of newly created or overwritten jobs. Default is 'sticky'. One of: # true -> Jobs will be enabled. # false -> Jobs will be disabled. # 'template' -> Jobs will inherit the state of their template job. # 'sticky' -> New jobs inherit the state of the template job - # overwritten jobs keep their most recent state. enable:'sticky'

#------# Makes text substitutions throughout all text elements of a job’s config.xml. # This includes the body of all commands that you may have defined. This option # is useful for plugins that cannot introspect the name of the branch or job # themselves (e.g. Sidebar-Link). All placeholders available to the namefmt # option are also available here. substitute: '@@JOB_NAME@@':'{branch}' '@@REF_NAME@@':'ref-{shortref}' '@@STORAGE@@':'/storage/builds/'

14 Chapter 2. Changes jenkins-autojobs documentation, Release 0.17.4

#------# Substitutions to perform on the ref and shortref. # The default is '@!?#&|\^_$%*': '_', which substitutes the characters # that cannot be in a Jenkins job name with '_'. sanitize: '@!?#&|\^_$%*':'_' # replace any of @!?#&|\^_$%* with _ 're:colou?r':'color' # replace regex 'colou?r' with 'color'

#------# List of branches to ignore (regular expressions) ignore: -'. *-nobuild' -'scratch/. *'

#------# A list of regular expressions that specify which branches to process. # Global settings can be overwritten on a per-ref basis. # Defaults to all refs ('refs: ".*"'). refs: -'feature-(. *)' -'release-(. *)': 'template':'release-template' 'namefmt':'rel-{1}' 'enable': false 'view':'release-view' 'tag':'group-1'

#------# View to which new jobs should be added. Cannot be 'All'. view:'view-name'

#------# Tag jobs with this string. The tag will be placed inside the config.xml of # new or updated jobs under the 'createByJenkinsAutojobs/tag' element. tag:'throw-away-jobs'

#------# If set to true, jenkins-autojobs will remove jobs for branches that were # deleted. It uses a special property in the job’s config.xml to determine if # the job was created by jenkins-autojobs. # # If set to a tag name, only jobs with that name will be cleaned. This is # useful if you have more than one instance of jenkins-autojobs running and you # don’t want them to mutually cleanup each others jobs. cleanup: true # or 'throw-away-jobs'

#------# Limit the number of jobs to consider for cleanup by view or job name regex. # This can be used to reduce the time needed to remove jobs with the cleanup # feature. The default is to process all jobs. cleanup-filters: views: -'My View' jobs: -'. *'

#------

2.2. Tutorial 15 jenkins-autojobs documentation, Release 0.17.4

# Method for writing tags and marking the build as created by jenkins-autojobs. # 'description' -> add special strings to the job's description (default). # 'element' -> add new xml elements to the job's config.xml. tag-method:'description'

Download hg-config.yaml

Subversion

#------# Jenkins location, login credentials and SSL config. jenkins:'https://jenkins.yourdomain.com' username:'change-me' password:'change-me'

# Verify the SSL certificate of the Jenkins server (default: true). verify-ssl: true # optional

# A client certificate can be specified as a single file, containing the # private key and certificate) or as 'path/to/client.cert:path/to/client.key'. client-cert:'path/to/client.cert' # optional

# Path to a CA_BUNDLE file or a directory with certificates of trusted CAs. cert-bundle:'path/to/certs/' # optional

#------# Svn base url (not necessarily the repository root). repo:'file:///tmp/repo/'

#------# Urls to list for branches that will be matchable by the refs option. # Autojobs will 'svn ls' each of these and strip the value of 'repo'. branches: -'file:///tmp/repo/branches/' -'file:///tmp/repo/experimental/' -'file:///tmp/repo/releases/' -'file:///tmp/repo/projects/ */branches'

#------# Repository login credentials. scm-username:'change-me' scm-password:'change-me'

#------# Job to use as a template for new jobs. template:'new-job-template'

#------# Character with which to replace '/' in branch names. namesep:'-'

#------# Template string to use for new job names. Several placeholder variables as # well as regex capture groups and backreferences from the 'refs' match are # available. Given a branch 'branches/svn-bisect' and a regex # 'branches/(.*)-(.*)', the following placeholders will be available: #

16 Chapter 2. Changes jenkins-autojobs documentation, Release 0.17.4

# {path} branches-svn-bisect # {path-orig} branches/svn-bisect # {branch} svn-bisect # {repo} sanitized value of 'repo' config key # {repo-orig} value of 'repo' config key # {0} svn # {1} bisect # # The default is '{path}'. namefmt:'{path}'

#------# If false, a job will never be overwritten if it exists. # If true, a job will be overwritten if the new configration differs from the # old one (the default). overwrite: true

#------# If true, new jobs will be added to the build queue after creation. build-on-create: false

#------# State of newly created or overwritten jobs. Default is 'sticky'. One of: # true -> Jobs will be enabled. # false -> Jobs will be disabled. # 'template' -> Jobs will inherit the state of their template job. # 'sticky' -> New jobs inherit the state of the template job - # overwritten jobs keep their most recent state. enable:'sticky'

#------# Makes text substitutions throughout all text elements of a job’s config.xml. # This includes the body of all commands that you may have defined. This option # is useful for plugins that cannot introspect the name of the branch or job # themselves (e.g. Sidebar-Link). All placeholders available to the namefmt # option are also available here. substitute: '@@JOB_NAME@@':'{branch}' '@@REF_NAME@@':'ref-{shortref}' '@@STORAGE@@':'/storage/builds/'

#------# Substitutions to perform on the ref and shortref. # The default is '@!?#&|\^_$%*': '_', which substitutes the characters # that cannot be in a Jenkins job name with '_'. sanitize: '@!?#&|\^_$%*':'_' # replace any of @!?#&|\^_$%* with _ 're:colou?r':'color' # replace regex 'colou?r' with 'color'

#------# List of branches to ignore (regular expressions). ignore: -'branches/. *-nobuild' -'experimental/john/. *'

#------# A list of regular expressions that specify which refs to process.

2.2. Tutorial 17 jenkins-autojobs documentation, Release 0.17.4

# Global settings can be overwritten on a per-branch basis. # Defaults to all branches ('refs: ".*"'). refs: -'branches/(. *)' -'releases/(. *)': 'template':'release-template' 'namefmt':'release-{short}' 'enable': false 'view':'release-view' 'tag':'group-1'

#------# View to which new jobs should be added. Cannot be 'All'. view:'view-name'

#------# Tag jobs with this string. The tag will be placed inside the config.xml of # new or updated jobs under the 'createByJenkinsAutojobs/tag' element. tag:'throw-away-jobs'

#------# If set to true, jenkins-autojobs will remove jobs for branches that were # deleted. It uses a special property in the job’s config.xml to determine if # the job was created by jenkins-autojobs. # # If set to a tag name, only jobs with that name will be cleaned. This is # useful if you have more than one instance of jenkins-autojobs running and you # don’t want them to mutually cleanup each others jobs. cleanup: true # or 'throw-away-jobs'

#------# Limit the number of jobs to consider for cleanup by view or job name regex. # This can be used to reduce the time needed to remove jobs with the cleanup # feature. The default is to process all jobs. cleanup-filters: views: -'My View' jobs: -'. *'

#------# Method for writing tags and marking the build as created by jenkins-autojobs. # 'description' -> add special strings to the job's description (default). # 'element' -> add new xml elements to the job's config.xml. tag-method:'description'

Download svn-config.yaml 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.

18 Chapter 2. Changes jenkins-autojobs documentation, Release 0.17.4

$ git init /tmp/repo $ cd /tmp/repo $ git --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 Check- out/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 #------$ cat config.yaml jenkins: http://jenkins.yourdomain.com repo: https://github.com/mitsuhiko/flask.git template: flask-master namefmt: '{shortref}' overwrite: true enable: true ignore: - 'refs/heads/.*-maintenance' refs: - 'refs/heads/feature/.*' - 'refs/heads/new-.*'

2.3. Case Study: Git 19 jenkins-autojobs documentation, Release 0.17.4

#------# dryrun with config inheritance debugging $ jenkins-makejobs-git -nd config.yaml loading config from "/tmp/config.yaml" explicitly ignored: - refs/heads/0.3-maintenance - refs/heads/0.5-maintenance - refs/heads/0.6-maintenance - refs/heads/0.7-maintenance - refs/heads/0.8-maintenance processing ref: refs/heads/feature/remove-jsonp . job name: feature-remove-jsonp . job exists: False . job created . config: . re: refs/heads/feature/.* . enable: enable . namefmt:{shortref} . template: flask-master . namesep: - . overwrite: True processing ref: refs/heads/new-logging . job name: new-logging . job exists: False . job created . config: . re: refs/heads/new-.* . enable: enable . namefmt:{shortref} . template: flask-master . namesep: - . overwrite: True processing ref: refs/heads/new-modules . job name: new-modules . job exists: False . job created . config: . re: refs/heads/new-.* . enable: enable . namefmt:{shortref} . template: flask-master . namesep: - . overwrite: True processing ref: refs/heads/new-request-dispatching . job name: new-request-dispatching . job exists: False . job created . config: . re: refs/heads/new-.* . enable: enable . namefmt:{shortref} . template: flask-master . namesep: -

20 Chapter 2. Changes jenkins-autojobs documentation, Release 0.17.4

. overwrite: True

#------$ jenkins-makejobs-git config.yaml loading config from "/tmp/config.yaml" explicitly ignored: - refs/heads/0.3-maintenance - refs/heads/0.5-maintenance - refs/heads/0.6-maintenance - refs/heads/0.7-maintenance - refs/heads/0.8-maintenance processing ref: refs/heads/feature/remove-jsonp . job name: feature-remove-jsonp . job exists: False . job created processing ref: refs/heads/new-logging . job name: new-logging . job exists: False . job created processing ref: refs/heads/new-modules . job name: new-modules . job exists: False . job created processing ref: refs/heads/new-request-dispatching . job name: new-request-dispatching . job exists: False . job created

# after modifying the template job $ jenkins-makejobs-git config.yaml loading config from "/home/gvalkov/tmp/config.yaml" explicitly ignored: - refs/heads/0.3-maintenance - refs/heads/0.5-maintenance - refs/heads/0.6-maintenance - refs/heads/0.7-maintenance - refs/heads/0.8-maintenance processing ref: refs/heads/feature/remove-jsonp . job name: feature-remove-jsonp . job exists: True . job updated processing ref: refs/heads/new-logging . job name: new-logging . job exists: True . job updated processing ref: refs/heads/new-modules . job name: new-modules

2.3. Case Study: Git 21 jenkins-autojobs documentation, Release 0.17.4

. job exists: True . job updated processing ref: refs/heads/new-request-dispatching . job name: new-request-dispatching . job exists: True . job updated

#------# subsequent runs $ jenkins-makejobs-git config.yaml loading config from "/tmp/config.yaml" explicitly ignored: - refs/heads/0.3-maintenance - refs/heads/0.5-maintenance - refs/heads/0.6-maintenance - refs/heads/0.7-maintenance - refs/heads/0.8-maintenance processing ref: refs/heads/feature/remove-jsonp . job name: feature-remove-jsonp . job exists: True . job does not need to be reconfigured processing ref: refs/heads/new-logging . job name: new-logging . job exists: True . job does not need to be reconfigured processing ref: refs/heads/new-modules . job name: new-modules . job exists: True . job does not need to be reconfigured processing ref: refs/heads/new-request-dispatching . job name: new-request-dispatching . job exists: True . job does not need to be reconfigured

22 Chapter 2. Changes CHAPTER 3

Development

Testing

The jenkins-autojobs test suite needs a running Jenkins instance, pre-configured with the git, hg and svn plugins. To save you some of the trouble of doing that, there is an all-in-one script that will download jenkins.war, bundle all necessary plugins and start a local server on http://localhost:60888. $ cd jenkins-autojobs/tests

# start a jenkins server $ bin/start-jenkins.sh

# if you want to gracefully shutdown the jenkins instance, either # kill the start-jenkins.sh process or send a 0 to localhost:60887 # (60887 is the winstone control port) $ killall start-jenkins.sh $ echo0 | nc 127.0.0.1 60887

$ cd jenkins-autojobs

# make sure that the jenkins_autojobs package is available on # sys.path (python setup.py develop in a virtualenv)

# run all tests $ py.test tests

# run only git tests $ py.test tests/test_git.py

# run all tests for all supported versions of python $

Warning: The test suite removes all jobs on the Jenkins server prior to running any tests.

Todo

• The documentation still needs a lot of work.

23 jenkins-autojobs documentation, Release 0.17.4

24 Chapter 3. Development CHAPTER 4

Similar Projects

• jenkins-build-per-branch • jenkins-job-builder

25 jenkins-autojobs documentation, Release 0.17.4

26 Chapter 4. Similar Projects CHAPTER 5

License

Jenkins-autojobs is released under the terms of the Revised BSD License. All figures are derived from the Jenkins logo and are released under the CC BY-SA 3.0 license.

27