.\" Man page generated from reStructuredText.
.
.TH "JENKINS-JOBS" "1" "December 22, 2014" "0.9.0" "Jenkins Job Builder"
.SH NAME
jenkins-jobs \- Jenkins Job Builder Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Jenkins Job Builder takes simple descriptions of \fI\%Jenkins\fP jobs in
\fI\%YAML\fP format, and uses them to configure Jenkins.  You can keep your
job descriptions in human readable text format in a version control
system to make changes and auditing easier.  It also has a flexible
template system, so creating many similarly configured jobs is easy.
.sp
Contents:
.SH INSTALLATION
.sp
To install Jenkins Job Builder, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo python setup.py install
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The OpenStack project uses Puppet to manage its infrastructure
systems, including Jenkins.  If you use Puppet, you can use the
\fI\%OpenStack Jenkins module\fP to install Jenkins Job Builder.
.SS Documentation
.sp
Documentation is included in the \fBdoc\fP folder. To generate docs
locally execute the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e doc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The generated documentation is then available under
\fBdoc/build/html/index.html\fP\&.
.SS Unit Tests
.sp
Unit tests have been included and are in the \fBtests\fP folder.  We recently
started including unit tests as examples in our documentation so to keep the
examples up to date it is very important that we include unit tests for
every module.  To run the unit tests, execute the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e py27
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Note: View \fBtox.ini\fP to run tests on other versions of Python.
.UNINDENT
.SS Test Coverage
.sp
To measure test coverage, execute the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tox \-e cover
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Configuration File
.sp
After installation, you will need to create a configuration file.  By
default, \fBjenkins\-jobs\fP looks in
\fB/etc/jenkins_jobs/jenkins_jobs.ini\fP but you may specify an
alternative location when running \fBjenkins\-jobs\fP\&.  The file should have
the following format:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[job_builder]
ignore_cache=True
keep_descriptions=False
include_path=.:scripts:~/git/
recursive=False

[jenkins]
user=jenkins
password=1234567890abcdef1234567890abcdef
url=https://jenkins.example.com
##### This is deprecated, use job_builder section instead
#ignore_cache=True

.ft P
.fi
.UNINDENT
.UNINDENT
.SS job_builder section
.INDENT 0.0
.TP
.B \fBignore_cache\fP
(Optional) If set to True, Jenkins Job Builder won\(aqt use any cache.
.TP
.B \fBkeep_descriptions\fP
By default \fIjenkins\-jobs\fP will overwrite the jobs descriptions even if no
description has been defined explicitly.
When this option is set to True, that behavior changes and it will only
overwrite the description if you specified it in the yaml. False by default.
.TP
.B \fBinclude_path\fP
(Optional) Can be set to a \(aq:\(aq delimited list of paths, which jenkins
job builder will search for any files specified by the custom application
yaml tags \(aqinclude\(aq, \(aqinclude\-raw\(aq and \(aqinclude\-raw\-escaped\(aq.
.TP
.B \fBrecursive\fP
(Optional) If set to True, jenkins job builder will search for job
definition files recursively
.UNINDENT
.SS jenkins section
.INDENT 0.0
.TP
.B \fBuser\fP
This should be the name of a user previously defined in Jenkins.
Appropriate user permissions must be set under the Jenkins security
matrix: under the \fBGlobal\fP group of permissions, check \fBRead\fP,
then under the \fBJob\fP group of permissions, check \fBCreate\fP,
\fBDelete\fP, \fBConfigure\fP and finally \fBRead\fP\&.
.TP
.B \fBpassword\fP
The API token for the user specified.  You can get this through the
Jenkins management interface under \fBPeople\fP \-> username \->
\fBConfigure\fP and then click the \fBShow API Token\fP button.
.TP
.B \fBurl\fP
The base URL for your Jenkins installation.
.UNINDENT
.SS Running
.sp
After it\(aqs installed and configured, you can invoke Jenkins Job
Builder by running \fBjenkins\-jobs\fP\&.  You won\(aqt be able to do anything
useful just yet without a configuration which is discussed in the next
section.
.SS Usage
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: jenkins\-jobs.py [\-h] [\-\-conf CONF] [\-l LOG_LEVEL] [\-\-ignore\-cache]
                       [\-\-flush\-cache]
                       {update,test,delete,delete\-all} ...

positional arguments:
  {update,test,delete,delete\-all}
                        update, test or delete job
    delete\-all          delete *ALL* jobs from Jenkins server, including those
                        not managed by Jenkins Job Builder.

optional arguments:
  \-h, \-\-help            show this help message and exit
  \-\-conf CONF           configuration file
  \-l LOG_LEVEL, \-\-log_level LOG_LEVEL
                        log level (default: info)
  \-\-ignore\-cache        ignore the cache and update the jobs anyhow (that will
                        only flush the specified jobs cache)
  \-\-flush\-cache         flush all the cache entries before updating
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Test Mode
.sp
Once you have a configuration defined, you can run the job builder in test mode.
.sp
If you want to run a simple test with just a single YAML job definition file
and see the XML output on stdout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
jenkins\-jobs test /path/to/foo.yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can also pass JJB a directory containing multiple job definition files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
jenkins\-jobs test /path/to/defs \-o /path/to/output
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which will write XML files to the output directory for all of the jobs
defined in the defs directory.
.SS Updating Jenkins
.sp
When you\(aqre satisfied with the generated XML from the test, you can run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
jenkins\-jobs update /path/to/defs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which will upload the job definitions to Jenkins if needed.  Jenkins Job
Builder maintains, for each host, a cache [1] of previously configured jobs,
so that you can run that command as often as you like, and it will only
update the jobs configurations in Jenkins if the defined definitions has
changed since the last time it was run.  Note: if you modify a job
directly in Jenkins, jenkins\-jobs will not know about it and will not
update it.
.sp
To update a specific list of jobs, simply pass them as additional
arguments after the job definition path. To update Foo1 and Foo2 run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
jenkins\-jobs update /path/to/defs Foo1 Foo2
.ft P
.fi
.UNINDENT
.UNINDENT
.SH FOOTNOTES
.IP [1] 5
The cache default location is at \fB~/.cache/jenkins_jobs\fP, which
can be overridden by setting the \fBXDG_CACHE_HOME\fP environment
variable.
.SH JOB DEFINITIONS
.sp
The job definitions for Jenkins Job Builder are kept in any number of
YAML files, in whatever way you would like to organize them.  When you
invoke \fBjenkins\-jobs\fP you may specify either the path of a single
YAML file, or a directory.  If you choose a directory, all of
the .yaml (or .yml) files in that directory will be read, and all the
jobs they define will be created or updated.
.SS Definitions
.sp
Jenkins Job Builder understands a few basic object types which are
described in the next sections.
.SS Job
.sp
The most straightforward way to create a job is simply to define a
Job in YAML.  It looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job:
    name: job\-name
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That\(aqs not very useful, so you\(aqll want to add some actions such as
\fIbuilders\fP, and perhaps \fIpublishers\fP\&.  Those are described
later.  There are a few basic optional fields for a Job definition:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job:
    name: job\-name
    project\-type: freestyle
    defaults: global
    disabled: false
    display\-name: \(aqFancy job name\(aq
    concurrent: true
    workspace: /srv/build\-area/job\-name
    child\-workspace: /srv/build\-area/job\-name
    quiet\-period: 5
    block\-downstream: false
    block\-upstream: false
    retry\-count: 3
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Job Parameters
.INDENT 7.0
.IP \(bu 2
\fBproject\-type\fP:
Defaults to "freestyle", but "maven" as well as "multijob" or "flow"
can also be specified.
.IP \(bu 2
\fBdefaults\fP:
Specifies a set of \fIdefaults\fP to use for this job, defaults to
\(aq\(aqglobal\(aq\(aq.  If you have values that are common to all of your jobs,
create a \fBglobal\fP \fIdefaults\fP object to hold them, and no further
configuration of individual jobs is necessary.  If some jobs
should not use the \fBglobal\fP defaults, use this field to specify a
different set of defaults.
.IP \(bu 2
\fBdisabled\fP:
Boolean value to set whether or not this job should be disabled in
Jenkins. Defaults to \fBfalse\fP (job will be enabled).
.IP \(bu 2
\fBdisplay\-name\fP:
Optional name shown for the project throughout the Jenkins web GUI in
place of the actual job name.  The jenkins_jobs tool cannot fully remove
this trait once it is set, so use caution when setting it.  Setting it to
the same string as the job\(aqs name is an effective un\-set workaround.
Alternately, the field can be cleared manually using the Jenkins web
interface.
.IP \(bu 2
\fBconcurrent\fP:
Boolean value to set whether or not Jenkins can run this job
concurrently. Defaults to \fBfalse\fP\&.
.IP \(bu 2
\fBworkspace\fP:
Path for a custom workspace. Defaults to Jenkins default
configuration.
.IP \(bu 2
\fBchild\-workspace\fP:
Path for a child custom workspace. Defaults to Jenkins default
configuration.
.IP \(bu 2
\fBquiet\-period\fP:
Number of seconds to wait between consecutive runs of this job.
Defaults to \fB0\fP\&.
.IP \(bu 2
\fBblock\-downstream\fP:
Boolean value to set whether or not this job must block while
downstream jobs are running. Downstream jobs are determined
transitively. Defaults to \fBfalse\fP\&.
.IP \(bu 2
\fBblock\-upstream\fP:
Boolean value to set whether or not this job must block while
upstream jobs are running. Upstream jobs are determined
transitively. Defaults to \fBfalse\fP\&.
.IP \(bu 2
\fBauth\-token\fP:
Specifies an authentication token that allows new builds to be
triggered by accessing a special predefined URL. Only those who
know the token will be able to trigger builds remotely.
.IP \(bu 2
\fBretry\-count\fP:
If a build fails to checkout from the repository, Jenkins will
retry the specified number of times before giving up.
.UNINDENT
.UNINDENT
.SS Job Template
.sp
If you need several jobs defined that are nearly identical, except
perhaps in their names, SCP targets, etc., then you may use a Job
Template to specify the particulars of the job, and then use a
\fI\%Project\fP to realize the job with appropriate variable substitution.
Any variables not specified at the project level will be inherited from
the \fI\%Defaults\fP\&.
.sp
A Job Template has the same syntax as a \fI\%Job\fP, but you may add
variables anywhere in the definition.  Variables are indicated by
enclosing them in braces, e.g., \fB{name}\fP will substitute the
variable \fIname\fP\&.  When using a variable in a string field, it is good
practice to wrap the entire string in quotes, even if the rules of
YAML syntax don\(aqt require it because the value of the variable may
require quotes after substitution. In the rare situation that you must
encode braces within literals inside a template (for example a shell
function definition in a builder), doubling the braces will prevent
them from being interpreted as a template variable.
.sp
You must include a variable in the \fBname\fP field of a Job Template
(otherwise, every instance would have the same name).  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job\-template:
    name: \(aq{name}\-unit\-tests\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Will not cause any job to be created in Jenkins, however, it will
define a template that you can use to create jobs with a \fI\%Project\fP
definition.  It\(aqs name will depend on what is supplied to the
\fI\%Project\fP\&.
.SS Project
.sp
The purpose of a project is to collect related jobs together, and
provide values for the variables in a \fI\%Job Template\fP\&.  It looks like
this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- project:
    name: project\-name
    jobs:
      \- \(aq{name}\-unit\-tests\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Any number of arbitrarily named additional fields may be specified,
and they will be available for variable substitution in the job
template.  Any job templates listed under \fBjobs:\fP will be realized
with those values.  The example above would create the job called
\(aqproject\-name\-unit\-tests\(aq in Jenkins.
.sp
The \fBjobs:\fP list can also allow for specifying job\-specific
substitutions as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- project:
    name: project\-name
    jobs:
      \- \(aq{name}\-unit\-tests\(aq:
          mail\-to: developer@nowhere.net
      \- \(aq{name}\-perf\-tests\(aq:
          mail\-to: projmanager@nowhere.net
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a variable is a list, the job template will be realized with the
variable set to each value in the list.  Multiple lists will lead to
the template being realized with the cartesian product of those
values.  Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- project:
    name: project\-name
    pyver:
      \- 26
      \- 27
    jobs:
      \- \(aq{name}\-{pyver}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If there are templates being realized that differ only in the variable
used for its name (thus not a use case for job\-specific substitutions),
additional variables can be specified for project variables. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job\-template:
    name: \(aq{name}\-{pyver}\(aq
    builders:
      \- shell: \(aqgit co {branch_name}\(aq

\- project:
   name: project\-name
   pyver:
    \- 26:
       branch_name: old_branch
    \- 27:
       branch_name: new_branch
   jobs:
    \- \(aq{name}\-{pyver}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Job Group
.sp
If you have several Job Templates that should all be realized
together, you can define a Job Group to collect them.  Simply use the
Job Group where you would normally use a \fI\%Job Template\fP and all of
the Job Templates in the Job Group will be realized.  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job\-template:
    name: \(aq{name}\-unit\-tests\(aq
    builders:
    \- shell: unittest
    publishers:
    \- email:
        recipients: \(aq{mail\-to}\(aq

\- job\-template:
    name: \(aq{name}\-perf\-tests\(aq
    builders:
    \- shell: perftest
    publishers:
    \- email:
        recipients: \(aq{mail\-to}\(aq

\- job\-group:
    name: \(aq{name}\-tests\(aq
    jobs:
    \- \(aq{name}\-unit\-tests\(aq:
        mail\-to: developer@nowhere.net
    \- \(aq{name}\-perf\-tests\(aq:
        mail\-to: projmanager@nowhere.net

\- project:
    name: project\-name
    jobs:
    \- \(aq{name}\-tests\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Would cause the jobs \fIproject\-name\-unit\-tests\fP and \fIproject\-name\-perf\-tests\fP to be created
in Jenkins.
.SS Macro
.sp
Many of the actions of a \fI\%Job\fP, such as builders or publishers, can
be defined as a Macro, and then that Macro used in the \fI\%Job\fP
description.  Builders are described later, but let\(aqs introduce a
simple one now to illustrate the Macro functionality.  This snippet
will instruct Jenkins to execute "make test" as part of the job:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job:
    name: foo\-test
    builders:
      \- shell: \(aqmake test\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you wanted to define a macro (which won\(aqt save much typing in this
case, but could still be useful to centralize the definition of a
commonly repeated task), the configuration would look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- builder:
    name: make\-test
    builders:
      \- shell: \(aqmake test\(aq

\- job:
    name: foo\-test
    builders:
      \- make\-test
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This allows you to create complex actions (and even sequences of
actions) in YAML that look like first\-class Jenkins Job Builder
actions.  Not every attribute supports Macros, check the documentation
for the action before you try to use a Macro for it.
.sp
Macros can take parameters, letting you define a generic macro and more
specific ones without having to duplicate code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# The \(aqadd\(aq macro takes a \(aqnumber\(aq parameter and will creates a
# job which prints \(aqAdding \(aq followed by the \(aqnumber\(aq parameter:
\- builder:
    name: add
    builders:
     \- shell: "echo Adding {number}"

# A specialized macro \(aqaddtwo\(aq reusing the \(aqadd\(aq macro but with
# a \(aqnumber\(aq parameter hardcoded to \(aqtwo\(aq:
\- builder:
    name: addtwo
    builders:
     \- add:
        number: "two"

# Glue to have Jenkins Job Builder to expand this YAML example:
\- job:
    name: "testingjob"
    builders:
     # The specialized macro:
     \- addtwo
     # Generic macro call with a parameter
     \- add:
        number: "ZERO"
     # Generic macro called without a parameter. Never do this!
     # See below for the resulting wrong output :(
     \- add
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then \fB<builders />\fP section of the generated job show up as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<builders>
  <hudson.tasks.Shell>
    <command>echo Adding two</command>
  </hudson.tasks.Shell>
  <hudson.tasks.Shell>
    <command>echo Adding ZERO</command>
  </hudson.tasks.Shell>
  <hudson.tasks.Shell>
    <command>echo Adding {number}</command>
  </hudson.tasks.Shell>
</builders>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As you can see, the specialized macro \fBaddtwo\fP reused the definition from
the generic macro \fBadd\fP\&.  Whenever you forget a parameter from a macro,
it will not be expanded and left as is, which will most probably cause havoc in
your Jenkins builds.
.SS Defaults
.sp
Defaults collect job attributes (including actions) and will supply
those values when the job is created, unless superseded by a value in
the \(aqJob\(aq_ definition.  If a set of Defaults is specified with the
name \fBglobal\fP, that will be used by all \fI\%Job\fP (and \fI\%Job Template\fP)
definitions unless they specify a different Default object with the
\fBdefaults\fP attribute.  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- defaults:
    name: global
    description: \(aqDo not edit this job through the web!\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Will set the job description for every job created.
.sp
You can define variables that will be realized in a \fIJob Template\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- defaults:
    name: global
    arch: \(aqi386\(aq

\- project:
    name: project\-name
    jobs:
        \- \(aqbuild\-{arch}\(aq
        \- \(aqbuild\-{arch}\(aq:
            arch: \(aqamd64\(aq

\- job\-template:
    name: \(aqbuild\-{arch}\(aq
    builders:
        \- shell: "echo Build arch {arch}."

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Would create jobs \fBbuild\-i386\fP and \fBbuild\-amd64\fP\&.
.SS Advanced
.sp
If you want to use lists or dicts variables you can use \fB{obj:key}\fP\&.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- project:
    name: test_custom_distri
    distributions: !!python/tuple [precise, jessie]
    architectures: !!python/tuple &architectures
      \- amd64
      \- i386
    axis_a:
        type: user\-defined
        name: architectures
        values: *architectures
    jobs:
      \- \(aq{name}\-source\(aq

\- job\-template:
      name: \(aq{name}\-source\(aq
      project\-type: matrix
      axes:
        \- axis:
            type: user\-defined
            name: distribution
            values: \(aq{obj:distributions}\(aq
        \- axis: \(aq{obj:axis_a}\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.SS Custom Yaml Tags
.sp
Custom application specific yamls tags are supported to provide
enhancements when reading yaml configuration.
.sp
These allow inclusion of arbitrary files as a method of having blocks of data
managed separately to the yaml job configurations. A specific usage of this is
inlining scripts contained in separate files, although such tags may also be
used to simplify usage of macros or job templates.
.sp
The tag \fB!include\fP will treat the following string as file which should be
parsed as yaml configuration data.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job:
    name: test\-job\-1
    builders:
      !include include001.yaml.inc

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
contents of include001.yaml.inc:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- timeout\-wrapper
\- pre\-scm\-shell\-ant
\- copy\-files

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The tag \fB!include\-raw\fP will treat the following file as a data blob, which
should be read into the calling yaml construct without any further parsing.
Any data in a file included through this tag, will be treated as string data.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job:
    name: test\-job\-include\-raw\-1
    builders:
      \- shell:
          !include\-raw include\-raw001\-hello\-world.sh
      \- shell:
          !include\-raw include\-raw001\-vars.sh

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
contents of include\-raw001\-hello\-world.sh:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!/bin/bash
#
# Sample script showing how the yaml include\-raw tag can be used
# to inline scripts that are maintained outside of the jenkins
# job yaml configuration.

echo "hello world"

exit 0

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
contents of include\-raw001\-vars.sh:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!/bin/bash
#
# sample script to check that brackets aren\(aqt escaped
# when using the include\-raw application yaml tag

VAR1="hello"
VAR2="world"
VAR3="${VAR1} ${VAR2}"

[[ \-n "${VAR3}" ]] && {
    # this next section is executed as one
    echo "${VAR3}"
    exit 0
}


.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The tag \fB!include\-raw\-escape\fP treats the given file as a data blob, which
should be escaped before being read in as string data. This allows
job\-templates to use this tag to include scripts from files without
needing to escape braces in the original file.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- template\-job:
    name: test\-job\-include\-raw\-{num}
    builders:
      \- shell:
          !include\-raw\-escape include\-raw001\-hello\-world.sh
      \- shell:
          !include\-raw\-escape include\-raw001\-vars.sh

\- project:
    name: test\-job\-template\-1
    num: 1
    jobs:
      \- \(aqtest\-job\-include\-raw\-{num}\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
contents of include\-raw001\-hello\-world.sh:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!/bin/bash
#
# Sample script showing how the yaml include\-raw tag can be used
# to inline scripts that are maintained outside of the jenkins
# job yaml configuration.

echo "hello world"

exit 0

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
contents of include\-raw001\-vars.sh:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!/bin/bash
#
# sample script to check that brackets aren\(aqt escaped
# when using the include\-raw application yaml tag

VAR1="hello"
VAR2="world"
VAR3="${VAR1} ${VAR2}"

[[ \-n "${VAR3}" ]] && {
    # this next section is executed as one
    echo "${VAR3}"
    exit 0
}


.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Modules
.sp
The bulk of the job definitions come from the following modules.
.SS Flow Project
.sp
The flow Project module handles creating Jenkins flow projects.
You may specify \fBflow\fP in the \fBproject\-type\fP attribute of
the \fIJob\fP definition.
.sp
Requires the Jenkins \fI\%Build Flow Plugin.\fP
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job:
  name: test_job
  project\-type: flow
  dsl: |
    build("job1")
    parallel (
      { build("job2a") },
      { build("job2b") }
    )
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Freestyle Project
.sp
The Freestyle Project module handles creating freestyle Jenkins
projects (i.e., those that do not use Maven).  You may specify
\fBfreestyle\fP in the \fBproject\-type\fP attribute to the \fIJob\fP
definition if you wish, though it is the default, so you may omit
\fBproject\-type\fP altogether if you are creating a freestyle project.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job:
  name: test_job
  project\-type: freestyle
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Maven Project
.sp
The Maven Project module handles creating Maven Jenkins projects.
.sp
To create a Maven project, specify \fBmaven\fP in the \fBproject\-type\fP
attribute to the \fIJob\fP definition. It also requires a \fBmaven\fP section
in the \fIJob\fP definition.
.INDENT 0.0
.TP
.B Job Parameters
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBroot\-module\fP:
.INDENT 7.0
.IP \(bu 2
\fBgroup\-id\fP (\fIstr\fP): GroupId.
.IP \(bu 2
\fBartifact\-id\fP (\fIstr\fP): ArtifactId.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fBroot\-pom\fP (\fIstr\fP): The path to the pom.xml file. (default \(aqpom.xml\(aq)
.IP \(bu 2
\fBgoals\fP (\fIstr\fP): Goals to execute. (required)
.IP \(bu 2
\fBmaven\-opts\fP (\fIstr\fP): Java options to pass to maven (aka MAVEN_OPTS)
.IP \(bu 2
\fBmaven\-name\fP (\fIstr\fP): Installation of maven which should be used.
Not setting \fBmaven\-name\fP appears to use the first maven install
defined in the global jenkins config.
.IP \(bu 2
\fBprivate\-repository\fP (\(aqstr\(aq): Whether to use a private maven repository
Possible values are \fIdefault\fP, \fIlocal\-to\-workspace\fP and
\fIlocal\-to\-executor\fP\&.
.IP \(bu 2
\fBignore\-upstream\-changes\fP (\fIbool\fP): Do not start a build whenever
a SNAPSHOT dependency is built or not. (default true)
.IP \(bu 2
\fBautomatic\-archiving\fP (\fIbool\fP): Activate automatic artifact archiving
(default true).
.IP \(bu 2
\fBsettings\fP (\fIstr\fP): Path to custom maven settings file (optional)
.IP \(bu 2
\fBglobal\-settings\fP (\fIstr\fP): Path to custom maven global settings file
(optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
project\-type: maven
maven:
  root\-pom: pom.xml
  goals: deploy
  root\-module:
    group\-id: gabba.gabba
    artifact\-id: hey
  settings: test
  global\-settings: test

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Matrix Project
.sp
The matrix project module handles creating Jenkins matrix
projects. To create a matrix project specify \fBmatrix\fP in the
\fBproject\-type\fP attribute to the \fIJob\fP definition.
Currently it only supports three axes which share the same
internal YAML structure:
.INDENT 0.0
.IP \(bu 2
label expressions (\fBlabel\-expression\fP)
.IP \(bu 2
user\-defined values (\fBuser\-defined\fP)
.IP \(bu 2
slave name or label (\fBslave\fP)
.UNINDENT
.sp
The module supports also dynamic axis:
.INDENT 0.0
.IP \(bu 2
dynamic (\fBdynamic\fP)
.UNINDENT
.sp
Requires the Jenkins \fI\%dynamic axis Plugin.\fP
.INDENT 0.0
.TP
.B Job Parameters
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBexecution\-strategy\fP (optional):
.INDENT 7.0
.IP \(bu 2
\fBcombination\-filter\fP (\fIstr\fP): axes selection filter
.IP \(bu 2
\fBsequential\fP (\fIbool\fP): run builds sequentially (default false)
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBtouchstone\fP (optional):
.INDENT 7.0
.IP \(bu 2
\fBexpr\fP (\fIstr\fP) \-\- selection filter for the touchstone build
.IP \(bu 2
\fBresult\fP (\fIstr\fP) \-\- required result of the job:             stable (default) or unstable
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBaxes\fP (\fIlist\fP):
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBaxis\fP:
.INDENT 7.0
.IP \(bu 2
\fBtype\fP (\fIstr\fP) \-\- axis type, must be either
\(aqlabel\-expression\(aq, \(aquser\-defined\(aq or \(aqslave\(aq.
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- name of the axis
.IP \(bu 2
\fBvalues\fP (\fIlist\fP) \-\- values of the axis
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job:
   name: matrix\-test
   project\-type: matrix
   execution\-strategy:
     combination\-filter: |
       !(os=="fedora11" && arch=="amd64")
     sequential: true
     touchstone:
       expr: \(aqos == "fedora11"\(aq
       result: unstable
   axes:
     \- axis:
        type: label\-expression
        name: os
        values:
         \- ubuntu12.04
         \- fedora11
     \- axis:
        type: label\-expression
        name: arch
        values:
         \- amd64
         \- i386
     \- axis:
        type: slave
        name: nodes
        values:
         \- node1
         \- node2
     \- axis:
        type: dynamic
        name: config
        values:
         \- config_list
   builders:
     \- shell: make && make check
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example using user\-defined axis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job:
   name: matrix\-user\-defined
   project\-type: matrix
   axes:
     \- axis:
       type: user\-defined
       name: database
       values:
        \- mysql
        \- postgresql
        \- sqlite
   builders:
    \- shell: make "$database"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Builders
.sp
Builders define actions that the Jenkins job should execute.  Examples
include shell scripts or maven targets.  The \fBbuilders\fP attribute in
the \fIJob\fP definition accepts a list of builders to invoke.  They
may be components defined below, locally defined macros (using the top
level definition of \fBbuilder:\fP, or locally defined components found
via the \fBjenkins_jobs.builders\fP entry point.
.INDENT 0.0
.TP
.B \fBComponent\fP: builders
.INDENT 7.0
.TP
.B Macro
builder
.TP
.B Entry Point
jenkins_jobs.builders
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job:
  name: test_job

  builders:
    \- shell: "make test"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ant
Execute an ant target.  Requires the Jenkins \fI\%Ant Plugin.\fP
.sp
To setup this builder you can either reference the list of targets
or use named parameters. Below is a description of both forms:
.sp
\fI1) Listing targets:\fP
.sp
After the ant directive, simply pass as argument a space separated list
of targets to build.
.INDENT 7.0
.TP
.B Parameter
space separated list of Ant targets
.UNINDENT
.sp
Example to call two Ant targets:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- ant: "target1 target2"

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The build file would be whatever the Jenkins Ant Plugin is set to use
per default (i.e build.xml in the workspace root).
.sp
\fI2) Using named parameters:\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBtargets\fP (\fIstr\fP) \-\- the space separated list of ANT targets.
.IP \(bu 2
\fBbuildfile\fP (\fIstr\fP) \-\- the path to the ANT build file.
.IP \(bu 2
\fBproperties\fP (\fIlist\fP) \-\- Passed to ant script using \-Dkey=value (optional)
.IP \(bu 2
\fBant\-name\fP (\fIstr\fP) \-\- the name of the ant installation,
(default \(aqdefault\(aq) (optional)
.IP \(bu 2
\fBjava\-opts\fP (\fIstr\fP) \-\- java options for ant, can have multiples,
must be in quotes (optional)
.UNINDENT
.UNINDENT
.sp
Example specifying the build file too and several targets:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- ant:
     targets: "debug test install"
     buildfile: "build.xml"
     properties:
        builddir: "/tmp/"
        failonerror: true
     java\-opts:
        \- "\-ea"
        \- "\-Xmx512m"
     ant\-name: "Standard Ant"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B artifact\-resolver
Allows one to resolve artifacts from a maven repository like nexus
(without having maven installed)
Requires the Jenkins \fI\%Repository Connector Plugin\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBfail\-on\-error\fP (\fIbool\fP) \-\- Whether to fail the build on error (default false)
.IP \(bu 2
\fBrepository\-logging\fP (\fIbool\fP) \-\- Enable repository logging (default false)
.IP \(bu 2
\fBtarget\-directory\fP (\fIstr\fP) \-\- Where to resolve artifacts to
.IP \(bu 2
\fBartifacts\fP (\fIlist\fP) \-\- 
.sp
list of artifacts to resolve
.INDENT 2.0
.TP
.B Artifact
.INDENT 7.0
.IP \(bu 2
\fBgroup\-id\fP (\fIstr\fP) \-\- Group ID of the artifact
.IP \(bu 2
\fBartifact\-id\fP (\fIstr\fP) \-\- Artifact ID of the artifact
.IP \(bu 2
\fBversion\fP (\fIstr\fP) \-\- Version of the artifact
.IP \(bu 2
\fBclassifier\fP (\fIstr\fP) \-\- Classifier of the artifact
(default \(aq\(aq)
.IP \(bu 2
\fBextension\fP (\fIstr\fP) \-\- Extension of the artifact
(default \(aqjar\(aq)
.IP \(bu 2
\fBtarget\-file\-name\fP (\fIstr\fP) \-\- What to name the artifact
(default \(aq\(aq)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- artifact\-resolver:
      fail\-on\-error: true
      repository\-logging: true
      target\-directory: foo
      artifacts:
        \- group\-id: commons\-logging
          artifact\-id: commons\-logging
          version: "1.1"
          classifier: src
          extension: jar
          target\-file\-name: comm\-log.jar
        \- group\-id: commons\-lang
          artifact\-id: commons\-lang
          version: "1.2"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B batch
Execute a batch command.
.INDENT 7.0
.TP
.B Parameter
the batch command to execute
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- batch: "foo/foo.bat"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B builders\-from
Use builders from another project.
Requires the Jenkins \fI\%Template Project Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBprojectName\fP (\fIstr\fP) \-\- the name of the other project
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- builders\-from: "base\-build"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B change\-assembly\-version
Change the assembly version.
Requires the Jenkins \fI\%Change Assembly Version.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBversion\fP (\fIstr\fP) \-\- Set the new version number for replace (default 1.0.0)
.IP \(bu 2
\fBassemblyFile\fP (\fIstr\fP) \-\- The file name to search (default AssemblyInfo.cs)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- change\-assembly\-version:
        version: "1.2.3"
        assembly\-file: "AFile"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B conditional\-step
Conditionally execute some build steps.  Requires the Jenkins \fI\%Conditional
BuildStep Plugin\fP\&.
.sp
Depending on the number of declared steps, a \fIConditional step (single)\fP
or a \fIConditional steps (multiple)\fP is created in Jenkins.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBcondition\-kind\fP (\fIstr\fP) \-\- Condition kind that must be verified before the
steps are executed. Valid values and their additional attributes are
described in the \fI\%conditions\fP table.
.IP \(bu 2
\fBon\-evaluation\-failure\fP (\fIstr\fP) \-\- What should be the outcome of the build
if the evaluation of the condition fails. Possible values are \fIfail\fP,
\fImark\-unstable\fP, \fIrun\-and\-mark\-unstable\fP, \fIrun\fP and \fIdont\-run\fP\&.
Default is \fIfail\fP\&.
.IP \(bu 2
\fBsteps\fP (\fIlist\fP) \-\- List of steps to run if the condition is verified. Items
in the list can be any builder known by Jenkins Job Builder.
.UNINDENT
.UNINDENT
.TS
center;
|l|l|.
_
T{
Condition kind
T}	T{
Description
T}
_
T{
always
T}	T{
Condition is always verified
T}
_
T{
never
T}	T{
Condition is never verified
T}
_
T{
boolean\-expression
T}	T{
Run the step if the expression expends to a
representation of true
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B condition\-expression
Expression to expand
.UNINDENT
.UNINDENT
.UNINDENT
T}
_
T{
current\-status
T}	T{
Run the build step if the current build status is
within the configured range
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B condition\-worst
Accepted values are SUCCESS,
UNSTABLE, FAILURE, NOT_BUILD, ABORTED
.TP
.B condition\-best
Accepted values are SUCCESS,
UNSTABLE, FAILURE, NOT_BUILD, ABORTED
.UNINDENT
.UNINDENT
.UNINDENT
T}
_
T{
shell
T}	T{
Run the step if the shell command succeed
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B condition\-command
Shell command to execute
.UNINDENT
.UNINDENT
.UNINDENT
T}
_
T{
windows\-shell
T}	T{
Similar to shell, except that commands will be
executed by cmd, under Windows
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B condition\-command
Command to execute
.UNINDENT
.UNINDENT
.UNINDENT
T}
_
T{
file\-exists
T}	T{
Run the step if a file exists
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B condition\-filename
Check existence of this file
.TP
.B condition\-basedir
If condition\-filename is
relative, it will be considered relative to
either \fIworkspace\fP, \fIartifact\-directory\fP,
or \fIjenkins\-home\fP\&. Default is \fIworkspace\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
T}
_
.TE
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
      \- conditional\-step:
          condition\-kind: current\-status
          condition\-worst: SUCCESS
          condition\-best: FAILURE
          steps:
              \- shell: "sl"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B copyartifact
Copy artifact from another project.  Requires the Jenkins \fI\%Copy Artifact
plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBproject\fP (\fIstr\fP) \-\- Project to copy from
.IP \(bu 2
\fBfilter\fP (\fIstr\fP) \-\- what files to copy
.IP \(bu 2
\fBtarget\fP (\fIstr\fP) \-\- Target base directory for copy, blank means use workspace
.IP \(bu 2
\fBflatten\fP (\fIbool\fP) \-\- Flatten directories (default: false)
.IP \(bu 2
\fBoptional\fP (\fIbool\fP) \-\- If the artifact is missing (for any reason) and
optional is true, the build won\(aqt fail because of this builder
(default: false)
.IP \(bu 2
\fBwhich\-build\fP (\fIstr\fP) \-\- which build to get artifacts from
(optional, default last\-successful)
.IP \(bu 2
\fBbuild\-number\fP (\fIstr\fP) \-\- specifies the build number to get when
when specific\-build is specified as which\-build
.IP \(bu 2
\fBpermalink\fP (\fIstr\fP) \-\- specifies the permalink to get when
permalink is specified as which\-build
.IP \(bu 2
\fBstable\fP (\fIbool\fP) \-\- specifies to get only last stable build when
last\-successful is specified as which\-build
.IP \(bu 2
\fBfallback\-to\-last\-successful\fP (\fIbool\fP) \-\- specifies to fallback to
last successful build when upstream\-build is specified as which\-build
.IP \(bu 2
\fBparam\fP (\fIstring\fP) \-\- specifies to use a build parameter to get the build when
build\-param is specified as which\-build
.IP \(bu 2
\fBparameter\-filters\fP (\fIstring\fP) \-\- Filter matching jobs based on these
parameters (optional)
.UNINDENT
.TP
.B Which\-build values
.INDENT 7.0
.IP \(bu 2
\fBlast\-successful\fP
.IP \(bu 2
\fBspecific\-build\fP
.IP \(bu 2
\fBlast\-saved\fP
.IP \(bu 2
\fBupstream\-build\fP
.IP \(bu 2
\fBpermalink\fP
.IP \(bu 2
\fBworkspace\-latest\fP
.IP \(bu 2
\fBbuild\-param\fP
.UNINDENT
.TP
.B Permalink values
.INDENT 7.0
.IP \(bu 2
\fBlast\fP
.IP \(bu 2
\fBlast\-stable\fP
.IP \(bu 2
\fBlast\-successful\fP
.IP \(bu 2
\fBlast\-failed\fP
.IP \(bu 2
\fBlast\-unstable\fP
.IP \(bu 2
\fBlast\-unsuccessful\fP
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- copyartifact:
      project: foo
      filter: "*.tar.gz"
      target: /home/foo
      which\-build: specific\-build
      build\-number: "123"
      optional: true
      flatten: true
      parameter\-filters: PUBLISH=true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B critical\-block\-end
Designate the end of a critical block. Must be used in conjuction with
critical\-block\-start.
.sp
Must also add a build wrapper (exclusion), specifying the resources that
control the critical block. Otherwise, this will have no effect.
.sp
Requires Jenkins \fI\%Exclusion Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- exclusion:
      resources:
        myresource1
builders:
  \- critical\-block\-start
  \- ... other builders
  \- critical\-block\-end
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B critical\-block\-start
Designate the start of a critical block. Must be used in conjuction with
critical\-block\-end.
.sp
Must also add a build wrapper (exclusion), specifying the resources that
control the critical block. Otherwise, this will have no effect.
.sp
Requires Jenkins \fI\%Exclusion Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- exclusion:
      resources:
        myresource1
builders:
  \- critical\-block\-start
  \- ... other builders
  \- critical\-block\-end
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B gradle
Execute gradle tasks.  Requires the Jenkins \fI\%Gradle Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBtasks\fP (\fIstr\fP) \-\- List of tasks to execute
.IP \(bu 2
\fBgradle\-name\fP (\fIstr\fP) \-\- Use a custom gradle name (optional)
.IP \(bu 2
\fBwrapper\fP (\fIbool\fP) \-\- use gradle wrapper (default false)
.IP \(bu 2
\fBexecutable\fP (\fIbool\fP) \-\- make gradlew executable (default false)
.IP \(bu 2
\fBswitches\fP (\fIlist\fP) \-\- Switches for gradle, can have multiples
.IP \(bu 2
\fBuse\-root\-dir\fP (\fIbool\fP) \-\- Whether to run the gradle script from the
top level directory or from a different location (default false)
.IP \(bu 2
\fBroot\-build\-script\-dir\fP (\fIstr\fP) \-\- If your workspace has the
top\-level build.gradle in somewhere other than the module
root directory, specify the path (relative to the module
root) here, such as ${workspace}/parent/ instead of just
${workspace}.
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- gradle:
      gradle\-name: "gradle\-1.2"
      wrapper: true
      executable: true
      use\-root\-dir: true
      root\-build\-script\-dir: ${workspace}/tests
      switches:
        \- "\-g /foo/bar/.gradle"
        \- "\-PmavenUserName=foobar"
      tasks: |
             init
             build
             tests

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B grails
Execute a grails build step. Requires the \fI\%Jenkins Grails Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBuse\-wrapper\fP (\fIbool\fP) \-\- Use a grails wrapper (default false)
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- Select a grails installation to use (optional)
.IP \(bu 2
\fBforce\-upgrade\fP (\fIbool\fP) \-\- Run \(aqgrails upgrade \-\-non\-interactive\(aq
first (default false)
.IP \(bu 2
\fBnon\-interactive\fP (\fIbool\fP) \-\- append \-\-non\-interactive to all build targets
(default false)
.IP \(bu 2
\fBtargets\fP (\fIstr\fP) \-\- Specify target(s) to run separated by spaces
.IP \(bu 2
\fBserver\-port\fP (\fIstr\fP) \-\- Specify a value for the server.port system
property (optional)
.IP \(bu 2
\fBwork\-dir\fP (\fIstr\fP) \-\- Specify a value for the grails.work.dir system
property (optional)
.IP \(bu 2
\fBproject\-dir\fP (\fIstr\fP) \-\- Specify a value for the grails.project.work.dir
system property (optional)
.IP \(bu 2
\fBbase\-dir\fP (\fIstr\fP) \-\- Specify a path to the root of the Grails
project (optional)
.IP \(bu 2
\fBproperties\fP (\fIstr\fP) \-\- Additional system properties to set (optional)
.IP \(bu 2
\fBplain\-output\fP (\fIbool\fP) \-\- append \-\-plain\-output to all build targets
(default false)
.IP \(bu 2
\fBstack\-trace\fP (\fIbool\fP) \-\- append \-\-stack\-trace to all build targets
(default false)
.IP \(bu 2
\fBverbose\fP (\fIbool\fP) \-\- append \-\-verbose to all build targets
(default false)
.IP \(bu 2
\fBrefresh\-dependencies\fP (\fIbool\fP) \-\- append \-\-refresh\-dependencies to all
build targets (default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- grails:
      use\-wrapper: "true"
      name: "grails\-2.2.2"
      force\-upgrade: "true"
      non\-interactive: "true"
      targets: "war ear"
      server\-port: "8003"
      work\-dir: "./grails\-work"
      project\-dir: "./project\-work"
      base\-dir: "./grails/project"
      properties: "program.name=foo"
      plain\-output: "true"
      stack\-trace: "true"
      verbose: "true"
      refresh\-dependencies: "true"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B groovy
Execute a groovy script or command.
Requires the Jenkins \fI\%Groovy Plugin\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBfile\fP (\fIstr\fP) \-\- Groovy file to run.
(Alternative: you can chose a command instead)
.IP \(bu 2
\fBcommand\fP (\fIstr\fP) \-\- Groovy command to run.
(Alternative: you can chose a script file instead)
.IP \(bu 2
\fBversion\fP (\fIstr\fP) \-\- Groovy version to use. (default \(aq(Default)\(aq)
.IP \(bu 2
\fBparameters\fP (\fIstr\fP) \-\- Parameters for the Groovy executable. (optional)
.IP \(bu 2
\fBscript\-parameters\fP (\fIstr\fP) \-\- These parameters will be passed to the script.
(optional)
.IP \(bu 2
\fBproperties\fP (\fIstr\fP) \-\- Instead of passing properties using the \-D parameter
you can define them here. (optional)
.IP \(bu 2
\fBjava\-opts\fP (\fIstr\fP) \-\- Direct access to JAVA_OPTS. Properties allows only
\-D properties, while sometimes also other properties like \-XX need to
be setup. It can be done here. This line is appended at the end of
JAVA_OPTS string. (optional)
.IP \(bu 2
\fBclass\-path\fP (\fIstr\fP) \-\- Specify script classpath here. Each line is one
class path item. (optional)
.UNINDENT
.UNINDENT
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- groovy:
      file: "test.groovy"

.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- groovy:
      command: "Some command"
      version: "Groovy 1.2"
      parameters: "parameters"
      script\-parameters: "script parameters"
      properties: "properties"
      java\-opts: "java opts"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B inject
Inject an environment for the job.
Requires the Jenkins \fI\%EnvInject Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBproperties\-file\fP (\fIstr\fP) \-\- the name of the property file (optional)
.IP \(bu 2
\fBproperties\-content\fP (\fIstr\fP) \-\- the properties content (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- inject:
      properties\-file: example.prop
      properties\-content: EXAMPLE=foo\-bar

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B managed\-script
This step allows to reference and execute a centrally managed
script within your build. Requires the Jenkins \fI\%Managed Script Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBscript\-id\fP (\fIstr\fP) \-\- Id of script to execute (Required)
.IP \(bu 2
\fBtype\fP (\fIstr\fP) \-\- 
.sp
Type of managed file (default: script)
.INDENT 2.0
.TP
.B type values
.INDENT 7.0
.IP \(bu 2
\fBbatch\fP: Execute managed windows batch
.IP \(bu 2
\fBscript\fP: Execute managed script
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBargs\fP (\fIlist\fP) \-\- Arguments to be passed to referenced script
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- managed\-script:
      script\-id: org.jenkinsci.plugins.managedscripts.ScriptConfig1401886156431
      type: script
      args:
        \- arg1
        \- arg2

.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- managed\-script:
      script\-id: org.jenkinsci.plugins.managedscripts.WinBatchConfig1402391729132
      type: batch
      args:
        \- arg1
        \- arg2

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B maven\-target
Execute top\-level Maven targets
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBgoals\fP (\fIstr\fP) \-\- Goals to execute
.IP \(bu 2
\fBproperties\fP (\fIstr\fP) \-\- Properties for maven, can have multiples
.IP \(bu 2
\fBpom\fP (\fIstr\fP) \-\- Location of pom.xml (default \(aqpom.xml\(aq)
.IP \(bu 2
\fBprivate\-repository\fP (\fIbool\fP) \-\- Use private maven repository for this
job (default false)
.IP \(bu 2
\fBmaven\-version\fP (\fIstr\fP) \-\- Installation of maven which should be used
(optional)
.IP \(bu 2
\fBjava\-opts\fP (\fIstr\fP) \-\- java options for maven, can have multiples,
must be in quotes (optional)
.IP \(bu 2
\fBsettings\fP (\fIstr\fP) \-\- Path to use as user settings.xml (optional)
.IP \(bu 2
\fBglobal\-settings\fP (\fIstr\fP) \-\- Path to use as global settings.xml (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
        \- maven\-target:
            maven\-version: Maven3
            pom: parent/pom.xml
            goals: clean
            private\-repository: true
            properties:
              \- foo=bar
              \- bar=foo
            java\-opts:
              \- "\-Xms512m \-Xmx1024m"
              \- "\-XX:PermSize=128m \-XX:MaxPermSize=256m"
            settings: mvn/settings.xml              
            global\-settings: mvn/globalsettings.xml
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B msbuild
Build .NET project using msbuild.  Requires the \fI\%Jenkins MSBuild Plugin\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBmsbuild\-version\fP (\fIstr\fP) \-\- which msbuild configured in Jenkins to use
(optional)
.IP \(bu 2
\fBsolution\-file\fP (\fIstr\fP) \-\- location of the solution file to build
.IP \(bu 2
\fBextra\-parameters\fP (\fIstr\fP) \-\- extra parameters to pass to msbuild (optional)
.IP \(bu 2
\fBpass\-build\-variables\fP (\fIbool\fP) \-\- should build variables be passed
to msbuild (default true)
.IP \(bu 2
\fBcontinue\-on\-build\-failure\fP (\fIbool\fP) \-\- should the build continue if
msbuild returns an error (default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- msbuild:
      solution\-file: "MySolution.sln"
      msbuild\-version: "msbuild\-4.0"
      extra\-parameters: "/maxcpucount:4"
      pass\-build\-variables: False
      continue\-on\-build\-failure: True

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B multijob
Define a multijob phase. Requires the Jenkins \fI\%Multijob Plugin.\fP
.sp
This builder may only be used in     \fBjenkins_jobs.modules.project_multijob.MultiJob\fP projects.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- MultiJob phase name
.IP \(bu 2
\fBcondition\fP (\fIstr\fP) \-\- when to trigger the other job (default \(aqSUCCESSFUL\(aq)
.IP \(bu 2
\fBprojects\fP (\fIlist\fP) \-\- 
.sp
list of projects to include in the MultiJob phase
.INDENT 2.0
.TP
.B Project
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- Project name
.IP \(bu 2
\fBcurrent\-parameters\fP (\fIbool\fP) \-\- Pass current build
parameters to the other job (default false)
.IP \(bu 2
\fBnode\-label\-name\fP (\fIstr\fP) \-\- Define a list of nodes
on which the job should be allowed to be executed on.
Requires NodeLabel Parameter Plugin (optional)
.IP \(bu 2
\fBnode\-label\fP (\fIstr\fP) \-\- Define a label
of \(aqRestrict where this project can be run\(aq on the fly.
Requires NodeLabel Parameter Plugin (optional)
.IP \(bu 2
\fBgit\-revision\fP (\fIbool\fP) \-\- Pass current git\-revision
to the other job (default false)
.IP \(bu 2
\fBproperty\-file\fP (\fIstr\fP) \-\- Pass properties from file
to the other job (optional)
.IP \(bu 2
\fBpredefined\-parameters\fP (\fIstr\fP) \-\- Pass predefined
parameters to the other job (optional)
.IP \(bu 2
\fBkill\-phase\-on\fP (\fIstr\fP) \-\- Stop the phase execution
on specific job status. Can be \(aqFAILURE\(aq, \(aqUNSTABLE\(aq,
\(aqNEVER\(aq. (optional)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- multijob:
      name: PhaseOne
      condition: SUCCESSFUL
      projects:
        \- name: PhaseOneJobA
          current\-parameters: true
          node\-label\-name: "vm_name"
          node\-label: "agent\-${BUILD_NUMBER}"
          git\-revision: true
        \- name: PhaseOneJobB
          current\-parameters: true
          property\-file: build.props
  \- multijob:
      name: PhaseTwo
      condition: UNSTABLE
      projects:
        \- name: PhaseTwoJobA
          current\-parameters: true
          predefined\-parameters: foo=bar
        \- name: PhaseTwoJobB
          current\-parameters: false
          kill\-phase\-on: UNSTABLE

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B powershell
Execute a powershell command. Requires the \fI\%Powershell Plugin\fP\&.
.INDENT 7.0
.TP
.B Parameter
the powershell command to execute
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- powershell: "foo/foo.ps1"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B python
Execute a python command. Requires the Jenkins \fI\%Python plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBparameter\fP (\fIstr\fP) \-\- the python command to execute
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- python: \(aqimport foobar\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B sbt
Execute a sbt build step. Requires the Jenkins \fI\%Sbt Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- Select a sbt installation to use. If no name is
provided, the first in the list of defined SBT
builders will be used. (default to first in list)
.IP \(bu 2
\fBjvm\-flags\fP (\fIstr\fP) \-\- Parameters to pass to the JVM (default \(aq\(aq)
.IP \(bu 2
\fBactions\fP (\fIstr\fP) \-\- Select the sbt tasks to execute (default \(aq\(aq)
.IP \(bu 2
\fBsbt\-flags\fP (\fIstr\fP) \-\- Add flags to SBT launcher
(default \(aq\-Dsbt.log.noformat=true\(aq)
.IP \(bu 2
\fBsubdir\-path\fP (\fIstr\fP) \-\- Path relative to workspace to run sbt in (default \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- sbt:
      name: "default"
      actions: "clean package"
      jvm\-flags: "\-Xmx8G"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B shell
Execute a shell command.
.INDENT 7.0
.TP
.B Parameters
\fBparameter\fP (\fIstr\fP) \-\- the shell command to execute
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- shell: "make test"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B shining\-panda
Execute a command inside various python environments. Requires the Jenkins
\fI\%ShiningPanda plugin\fP\&.
.INDENT 7.0
.TP
.B Parameters
\fBbuild\-environment\fP (\fIstr\fP) \-\- 
.sp
Building environment to set up (Required).
.INDENT 7.0
.TP
.B build\-environment values
.INDENT 7.0
.IP \(bu 2
\fBpython\fP: Use a python installation configured in Jenkins.
.IP \(bu 2
\fBcustom\fP: Use a manually installed python.
.IP \(bu 2
\fBvirtualenv\fP: Create a virtualenv
.UNINDENT
.UNINDENT

.UNINDENT
.sp
For the \fBpython\fP environment
.INDENT 7.0
.TP
.B Parameters
\fBpython\-version\fP (\fIstr\fP) \-\- Name of the python installation to use.
Must match one of the configured installations on server         configuration
(default: System\-CPython\-2.7)
.UNINDENT
.sp
For the \fBcustom\fP environment:
.INDENT 7.0
.TP
.B Parameters
\fBhome\fP (\fIstr\fP) \-\- path to the home folder of the custom installation         (Required)
.UNINDENT
.sp
For the \fBvirtualenv\fP environment:
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpython\-version\fP (\fIstr\fP) \-\- Name of the python installation to use.
Must match one of the configured installations on server         configuration
(default: System\-CPython\-2.7)
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- Name of this virtualenv. Two virtualenv builders with         the same name will use the same virtualenv installation (optional)
.IP \(bu 2
\fBclear\fP (\fIbool\fP) \-\- If true, delete and recreate virtualenv on each build.
(default: false)
.IP \(bu 2
\fBuse\-distribute\fP (\fIbool\fP) \-\- if true use distribute, if false use         setuptools. (default: true)
.IP \(bu 2
\fBsystem\-site\-packages\fP (\fIbool\fP) \-\- if true, give access to the global
site\-packages directory to the virtualenv. (default: false)
.UNINDENT
.UNINDENT
.sp
Common to all environments:
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBnature\fP (\fIstr\fP) \-\- 
.sp
Nature of the command field. (default: shell)
.INDENT 2.0
.TP
.B nature values
.INDENT 7.0
.IP \(bu 2
\fBshell\fP: execute the Command contents with default shell
.IP \(bu 2
\fBxshell\fP: like \fBshell\fP but performs platform conversion                 first
.IP \(bu 2
\fBpython\fP: execute the Command contents with the Python                 executable
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBcommand\fP (\fIstr\fP) \-\- The command to execute
.IP \(bu 2
\fBignore\-exit\-code\fP (\fIbool\fP) \-\- mark the build as failure if any of the
commands exits with a non\-zero exit code. (default: false)
.UNINDENT
.UNINDENT
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
    \- shining\-panda:
        build\-environment: python
        python\-version: System\-CPython\-2.7
        nature: python
        command: setup.py build
        ignore\-exit\-code: false

.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
    \- shining\-panda:
        build\-environment: custom
        home: /usr/local/lib/custom\-python\-27
        nature: xshell
        command: |
            cd $HOME/build
            python setup.py build
        ignore\-exit\-code: true

.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
    \- shining\-panda:
        build\-environment: virtualenv
        python\-version: System\-CPython\-2.7
        nature: shell
        command: python setup.py build
        name: virtvenv1
        clear: true
        use\-distribute: true
        system\-site\-packages: true
        ignore\-exit\-code: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ssh
Send files or execute commands over SSH.
Requires the Jenkins \fI\%Publish over SSH Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBsite\fP (\fIstr\fP) \-\- name of the ssh site
.IP \(bu 2
\fBtarget\fP (\fIstr\fP) \-\- destination directory
.IP \(bu 2
\fBtarget\-is\-date\-format\fP (\fIbool\fP) \-\- whether target is a date format. If true,
raw text should be quoted (defaults to False)
.IP \(bu 2
\fBclean\-remote\fP (\fIbool\fP) \-\- should the remote directory be deleted before
transferring files (defaults to False)
.IP \(bu 2
\fBsource\fP (\fIstr\fP) \-\- source path specifier
.IP \(bu 2
\fBcommand\fP (\fIstr\fP) \-\- a command to execute on the remote server (optional)
.IP \(bu 2
\fBtimeout\fP (\fIint\fP) \-\- timeout in milliseconds for the Exec command (optional)
.IP \(bu 2
\fBuse\-pty\fP (\fIbool\fP) \-\- run the exec command in pseudo TTY (defaults to False)
.IP \(bu 2
\fBexcludes\fP (\fIstr\fP) \-\- excluded file pattern (optional)
.IP \(bu 2
\fBremove\-prefix\fP (\fIstr\fP) \-\- prefix to remove from uploaded file paths
(optional)
.IP \(bu 2
\fBfail\-on\-error\fP (\fIbool\fP) \-\- fail the build if an error occurs (defaults to
False).
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- ssh:
      site: \(aqserver.example.com\(aq
      target: \(aqdest/dir\(aq
      source: \(aqbase/source/dir/**\(aq
      remove\-prefix: \(aqbase/source/dir\(aq
      excludes: \(aq**/*.excludedfiletype\(aq
      use\-pty: true
      command: \(aqrm \-r jenkins_$BUILD_NUMBER\(aq
      timeout: 1800000
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B system\-groovy
Execute a system groovy script or command.
Requires the Jenkins \fI\%Groovy Plugin\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBfile\fP (\fIstr\fP) \-\- Groovy file to run.
(Alternative: you can chose a command instead)
.IP \(bu 2
\fBcommand\fP (\fIstr\fP) \-\- Groovy command to run.
(Alternative: you can chose a script file instead)
.IP \(bu 2
\fBbindings\fP (\fIstr\fP) \-\- Define variable bindings (in the properties file
format). Specified variables can be addressed from the script. (optional)
.IP \(bu 2
\fBclass\-path\fP (\fIstr\fP) \-\- Specify script classpath here. Each line is one class
path item. (optional)
.UNINDENT
.UNINDENT
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- system\-groovy:
      file: "test.groovy"

.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- system\-groovy:
      command: "Some command"
      bindings: "Some bindings"
      class\-path: "Some classpath"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B trigger\-builds
Trigger builds of other jobs.
Requires the Jenkins \fI\%Parameterized Trigger Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBproject\fP (\fIstr\fP) \-\- the Jenkins project to trigger
.IP \(bu 2
\fBpredefined\-parameters\fP (\fIstr\fP) \-\- key/value pairs to be passed to the job (optional)
.IP \(bu 2
\fBproperty\-file\fP (\fIstr\fP) \-\- Pass properties from file to the other job (optional)
.IP \(bu 2
\fBproperty\-file\-fail\-on\-missing\fP (\fIbool\fP) \-\- Don\(aqt trigger if any files are missing (optional)
(default true)
.IP \(bu 2
\fBcurrent\-parameters\fP (\fIbool\fP) \-\- Whether to include the
parameters passed to the current build to the
triggered job.
.IP \(bu 2
\fBsvn\-revision\fP (\fIbool\fP) \-\- Whether to pass the svn revision
to the triggered job
.IP \(bu 2
\fBblock\fP (\fIbool\fP) \-\- whether to wait for the triggered jobs
to finish or not (default false)
.IP \(bu 2
\fBsame\-node\fP (\fIbool\fP) \-\- Use the same node for the triggered builds that was
used for this build (optional)
.IP \(bu 2
\fBparameter\-factories\fP (\fIlist\fP) \-\- 
.sp
list of parameter factories
.INDENT 2.0
.TP
.B Factory
.INDENT 7.0
.IP \(bu 2
\fBfactory\fP (\fIstr\fP) \fBfilebuild\fP \-\- For every property file,
invoke one build
.IP \(bu 2
\fBfile\-pattern\fP (\fIstr\fP) \-\- File wildcard pattern
.IP \(bu 2
\fBno\-files\-found\-action\fP (\fIstr\fP) \-\- Action to perform when
no files found  (optional) [\(aqFAIL\(aq, \(aqSKIP\(aq, \(aqNOPARMS\(aq]
(default \(aqSKIP\(aq)
.UNINDENT
.TP
.B Factory
.INDENT 7.0
.IP \(bu 2
\fBfactory\fP (\fIstr\fP) \fBbinaryfile\fP \-\- For every matching
file, invoke one build
.IP \(bu 2
\fBfile\-pattern\fP (\fIstr\fP) \-\- Artifact ID of the artifact
.IP \(bu 2
\fBno\-files\-found\-action\fP (\fIstr\fP) \-\- Action to perform when
no files found  (optional) [\(aqFAIL\(aq, \(aqSKIP\(aq, \(aqNOPARMS\(aq]
(default \(aqSKIP\(aq)
.UNINDENT
.TP
.B Factory
.INDENT 7.0
.IP \(bu 2
\fBfactory\fP (\fIstr\fP) \fBcounterbuild\fP \-\- Invoke i=0...N builds
.IP \(bu 2
\fBfrom\fP (\fIint\fP) \-\- Artifact ID of the artifact
.IP \(bu 2
\fBto\fP (\fIint\fP) \-\- Version of the artifact
.IP \(bu 2
\fBstep\fP (\fIint\fP) \-\- Classifier of the artifact
.IP \(bu 2
\fBparameters\fP (\fIstr\fP) \-\- KEY=value pairs, one per line
(default \(aq\(aq)
.IP \(bu 2
\fBvalidation\-fail\fP (\fIstr\fP) \-\- Action to perform when
stepping validation fails  (optional)
[\(aqFAIL\(aq, \(aqSKIP\(aq, \(aqNOPARMS\(aq]
(default \(aqFAIL\(aq)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Examples:
.sp
Basic usage.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- trigger\-builds:
    \- project: "build_started"
      predefined\-parameters:
        FOO="bar"
      current\-parameters: true
      svn\-revision: true
      block: true

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example with all supported parameter factories.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
builders:
  \- trigger\-builds:
    \- project: "build_started"
      predefined\-parameters:
        FOO="bar"
      current\-parameters: true
      svn\-revision: true
      parameter\-factories:
        \- factory: filebuild
          file\-pattern: propfile*.txt
        \- factory: binaryfile
          parameter\-name: filename
          file\-pattern: otherpropfile*.txt
        \- factory: counterbuild
          from: 0
          to: 5
          step: 1
      block: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Hipchat
.sp
Enable hipchat notification of build execution.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- job:
    name: test_job
    hipchat:
      enabled: true
      room:  Testjob Build Notifications
      start\-notify: true
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the jenkins UI specification, the hipchat plugin must be explicitly
selected as a publisher.  This is not required (or supported) here \- use the
\fBenabled\fP parameter to enable/disable the publisher action.
If you set \fBenabled: false\fP, no hipchat parameters are written to XML.
.SS Metadata
.sp
The Metadata plugin module enables the ability to add metadata to the projects
that can be exposed to job environment.
Requires the Jenkins \fI\%Metadata Plugin.\fP
.INDENT 0.0
.TP
.B \fBComponent\fP: metadata
.INDENT 7.0
.TP
.B Macro
metadata
.TP
.B Entry Point
jenkins_jobs.metadata
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
metadata:
  \- string:
      name: FOO
      value: bar
      expose\-to\-env: true
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B date
A date metadata
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the metadata
.IP \(bu 2
\fBtime\fP (\fIstr\fP) \-\- time value in millisec since 1970\-01\-01 00:00:00 UTC
.IP \(bu 2
\fBtimezone\fP (\fIstr\fP) \-\- time zone of the metadata
.IP \(bu 2
\fBexpose\-to\-env\fP (\fIbool\fP) \-\- expose to environment (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
metadata:
  \- date:
      name: FOO
      value: 1371708900268
      timezone: Australia/Melbourne
      expose\-to\-env: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B number
A number metadata.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the metadata
.IP \(bu 2
\fBvalue\fP (\fIstr\fP) \-\- the value of the metadata
.IP \(bu 2
\fBexpose\-to\-env\fP (\fIbool\fP) \-\- expose to environment (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
metadata:
  \- number:
      name: FOO
      value: 1
      expose\-to\-env: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B string
A string metadata.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the metadata
.IP \(bu 2
\fBvalue\fP (\fIstr\fP) \-\- the value of the metadata
.IP \(bu 2
\fBexpose\-to\-env\fP (\fIbool\fP) \-\- expose to environment (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
metadata:
  \- string:
      name: FOO
      value: bar
      expose\-to\-env: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Notifications
.sp
The Notifications module allows you to configure Jenkins to notify
other applications about various build phases.  It requires the
Jenkins notification plugin.
.INDENT 0.0
.TP
.B \fBComponent\fP: notifications
.INDENT 7.0
.TP
.B Macro
notification
.TP
.B Entry Point
jenkins_jobs.notifications
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job:
  name: test_job

  notifications:
    \- http:
        url: http://example.com/jenkins_endpoint
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B http
Defines an HTTP notification endpoint.
Requires the Jenkins \fI\%Notification Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBurl\fP (\fIstr\fP) \-\- URL of the endpoint
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
notifications:
  \- http:
      url: http://example.com/jenkins_endpoint
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Parameters
.sp
The Parameters module allows you to specify build parameters for a job.
.INDENT 0.0
.TP
.B \fBComponent\fP: parameters
.INDENT 7.0
.TP
.B Macro
parameter
.TP
.B Entry Point
jenkins_jobs.parameters
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job:
  name: test_job

  parameters:
    \- string:
        name: FOO
        default: bar
        description: "A parameter named FOO, defaults to \(aqbar\(aq."
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B bool
A boolean parameter.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdefault\fP (\fIstr\fP) \-\- the default value of the parameter (optional)
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- bool:
      name: FOO
      default: false
      description: "A parameter named FOO, defaults to \(aqfalse\(aq."
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B choice
A single selection parameter.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBchoices\fP (\fIlist\fP) \-\- the available choices
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- choice:
      name: project
      choices:
        \- nova
        \- glance
      description: "On which project to run?"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B dynamic\-choice
Dynamic Choice Parameter
Requires the Jenkins \fI\%Jenkins Dynamic Parameter Plug\-in.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.IP \(bu 2
\fBscript\fP (\fIstr\fP) \-\- Groovy expression which generates the potential choices.
.IP \(bu 2
\fBremote\fP (\fIbool\fP) \-\- the script will be executed on the slave where the build
is started (default false)
.IP \(bu 2
\fBclasspath\fP (\fIstr\fP) \-\- class path for script (optional)
.IP \(bu 2
\fBread\-only\fP (\fIbool\fP) \-\- user can\(aqt modify parameter once populated
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- dynamic\-choice:
      name: OPTIONS
      description: "Available options"
      script: "[\(aqoptionA\(aq, \(aqoptionB\(aq]"
      remote: false
      read\-only: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B dynamic\-choice\-scriptler
Dynamic Choice Parameter (Scriptler)
Requires the Jenkins \fI\%Jenkins Dynamic Parameter Plug\-in.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.IP \(bu 2
\fBscript\-id\fP (\fIstr\fP) \-\- Groovy script which generates the default value
.IP \(bu 2
\fBparameters\fP (\fIlist\fP) \-\- 
.sp
parameters to corresponding script
.INDENT 2.0
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) Parameter name
.IP \(bu 2
\fBvalue\fP (\fIstr\fP) Parameter value
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBremote\fP (\fIbool\fP) \-\- the script will be executed on the slave where the build
is started (default false)
.IP \(bu 2
\fBread\-only\fP (\fIbool\fP) \-\- user can\(aqt modify parameter once populated
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- dynamic\-choice\-scriptler:
      name: OPTIONS
      description: "Available options"
      script\-id: "scriptid.groovy"
      parameters:
        \- name: param1
          value: value1
        \- name: param2
          value: value2
      remote: false
      read\-only: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B dynamic\-string
Dynamic Parameter
Requires the Jenkins \fI\%Jenkins Dynamic Parameter Plug\-in.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.IP \(bu 2
\fBscript\fP (\fIstr\fP) \-\- Groovy expression which generates the potential choices
.IP \(bu 2
\fBremote\fP (\fIbool\fP) \-\- the script will be executed on the slave where the build
is started (default false)
.IP \(bu 2
\fBclasspath\fP (\fIstr\fP) \-\- class path for script (optional)
.IP \(bu 2
\fBread\-only\fP (\fIbool\fP) \-\- user can\(aqt modify parameter once populated
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- dynamic\-string:
      name: FOO
      description: "A parameter named FOO, defaults to \(aqbar\(aq."
      script: "bar"
      remote: false
      read\-only: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B dynamic\-string\-scriptler
Dynamic Parameter (Scriptler)
Requires the Jenkins \fI\%Jenkins Dynamic Parameter Plug\-in.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.IP \(bu 2
\fBscript\-id\fP (\fIstr\fP) \-\- Groovy script which generates the default value
.IP \(bu 2
\fBparameters\fP (\fIlist\fP) \-\- 
.sp
parameters to corresponding script
.INDENT 2.0
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) Parameter name
.IP \(bu 2
\fBvalue\fP (\fIstr\fP) Parameter value
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBremote\fP (\fIbool\fP) \-\- the script will be executed on the slave where the build
is started (default false)
.IP \(bu 2
\fBread\-only\fP (\fIbool\fP) \-\- user can\(aqt modify parameter once populated
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- dynamic\-string\-scriptler:
      name: FOO
      description: "A parameter named FOO, defaults to \(aqbar\(aq."
      script\-id: "scriptid.groovy"
      parameters:
        \- name: param1
          value: value1
        \- name: param2
          value: value2
      remote: false
      read\-only: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B file
A file parameter.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the target location for the file upload
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- file:
      name: test.txt
      description: "Upload test.txt."
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B label
A node label parameter.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdefault\fP (\fIstr\fP) \-\- the default value of the parameter (optional)
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- label:
      name: node
      default: precise
      description: "The node on which to run the job"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B password
A password parameter.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdefault\fP (\fIstr\fP) \-\- the default value of the parameter (optional)
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- password:
      name: FOO
      default: 1HSC0Ts6E161FysGf+e1xasgsHkgleLh09JUTYnipPvw=
      description: "A parameter named FOO."
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B string
A string parameter.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdefault\fP (\fIstr\fP) \-\- the default value of the parameter (optional)
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- string:
      name: FOO
      default: bar
      description: "A parameter named FOO, defaults to \(aqbar\(aq."
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B svn\-tags
A svn tag parameter
Requires the Jenkins \fI\%Parameterized Trigger Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdefault\fP (\fIstr\fP) \-\- the default value of the parameter (optional)
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.IP \(bu 2
\fBurl\fP (\fIstr\fP) \-\- the url to list tags from
.IP \(bu 2
\fBfilter\fP (\fIstr\fP) \-\- the regular expression to filter tags
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- svn\-tags:
      name: BRANCH_NAME
      default: release
      description: A parameter named BRANCH_NAME default is release
      url: http://svn.example.com/repo
      filter: [A\-za\-z0\-9]*
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B text
A text parameter.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdefault\fP (\fIstr\fP) \-\- the default value of the parameter (optional)
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- text:
      name: FOO
      default: bar
      description: "A parameter named FOO, defaults to \(aqbar\(aq."
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B validating\-string
A validating string parameter
Requires the Jenkins \fI\%Validating String Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- the name of the parameter
.IP \(bu 2
\fBdefault\fP (\fIstr\fP) \-\- the default value of the parameter (optional)
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- a description of the parameter (optional)
.IP \(bu 2
\fBregex\fP (\fIstr\fP) \-\- a regular expression to validate the string
.IP \(bu 2
\fBmsg\fP (\fIstr\fP) \-\- a message to display upon failed validation
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
parameters:
  \- validating\-string:
      name: FOO
      default: bar
      description: "A parameter named FOO, defaults to \(aqbar\(aq."
      regex: [A\-Za\-z]*
      msg: Your entered value failed validation
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Properties
.sp
The Properties module supplies a wide range of options that are
implemented as Jenkins job properties.
.INDENT 0.0
.TP
.B \fBComponent\fP: properties
.INDENT 7.0
.TP
.B Macro
property
.TP
.B Entry Point
jenkins_jobs.properties
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job:
  name: test_job

  properties:
    \- github:
        url: https://github.com/openstack\-infra/jenkins\-job\-builder/
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B authenticated\-build
Specifies an authorization matrix where only authenticated users
may trigger a build.
.sp
DEPRECATED
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- authenticated\-build
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B authorization
Specifies an authorization matrix
.INDENT 7.0
.TP
.B The available rights are:
job\-delete
job\-configure
job\-read
job\-extended\-read
job\-discover
job\-build
job\-workspace
job\-cancel
run\-delete
run\-update
scm\-tag
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- authorization:
      admin:
        \- job\-delete
        \- job\-configure
        \- job\-read
        \- job\-discover
        \- job\-build
        \- job\-workspace
        \- job\-cancel
        \- run\-delete
        \- run\-update
        \- scm\-tag
      anonymous:
        \- job\-discover
        \- job\-read
        \- job\-extended\-read
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B batch\-tasks
Batch tasks can be tasks for events like releases, integration, archiving,
etc. In this way, anyone in the project team can execute them in a way that
leaves a record.
.sp
A batch task consists of a shell script and a name. When you execute
a build, the shell script gets run on the workspace, just like a build.
Batch tasks and builds "lock" the workspace, so when one of those
activities is in progress, all the others will block in the queue.
.sp
Requires the Jenkins \fI\%Batch Task Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBbatch\-tasks\fP (\fIlist\fP) \-\- 
.sp
Batch tasks.
.INDENT 7.0
.TP
.B Task
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) Task name.
.IP \(bu 2
\fBscript\fP (\fIstr\fP) Task script.
.UNINDENT
.UNINDENT

.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- batch\-tasks:
      \- name: release
        script: mvn \-B release:prepare release:perform
      \- name: say hello
        script: echo "Hello world"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B build\-blocker
This plugin keeps the actual job in the queue
if at least one name of currently running jobs
is matching with one of the given regular expressions.
.sp
Requires the Jenkins \fI\%Build Blocker Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBuse\-build\-blocker\fP (\fIbool\fP) \-\- Enable or disable build blocker
(optional) (default true)
.IP \(bu 2
\fBblocking\-jobs\fP (\fIlist\fP) \-\- One regular expression per line
to select blocking jobs by their names. (required)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- build\-blocker:
      use\-build\-blocker: true
      blocking\-jobs:
        \- ".*\-deploy"
        \- "^maintenance.*"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B builds\-chain\-fingerprinter
Builds chain fingerprinter.
Requires the Jenkins \fI\%Builds chain fingerprinter Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBper\-builds\-chain\fP (\fIbool\fP) \-\- enable builds hierarchy fingerprinting
(default False)
.IP \(bu 2
\fBper\-job\-chain\fP (\fIbool\fP) \-\- enable jobs hierarchy fingerprinting
(default False)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- builds\-chain\-fingerprinter:
      per\-builds\-chain: true
      per\-job\-chain: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B copyartifact
Specify a list of projects that have access to copy the artifacts of
this project.
.sp
Requires the Jenkins \fI\%Copy Artifact plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBprojects\fP (\fIstring\fP) \-\- comma separated list of projects that can copy
artifacts of this project. Wild card character \(aq*\(aq is available.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- copyartifact:
      projects: foo*

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B delivery\-pipeline
Requires the Jenkins \fI\%Delivery Pipeline Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBstage\fP (\fIstr\fP) \-\- Name of the stage for this job (default: \(aq\(aq)
.IP \(bu 2
\fBtask\fP (\fIstr\fP) \-\- Name of the task for this job (default: \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- delivery\-pipeline:
      stage: Stage
      task: Task

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B extended\-choice
Creates an extended choice property where values can be read from a file
Requires the Jenkins \fI\%Extended Choice Parameter Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstring\fP) \-\- name of the property
.IP \(bu 2
\fBdescription\fP (\fIstring\fP) \-\- description of the property (optional, default \(aq\(aq)
.IP \(bu 2
\fBproperty\-file\fP (\fIstring\fP) \-\- location of property file to read from
(optional, default \(aq\(aq)
.IP \(bu 2
\fBproperty\-key\fP (\fIstring\fP) \-\- key for the property\-file (optional, default \(aq\(aq)
.IP \(bu 2
\fBquote\-value\fP (\fIbool\fP) \-\- whether to put quotes around the property
when passing to Jenkins (optional, default false)
.IP \(bu 2
\fBvisible\-items\fP (\fIstring\fP) \-\- number of items to show in the list
(optional, default 5)
.IP \(bu 2
\fBtype\fP (\fIstring\fP) \-\- type of select (optional, default single\-select)
.IP \(bu 2
\fBvalue\fP (\fIstring\fP) \-\- comma separated list of values for the single select
or multi\-select box (optional, default \(aq\(aq)
.IP \(bu 2
\fBdefault\-value\fP (\fIstring\fP) \-\- used to set the initial selection of the
single\-select or multi\-select box (optional, default \(aq\(aq)
.IP \(bu 2
\fBdefault\-property\-file\fP (\fIstring\fP) \-\- location of property file when default
value needs to come from a property file (optional, default \(aq\(aq)
.IP \(bu 2
\fBdefault\-property\-key\fP (\fIstring\fP) \-\- key for the default property file
(optional, default \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- extended\-choice:
      name: FOO
      description: A foo property
      property\-file: /home/foo/property.prop
      property\-key: key
      quote\-value: true
      visible\-items: 10
      type: multi\-select
      value: foo,bar,select
      default\-value: foo
      default\-property\-file: /home/property.prop
      default\-property\-key: fookey
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B github
Sets the GitHub URL for the project.
.INDENT 7.0
.TP
.B Parameters
\fBurl\fP (\fIstr\fP) \-\- the GitHub URL
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- github:
      url: https://github.com/openstack\-infra/jenkins\-job\-builder/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B heavy\-job
This plugin allows you to define "weight" on each job,
and making each job consume that many executors
.sp
Requires the Jenkins \fI\%Heavy Job Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBweight\fP (\fIint\fP) \-\- Specify the total number of executors
that this job should occupy (default 1)
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- heavy\-job:
      weight: 2

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B inject
Allows you to inject evironment variables into the build.
Requires the Jenkins \fI\%Env Inject Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBproperties\-file\fP (\fIstr\fP) \-\- file to read with properties (optional)
.IP \(bu 2
\fBproperties\-content\fP (\fIstr\fP) \-\- key=value properties (optional)
.IP \(bu 2
\fBscript\-file\fP (\fIstr\fP) \-\- file with script to run (optional)
.IP \(bu 2
\fBscript\-content\fP (\fIstr\fP) \-\- script to run (optional)
.IP \(bu 2
\fBgroovy\-content\fP (\fIstr\fP) \-\- groovy script to run (optional)
.IP \(bu 2
\fBload\-from\-master\fP (\fIbool\fP) \-\- load files from master (default false)
.IP \(bu 2
\fBenabled\fP (\fIbool\fP) \-\- injection enabled (default true)
.IP \(bu 2
\fBkeep\-system\-variables\fP (\fIbool\fP) \-\- keep system variables (default true)
.IP \(bu 2
\fBkeep\-build\-variables\fP (\fIbool\fP) \-\- keep build variable (default true)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- inject:
      properties\-content: FOO=bar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B least\-load
Enables the Least Load Plugin.
Requires the Jenkins \fI\%Least Load Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBdisabled\fP (\fIbool\fP) \-\- whether or not leastload is disabled (default True)
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- least\-load:
      disabled: False

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ownership
Plugin provides explicit ownership for jobs and slave nodes.
Requires the Jenkins \fI\%Ownership Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBenabled\fP (\fIbool\fP) \-\- whether ownership enabled (default : true)
.IP \(bu 2
\fBowner\fP (\fIstr\fP) \-\- the owner of job
.IP \(bu 2
\fBco\-owners\fP (\fIlist\fP) \-\- list of job co\-owners
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
 \- ownership:
    owner: abraverm
    co\-owners:
     \- lbednar
     \- edolinin
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B priority\-sorter
Allows simple ordering of builds, using a configurable job priority.
.sp
Requires the Jenkins \fI\%Priority Sorter Plugin\fP\&.
.INDENT 7.0
.TP
.B Parameters
\fBpriority\fP (\fIint\fP) \-\- Priority of the job.  Higher value means higher
priority, with 100 as the standard priority. (required)
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- priority\-sorter:
      priority: 150
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B promoted\-build
Marks a build for promotion. A promotion process with an identical
name must be created via the web interface in the job in order for the job
promotion to persist. Promotion processes themselves cannot be configured
by jenkins\-jobs due to the separate storage of plugin configuration files.
Requires the Jenkins \fI\%Promoted Builds Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBnames\fP (\fIlist\fP) \-\- the promoted build names
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- promoted\-build:
      names:
        \- "Release to QA"
        \- "Jane Must Approve"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B slave\-utilization
This plugin allows you to specify the percentage of a slave\(aqs capacity a
job wants to use.
.sp
Requires the Jenkins \fI\%Slave Utilization Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBslave\-percentage\fP (\fIint\fP) \-\- Specify the percentage of a slave\(aqs execution
slots that this job should occupy (default: 0)
.IP \(bu 2
\fBsingle\-instance\-per\-slave\fP (\fIbool\fP) \-\- Control whether concurrent instances
of this job will be permitted to run in parallel on a single slave
(default: False)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- slave\-utilization:
      slave\-percentage: 40
      single\-instance\-per\-slave: false

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B throttle
Throttles the number of builds for this job.
Requires the Jenkins \fI\%Throttle Concurrent Builds Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBmax\-per\-node\fP (\fIint\fP) \-\- max concurrent builds per node (default 0)
.IP \(bu 2
\fBmax\-total\fP (\fIint\fP) \-\- max concurrent builds (default 0)
.IP \(bu 2
\fBenabled\fP (\fIbool\fP) \-\- whether throttling is enabled (default True)
.IP \(bu 2
\fBoption\fP (\fIstr\fP) \-\- throttle \fIproject\fP or \fIcategory\fP
.IP \(bu 2
\fBcategories\fP (\fIlist\fP) \-\- multiproject throttle categories
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- throttle:
      max\-total: 4
      categories:
        \- cat1
        \- cat2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B zeromq\-event
This is a Jenkins plugin that will publish Jenkins Job run events
(start, complete, finish) to a ZMQ PUB socket.
.sp
Requires the Jenkins \fI\%ZMQ Event Publisher.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
properties:
  \- zeromq\-event

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Publishers
.sp
Publishers define actions that the Jenkins job should perform after
the build is complete.
.INDENT 0.0
.TP
.B \fBComponent\fP: publishers
.INDENT 7.0
.TP
.B Macro
publisher
.TP
.B Entry Point
jenkins_jobs.publishers
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B aggregate\-tests
Aggregate downstream test results
.INDENT 7.0
.TP
.B Parameters
\fBinclude\-failed\-builds\fP (\fIbool\fP) \-\- whether to include failed builds
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- aggregate\-tests:
      include\-failed\-builds: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B archive
Archive build artifacts
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBartifacts\fP (\fIstr\fP) \-\- path specifier for artifacts to archive
.IP \(bu 2
\fBexcludes\fP (\fIstr\fP) \-\- path specifier for artifacts to exclude
.IP \(bu 2
\fBlatest\-only\fP (\fIbool\fP) \-\- only keep the artifacts from the latest
successful build
.IP \(bu 2
\fBallow\-empty\fP (\fIbool\fP) \-\- pass the build if no artifacts are
found (default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- archive:
      artifacts: \(aq*.tar.gz\(aq
      allow\-empty: \(aqtrue\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B artifact\-deployer
This plugin makes it possible to copy artifacts to remote locations.
.sp
Requires the Jenkins \fI\%ArtifactDeployer Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBentries\fP (\fIlist\fP) \-\- .INDENT 2.0
.TP
.B entries
.INDENT 7.0
.IP \(bu 2
\fBfiles\fP (\fIstr\fP) \- files to deploy
.IP \(bu 2
\fBbasedir\fP (\fIstr\fP) \- the dir from files are deployed
.IP \(bu 2
\fBexcludes\fP (\fIstr\fP) \- the mask to exclude files
.IP \(bu 2
\fBremote\fP (\fIstr\fP) \- a remote output directory
.IP \(bu 2
\fBflatten\fP (\fIbool\fP) \- ignore the source directory structure
(Default: False)
.IP \(bu 2
\fBdelete\-remote\fP (\fIbool\fP) \- clean\-up remote directory
before deployment (Default: False)
.IP \(bu 2
\fBdelete\-remote\-artifacts\fP (\fIbool\fP) \- delete remote artifacts
when the build is deleted (Default: False)
.IP \(bu 2
\fBfail\-no\-files\fP (\fIbool\fP) \- fail build if there are no files
(Default: False)
.IP \(bu 2
\fBgroovy\-script\fP (\fIstr\fP) \- execute a Groovy script
before a build is deleted
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBdeploy\-if\-fail\fP (\fIbool\fP) \-\- Deploy if the build is failed (Default: False)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- artifact\-deployer:
      entries:
        \- files: \(aq*.tar.gz\(aq
          basedir: \(aq/opt/data\(aq
          excludes: \(aq*tmp*\(aq
          remote: \(aq/home/test/\(aq
          flatten: true
          delete\-remote: true
          delete\-remote\-artifacts: true
          fail\-no\-files: true
          groovy\-script: \(aqprint 123\(aq
      deploy\-if\-fail: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B blame\-upstream
Notify upstream commiters when build fails
Requires the Jenkins \fI\%Blame upstream commiters Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- blame\-upstream

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B build\-publisher
This plugin allows records from one Jenkins to be published
on another Jenkins.
.sp
Requires the Jenkins \fI\%Build Publisher Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBservers\fP (\fIstr\fP) \-\- Specify the servers where to publish
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- build\-publisher:
        name: servername
        publish\-unstable\-builds: true
        publish\-failed\-builds: true
        days\-to\-keep: \-1
        num\-to\-keep: \-1
        artifact\-days\-to\-keep: \-1
        artifact\-num\-to\-keep: \-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B publishers.build_trends_publisher(plugin_name, xml_element, data)
Helper to create various trend publishers.
.UNINDENT
.INDENT 0.0
.TP
.B campfire
Send build notifications to Campfire rooms.
Requires the Jenkins \fI\%Campfire Plugin.\fP
.sp
Campfire notifications global default values must be configured for
the Jenkins instance. Default values will be used if no specific
values are specified for each job, so all config params are optional.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBsubdomain\fP (\fIstr\fP) \-\- override the default campfire subdomain
.IP \(bu 2
\fBtoken\fP (\fIstr\fP) \-\- override the default API token
.IP \(bu 2
\fBssl\fP (\fIbool\fP) \-\- override the default \(aquse SSL\(aq
.IP \(bu 2
\fBroom\fP (\fIstr\fP) \-\- override the default room name
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- campfire:
        subdomain: \(aqsub\(aq
        ssl: true
        token: \(aqTOKEN\(aq
        room: \(aqroom\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B checkstyle
Publish trend reports with Checkstyle.
Requires the Jenkins \fI\%Checkstyle Plugin.\fP
.sp
The checkstyle component accepts a dictionary with the
following values:
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP (\fIstr\fP) \-\- report filename pattern
.IP \(bu 2
\fBcanRunOnFailed\fP (\fIbool\fP) \-\- also runs for failed builds
(instead of just stable or unstable builds)
.IP \(bu 2
\fBshouldDetectModules\fP (\fIbool\fP) \-\- 
.IP \(bu 2
\fBhealthy\fP (\fIint\fP) \-\- sunny threshold
.IP \(bu 2
\fBunHealthy\fP (\fIint\fP) \-\- stormy threshold
.IP \(bu 2
\fBhealthThreshold\fP (\fIstr\fP) \-\- threshold priority for health status
(high: only high, normal: high and normal, low: all)
.IP \(bu 2
\fBthresholds\fP (\fIdict\fP) \-\- .INDENT 2.0
.TP
.B thresholds
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBunstable\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B unstable
.INDENT 7.0
.IP \(bu 2
\fBtotalAll\fP (\fIint\fP)
.IP \(bu 2
\fBtotalHigh\fP (\fIint\fP)
.IP \(bu 2
\fBtotalNormal\fP (\fIint\fP)
.IP \(bu 2
\fBtotalLow\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBfailed\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B failed
.INDENT 7.0
.IP \(bu 2
\fBtotalAll\fP (\fIint\fP)
.IP \(bu 2
\fBtotalHigh\fP (\fIint\fP)
.IP \(bu 2
\fBtotalNormal\fP (\fIint\fP)
.IP \(bu 2
\fBtotalLow\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBdefaultEncoding\fP (\fIstr\fP) \-\- encoding for parsing or showing files
(empty will use platform default)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
 \- checkstyle:
    pattern: \(aq**/checkstyle\-result.xml\(aq
    healthy: 0
    unHealthy: 100
    healthThreshold: \(aqhigh\(aq
    thresholds:
        unstable:
            totalHigh: 10
        failed:
            totalHigh: 1

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Full example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
 \- checkstyle:
    pattern: \(aq**/checkstyle\-result.xml\(aq
    canRunOnFailed: true
    shouldDetectModules: true
    healthy: 0
    unHealthy: 100
    healthThreshold: \(aqhigh\(aq
    thresholds:
        unstable:
            totalAll: 90
            totalHigh: 80
            totalNormal: 70
            totalLow: 60
        failed:
            totalAll: 90
            totalHigh: 80
            totalNormal: 70
            totalLow: 60
    defaultEncoding: \(aqutf\-8\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B cifs
Upload files via CIFS.
Requires the Jenkins \fI\%Publish over CIFS Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBsite\fP (\fIstr\fP) \-\- name of the cifs site/share
.IP \(bu 2
\fBtarget\fP (\fIstr\fP) \-\- destination directory
.IP \(bu 2
\fBtarget\-is\-date\-format\fP (\fIbool\fP) \-\- whether target is a date format. If true,
raw text should be quoted (default false)
.IP \(bu 2
\fBclean\-remote\fP (\fIbool\fP) \-\- should the remote directory be deleted before
transferring files (default false)
.IP \(bu 2
\fBsource\fP (\fIstr\fP) \-\- source path specifier
.IP \(bu 2
\fBexcludes\fP (\fIstr\fP) \-\- excluded file pattern (optional)
.IP \(bu 2
\fBremove\-prefix\fP (\fIstr\fP) \-\- prefix to remove from uploaded file paths
(optional)
.IP \(bu 2
\fBfail\-on\-error\fP (\fIbool\fP) \-\- fail the build if an error occurs (default false).
.IP \(bu 2
\fBflatten\fP (\fIbool\fP) \-\- only create files on the server, don\(aqt create
directories (default false).
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- cifs:
      site: \(aqcifs.share\(aq
      target: \(aqdest/dir\(aq
      source: \(aqbase/source/dir/**\(aq
      remove\-prefix: \(aqbase/source/dir\(aq
      excludes: \(aq**/*.excludedfiletype\(aq
      flatten: true


.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B cigame
This plugin introduces a game where users get points
for improving the builds.
Requires the Jenkins \fI\%The Continuous Integration Game plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- cigame

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B claim\-build
Claim build failures
Requires the Jenkins \fI\%Claim Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- claim\-build
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B clone\-workspace
Archive the workspace from builds of one project and reuse them as the SCM
source for another project.
Requires the Jenkins \fI\%Clone Workspace SCM Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBworkspace\-glob\fP (\fIstr\fP) \-\- Files to include in cloned workspace
.IP \(bu 2
\fBworkspace\-exclude\-glob\fP (\fIstr\fP) \-\- Files to exclude from cloned workspace
.IP \(bu 2
\fBcriteria\fP (\fIstr\fP) \-\- Criteria for build to be archived.  Can be \(aqany\(aq,
\(aqnot failed\(aq, or \(aqsuccessful\(aq. (default: any )
.IP \(bu 2
\fBarchive\-method\fP (\fIstr\fP) \-\- Choose the method to use for archiving the
workspace.  Can be \(aqtar\(aq or \(aqzip\(aq.  (default: tar)
.IP \(bu 2
\fBoverride\-default\-excludes\fP (\fIbool\fP) \-\- Override default ant excludes.
(default: false)
.UNINDENT
.UNINDENT
.sp
Minimal example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- clone\-workspace

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Full example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- clone\-workspace:
      criteria: "any"
      archive\-method: "tar"
      override\-default\-excludes: false
      workspace\-glob: "**/*.zip"
      workspace\-exclude\-glob: "**/*.tgz"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B cloverphp
Capture code coverage reports from PHPUnit
Requires the Jenkins \fI\%Clover PHP Plugin.\fP
.sp
Your job definition should pass to PHPUnit the \-\-coverage\-clover option
pointing to a file in the workspace (ex: clover\-coverage.xml). The filename
has to be filled in the \fIxml\-location\fP field.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBxml\-location\fP (\fIstr\fP) \-\- Path to the coverage XML file generated by PHPUnit
using \-\-coverage\-clover. Relative to workspace. (required)
.IP \(bu 2
\fBhtml\fP (\fIdict\fP) \-\- 
.sp
When existent, whether the plugin should generate a HTML
report.  Note that PHPUnit already provide a HTML report via its
\-\-cover\-html option which can be set in your builder (optional):
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBdir\fP (str): Directory where HTML report will be generated relative
to workspace. (required in \fIhtml\fP dict).
.UNINDENT
.IP \(bu 2
\fBarchive\fP (bool): Whether to archive HTML reports (default True).
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBmetric\-targets\fP (\fIlist\fP) \-\- 
.sp
List of metric targets to reach, must be one of
\fBhealthy\fP, \fBunhealthy\fP and \fBfailing\fP\&. Each metric target can takes
two parameters:
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBmethod\fP  Target for method coverage
.IP \(bu 2
\fBstatement\fP Target for statements coverage
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Whenever a metric target is not filled in, the Jenkins plugin can fill in
defaults for you (as of v0.3.3 of the plugin the healthy target will have
method: 70 and statement: 80 if both are left empty). Jenkins Job Builder
will mimic that feature to ensure clean configuration diff.

.UNINDENT
.UNINDENT
.sp
Minimal example:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Test for the defaults, only xml\-location is required
publishers:
 \- cloverphp:
       xml\-location: \(aqbuild/clover.xml\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Full example:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Exercise all options with non defaults values
publishers:
 \- cloverphp:
       xml\-location: \(aqbuild/clover.xml\(aq
       html:
         dir: \(aqhtml\(aq
         archive: false
       metric\-targets:
        \- healthy:
           method: 80
           statement: 90
        \- unhealthy:
           method: 40
           statement: 50
        \- failing:
           method: 10
           statement: 20

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B cobertura
Generate a cobertura coverage report.
Requires the Jenkins \fI\%Cobertura Coverage Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBreport\-file\fP (\fIstr\fP) \-\- This is a file name pattern that can be used
to locate the cobertura xml report files (optional)
.IP \(bu 2
\fBonly\-stable\fP (\fIbool\fP) \-\- Include only stable builds (default false)
.IP \(bu 2
\fBfail\-no\-reports\fP (\fIbool\fP) \-\- fail builds if no coverage reports are found
(default false)
.IP \(bu 2
\fBfail\-unhealthy\fP (\fIbool\fP) \-\- Unhealthy projects will be failed
(default false)
.IP \(bu 2
\fBfail\-unstable\fP (\fIbool\fP) \-\- Unstable projects will be failed (default false)
.IP \(bu 2
\fBhealth\-auto\-update\fP (\fIbool\fP) \-\- Auto update threshold for health on
successful build (default false)
.IP \(bu 2
\fBstability\-auto\-update\fP (\fIbool\fP) \-\- Auto update threshold for stability on
successful build (default false)
.IP \(bu 2
\fBzoom\-coverage\-chart\fP (\fIbool\fP) \-\- Zoom the coverage chart and crop area below
the minimum and above the maximum coverage
of the past reports (default false)
.IP \(bu 2
\fBsource\-encoding\fP (\fIstr\fP) \-\- Override the source encoding (default ASCII)
.IP \(bu 2
\fBtargets\fP (\fIdict\fP) \-\- .INDENT 2.0
.TP
.B targets
(packages, files, classes, method, line, conditional)
.INDENT 7.0
.IP \(bu 2
\fBhealthy\fP (\fIint\fP): Healthy threshold (default 0)
.IP \(bu 2
\fBunhealthy\fP (\fIint\fP): Unhealthy threshold (default 0)
.IP \(bu 2
\fBfailing\fP (\fIint\fP): Failing threshold (default 0)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- cobertura:
       report\-file: "/reports/cobertura/coverage.xml"
       only\-stable: "true"
       fail\-no\-reports: "true"
       fail\-unhealthy: "true"
       fail\-unstable: "true"
       health\-auto\-update: "true"
       stability\-auto\-update: "true"
       zoom\-coverage\-chart: "true"
       source\-encoding: "Big5"
       targets:
            \- files:
                healthy: 10
                unhealthy: 20
                failing: 30
            \- method:
                healthy: 50
                unhealthy: 40
                failing: 30
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B copy\-to\-master
Copy files to master from slave
Requires the Jenkins \fI\%Copy To Slave Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBincludes\fP (\fIlist\fP) \-\- list of file patterns to copy
.IP \(bu 2
\fBexcludes\fP (\fIlist\fP) \-\- list of file patterns to exclude
.IP \(bu 2
\fBdestination\fP (\fIstring\fP) \-\- absolute path into which the files will be copied.
If left blank they will be copied into the
workspace of the current job
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- copy\-to\-master:
      includes:
        \- file1
        \- file2*.txt
      excludes:
        \- file2bad.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B coverage
WARNING: The coverage function is deprecated. Instead, use the
cobertura function to generate a cobertura coverage report.
Requires the Jenkins \fI\%Cobertura Coverage Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- coverage
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B cppcheck
Cppcheck result publisher
Requires the Jenkins \fI\%Cppcheck Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBpattern\fP (\fIstr\fP) \-\- file pattern for cppcheck xml report
.UNINDENT
.sp
for more optional parameters see the example
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- cppcheck:
      pattern: "**/cppcheck.xml"
      # the rest is optional
      # build status (new) error count thresholds
      thresholds:
        unstable: 5
        new\-unstable: 5
        failure: 7
        new\-failure: 3
        # severities which count towards the threshold, default all true
        severity:
          error: true
          warning: true
          information: false
      graph:
        xysize: [500, 200]
        # which errors to display, default only sum
        display:
          sum: false
          error: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B description\-setter
This plugin sets the description for each build,
based upon a RegEx test of the build log file.
.sp
Requires the Jenkins \fI\%Description Setter Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBregexp\fP (\fIstr\fP) \-\- A RegEx which is used to scan the build log file
.IP \(bu 2
\fBregexp\-for\-failed\fP (\fIstr\fP) \-\- A RegEx which is used for failed builds
(optional)
.IP \(bu 2
\fBdescription\fP (\fIstr\fP) \-\- The description to set on the build (optional)
.IP \(bu 2
\fBdescription\-for\-failed\fP (\fIstr\fP) \-\- The description to set on
the failed builds (optional)
.IP \(bu 2
\fBset\-for\-matrix\fP (\fIbool\fP) \-\- Also set the description on
a multi\-configuration build (Default False)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- description\-setter:
      regexp: ".*(<a href=.*a>)"
      regexp\-for\-failed: ".*(<a href=.*a>)"
      description: "some description"
      description\-for\-failed: "another description"
      set\-for\-matrix: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B doxygen
This plugin parses the Doxygen descriptor (Doxyfile) and provides a link to
the generated Doxygen documentation.
.sp
Requires the Jenkins \fI\%Doxygen Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBdoxyfile\fP (\fIstr\fP) \-\- The doxyfile path
.IP \(bu 2
\fBkeepall\fP (\fIbool\fP) \-\- Retain doxygen generation for each successful build
(default: false)
.IP \(bu 2
\fBfolder\fP (\fIstr\fP) \-\- Folder where you run doxygen (default: \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- doxygen:
      doxyfile: "Doxyfile"
      keepall: false
      folder: "build"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B email
Email notifications on build failure.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBrecipients\fP (\fIstr\fP) \-\- Recipient email addresses
.IP \(bu 2
\fBnotify\-every\-unstable\-build\fP (\fIbool\fP) \-\- Send an email for every
unstable build (default true)
.IP \(bu 2
\fBsend\-to\-individuals\fP (\fIbool\fP) \-\- Send an email to the individual
who broke the build (default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- email:
      recipients: breakage@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B email\-ext
Extend Jenkin\(aqs built in email notification
Requires the Jenkins \fI\%Email\-ext Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBrecipients\fP (\fIstr\fP) \-\- Comma separated list of emails
.IP \(bu 2
\fBreply\-to\fP (\fIstr\fP) \-\- Comma separated list of emails that should be in
the Reply\-To header for this project (default $DEFAULT_REPLYTO)
.IP \(bu 2
\fBcontent\-type\fP (\fIstr\fP) \-\- The content type of the emails sent. If not set, the
Jenkins plugin uses the value set on the main configuration page.
Possible values: \(aqhtml\(aq, \(aqtext\(aq or \(aqdefault\(aq (default \(aqdefault\(aq)
.IP \(bu 2
\fBsubject\fP (\fIstr\fP) \-\- Subject for the email, can include variables like
${BUILD_NUMBER} or even groovy or javascript code
.IP \(bu 2
\fBbody\fP (\fIstr\fP) \-\- Content for the body of the email, can include variables
like ${BUILD_NUMBER}, but the real magic is using groovy or
javascript to hook into the Jenkins API itself
.IP \(bu 2
\fBattach\-build\-log\fP (\fIbool\fP) \-\- Include build log in the email (default false)
.IP \(bu 2
\fBattachments\fP (\fIstr\fP) \-\- pattern of files to include as attachment (optional)
.IP \(bu 2
\fBalways\fP (\fIbool\fP) \-\- Send an email for every result (default false)
.IP \(bu 2
\fBunstable\fP (\fIbool\fP) \-\- Send an email for an unstable result (default false)
.IP \(bu 2
\fBfirst\-failure\fP (\fIbool\fP) \-\- Send an email for just the first failure
(default false)
.IP \(bu 2
\fBnot\-built\fP (\fIbool\fP) \-\- Send an email if not built (default false)
.IP \(bu 2
\fBaborted\fP (\fIbool\fP) \-\- Send an email if the build is aborted (default false)
.IP \(bu 2
\fBregression\fP (\fIbool\fP) \-\- Send an email if there is a regression
(default false)
.IP \(bu 2
\fBfailure\fP (\fIbool\fP) \-\- Send an email if the build fails (default true)
.IP \(bu 2
\fBsecond\-failure\fP (\fIbool\fP) \-\- Send an email for the second failure
(default false)
.IP \(bu 2
\fBimprovement\fP (\fIbool\fP) \-\- Send an email if the build improves (default false)
.IP \(bu 2
\fBstill\-failing\fP (\fIbool\fP) \-\- Send an email if the build is still failing
(default false)
.IP \(bu 2
\fBsuccess\fP (\fIbool\fP) \-\- Send an email for a successful build (default false)
.IP \(bu 2
\fBfixed\fP (\fIbool\fP) \-\- Send an email if the build is fixed (default false)
.IP \(bu 2
\fBstill\-unstable\fP (\fIbool\fP) \-\- Send an email if the build is still unstable
(default false)
.IP \(bu 2
\fBpre\-build\fP (\fIbool\fP) \-\- Send an email before the build (default false)
.IP \(bu 2
\fBpresend\-script\fP (\fIstr\fP) \-\- A Groovy script executed prior sending the mail.
(default \(aq\(aq)
.IP \(bu 2
\fBmatrix\-trigger\fP (\fIstr\fP) \-\- 
.sp
If using matrix projects, when to trigger
.INDENT 2.0
.TP
.B matrix\-trigger values
.INDENT 7.0
.IP \(bu 2
\fBboth\fP
.IP \(bu 2
\fBonly\-parent\fP
.IP \(bu 2
\fBonly\-configurations\fP
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBsend\-to\fP (\fIlist\fP) \-\- 
.sp
list of recipients from the predefined groups
.INDENT 2.0
.TP
.B send\-to values
.INDENT 7.0
.IP \(bu 2
\fBdevelopers\fP (disabled by default)
.IP \(bu 2
\fBrequester\fP (disabled by default)
.IP \(bu 2
\fBculprits\fP (disabled by default)
.IP \(bu 2
\fBrecipients\fP (enabled by default)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- email\-ext:
      recipients: foo@example.com, bar@example.com
      reply\-to: foo@example.com
      content\-type: html
      subject: Subject for Build ${BUILD_NUMBER}
      body: The build has finished
      attach\-build\-log: false
      attachments: "*/foo*.log"
      always: true
      unstable: true
      first\-failure: true
      not\-built: true
      aborted: true
      regression: true
      failure: true
      second\-failure: true
      improvement: true
      still\-failing: true
      success: true
      fixed: true
      still\-unstable: true
      pre\-build: true
      matrix\-trigger: only\-configurations
      presend\-script: "cancel=true"
      send\-to:
        \- developers
        \- requester
        \- culprits
        \- recipients

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B emotional\-jenkins
Emotional Jenkins.
Requires the Jenkins \fI\%Emotional Jenkins Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- emotional\-jenkins

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B fingerprint
Fingerprint files to track them across builds
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBfiles\fP (\fIstr\fP) \-\- files to fingerprint, follows the @includes of Ant fileset
(default blank)
.IP \(bu 2
\fBrecord\-artifacts\fP (\fIbool\fP) \-\- fingerprint all archived artifacts
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- fingerprint:
      files: builddir/test*.xml
      record\-artifacts: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B fitnesse
Publish Fitnesse test results
.sp
Requires the Jenkins \fI\%Fitnesse plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBresults\fP (\fIstr\fP) \-\- path specifier for results files
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- fitnesse:
      results: "fitnesse\-results/**/*.xml"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ftp
Upload files via FTP.
Requires the Jenkins \fI\%Publish over FTP Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBsite\fP (\fIstr\fP) \-\- name of the ftp site
.IP \(bu 2
\fBtarget\fP (\fIstr\fP) \-\- destination directory
.IP \(bu 2
\fBtarget\-is\-date\-format\fP (\fIbool\fP) \-\- whether target is a date format. If true,
raw text should be quoted (default false)
.IP \(bu 2
\fBclean\-remote\fP (\fIbool\fP) \-\- should the remote directory be deleted before
transferring files (default false)
.IP \(bu 2
\fBsource\fP (\fIstr\fP) \-\- source path specifier
.IP \(bu 2
\fBexcludes\fP (\fIstr\fP) \-\- excluded file pattern (optional)
.IP \(bu 2
\fBremove\-prefix\fP (\fIstr\fP) \-\- prefix to remove from uploaded file paths
(optional)
.IP \(bu 2
\fBfail\-on\-error\fP (\fIbool\fP) \-\- fail the build if an error occurs (default false).
.IP \(bu 2
\fBflatten\fP (\fIbool\fP) \-\- only create files on the server, don\(aqt create
directories (default false).
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
\- ftp:
    site: \(aqftp.example.com\(aq
    target: \(aqdest/dir\(aq
    source: \(aqbase/source/dir/**\(aq
    remove\-prefix: \(aqbase/source/dir\(aq
    excludes: \(aq**/*.excludedfiletype\(aq
    flatten: true


.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B git
This plugin will configure the Jenkins Git plugin to
push merge results, tags, and/or branches to
remote repositories after the job completes.
.sp
Requires the Jenkins \fI\%Git Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpush\-merge\fP (\fIbool\fP) \-\- push merges back to the origin specified in the
pre\-build merge options (Default: False)
.IP \(bu 2
\fBpush\-only\-if\-success\fP (\fIbool\fP) \-\- Only push to remotes if the build succeeds
\- otherwise, nothing will be pushed.
(Default: True)
.IP \(bu 2
\fBtags\fP (\fIlist\fP) \-\- 
.sp
tags to push at the completion of the build
.INDENT 2.0
.TP
.B tag
.INDENT 7.0
.IP \(bu 2
\fBremote\fP (\fIstr\fP) remote repo name to push to
(Default: \(aqorigin\(aq)
.IP \(bu 2
\fBname\fP (\fIstr\fP) name of tag to push
.IP \(bu 2
\fBmessage\fP (\fIstr\fP) message content of the tag
.IP \(bu 2
\fBcreate\-tag\fP (\fIbool\fP) whether or not to create the tag
after the build, if this is False then the tag needs to
exist locally (Default: False)
.IP \(bu 2
\fBupdate\-tag\fP (\fIbool\fP) whether to overwrite a remote tag
or not (Default: False)
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBbranches\fP (\fIlist\fP) \-\- 
.sp
branches to push at the completion of the build
.INDENT 2.0
.TP
.B branch
.INDENT 7.0
.IP \(bu 2
\fBremote\fP (\fIstr\fP) remote repo name to push to
(Default: \(aqorigin\(aq)
.IP \(bu 2
\fBname\fP (\fIstr\fP) name of remote branch to push to
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBnotes\fP (\fIlist\fP) \-\- 
.sp
notes to push at the completion of the build
.INDENT 2.0
.TP
.B note
.INDENT 7.0
.IP \(bu 2
\fBremote\fP (\fIstr\fP) remote repo name to push to
(Default: \(aqorigin\(aq)
.IP \(bu 2
\fBmessage\fP (\fIstr\fP) content of the note
.IP \(bu 2
\fBnamespace\fP (\fIstr\fP) namespace of the note
(Default: master)
.IP \(bu 2
\fBreplace\-note\fP (\fIbool\fP) whether to overwrite a note or not
(Default: False)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- git:
        push\-merge: true
        push\-only\-if\-success: false
        tags:
            \- tag:
                remote: tagremotename
                name: tagname
                message: "some tag message"
                create\-tag: true
                update\-tag: true
        branches:
            \- branch:
                remote: branchremotename
                name: "some/branch"
        notes:
            \- note:
                remote: remotename
                message: "some note to push"
                namespace: commits
                replace\-note: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B github\-notifier
Set build status on Github commit.
Requires the Jenkins \fI\%Github Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- github\-notifier

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B groovy\-postbuild
Execute a groovy script.
Requires the Jenkins \fI\%Groovy Postbuild Plugin\fP
.INDENT 7.0
.TP
.B Parameter
the groovy script to execute
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- groovy\-postbuild: "manager.buildFailure()"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B html\-publisher
This plugin publishes HTML reports.
.sp
Requires the Jenkins \fI\%HTML Publisher Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- Report name
.IP \(bu 2
\fBdir\fP (\fIstr\fP) \-\- HTML directory to archive
.IP \(bu 2
\fBfiles\fP (\fIstr\fP) \-\- Specify the pages to display
.IP \(bu 2
\fBkeep\-all\fP (\fIbool\fP) \-\- keep HTML reports for each past build (Default False)
.IP \(bu 2
\fBallow\-missing\fP (\fIbool\fP) \-\- Allow missing HTML reports (Default False)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- html\-publisher:
        name: "some name"
        dir: "path/"
        files: "index.html"
        keep\-all: true
        allow\-missing: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ircbot
ircbot enables Jenkins to send build notifications via IRC and lets you
interact with Jenkins via an IRC bot.
.sp
Requires the Jenkins \fI\%IRC Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBstrategy\fP (\fIstring\fP) \-\- 
.sp
When to send notifications
.INDENT 2.0
.TP
.B strategy values
.INDENT 7.0
.IP \(bu 2
\fBall\fP always (default)
.IP \(bu 2
\fBany\-failure\fP on any failure_and_fixed
.IP \(bu 2
\fBfailure\-and\-fixed\fP on failure and fixes
.IP \(bu 2
\fBnew\-failure\-and\-fixed\fP on new failure and fixes
.IP \(bu 2
\fBstatechange\-only\fP only on state change
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBnotify\-start\fP (\fIbool\fP) \-\- Whether to send notifications to channels when a
build starts
(default: false)
.IP \(bu 2
\fBnotify\-committers\fP (\fIbool\fP) \-\- Whether to send notifications to the users
that are suspected of having broken this build
(default: false)
.IP \(bu 2
\fBnotify\-culprits\fP (\fIbool\fP) \-\- Also send notifications to \(aqculprits\(aq from
previous unstable/failed builds
(default: false)
.IP \(bu 2
\fBnotify\-upstream\fP (\fIbool\fP) \-\- Whether to send notifications to upstream
committers if no committers were found for a
broken build
(default: false)
.IP \(bu 2
\fBnotify\-fixers\fP (\fIbool\fP) \-\- Whether to send notifications to the users that
have fixed a broken build
(default: false)
.IP \(bu 2
\fBmessage\-type\fP (\fIstring\fP) \-\- 
.sp
Channel Notification Message.
.INDENT 2.0
.TP
.B message\-type values
.INDENT 7.0
.IP \(bu 2
\fBsummary\-scm\fP for summary and SCM changes (default)
.IP \(bu 2
\fBsummary\fP for summary only
.IP \(bu 2
\fBsummary\-params\fP for summary and build parameters
.IP \(bu 2
\fBsummary\-scm\-fail\fP for summary, SCM changes, failures)
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBchannels\fP (\fIlist\fP) \-\- .INDENT 2.0
.TP
.B list channels definitions
If empty, it takes channel from Jenkins configuration.
(default: empty)
WARNING: the IRC plugin requires the channel to be
configured in the system wide configuration or the jobs
will fail to emit notifications to the channel
.UNINDENT
.INDENT 2.0
.TP
.B Channel
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) Channel name
.IP \(bu 2
\fBpassword\fP (\fIstr\fP) Channel password (optional)
.IP \(bu 2
\fBnotify\-only\fP (\fIbool\fP) Set to true if you want to
disallow bot commands (default: false)
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBmatrix\-notifier\fP (\fIstring\fP) \-\- .INDENT 2.0
.TP
.B notify for matrix projects
instant\-messaging\-plugin injects an additional
field in the configuration form whenever the
project is a multi\-configuration project
.UNINDENT
.INDENT 2.0
.TP
.B matrix\-notifier values
.INDENT 7.0
.IP \(bu 2
\fBall\fP
.IP \(bu 2
\fBonly\-configurations\fP (default)
.IP \(bu 2
\fBonly\-parent\fP
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- ircbot:
      strategy: all
      notify\-start: false
      notify\-committers: false
      notify\-culprits: false
      notify\-upstream: false
      notify\-fixers: false
      message\-type: summary\-scm
      channels:
          \- name: \(aq#jenkins\-channel1\(aq
            password: secrete
            notify\-only: false
          \- name: \(aq#jenkins\-channel2\(aq
            notify\-only: true
      matrix\-notifier: only\-configurations

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B jabber
Integrates Jenkins with the Jabber/XMPP instant messaging protocol
Requires the Jenkins \fI\%Jabber Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBnotify\-on\-build\-start\fP (\fIbool\fP) \-\- Whether to send notifications
to channels when a build starts (default false)
.IP \(bu 2
\fBnotify\-scm\-committers\fP (\fIbool\fP) \-\- Whether to send notifications
to the users that are suspected of having broken this build
(default false)
.IP \(bu 2
\fBnotify\-scm\-culprits\fP (\fIbool\fP) \-\- Also send notifications to \(aqculprits\(aq
from previous unstable/failed builds (default false)
.IP \(bu 2
\fBnotify\-upstream\-committers\fP (\fIbool\fP) \-\- Whether to send notifications to
upstream committers if no committers were found for a broken build
(default false)
.IP \(bu 2
\fBnotify\-scm\-fixers\fP (\fIbool\fP) \-\- Whether to send notifications to the users
that have fixed a broken build (default false)
.IP \(bu 2
\fBgroup\-targets\fP (\fIlist\fP) \-\- List of group targets to notify
.IP \(bu 2
\fBindividual\-targets\fP (\fIlist\fP) \-\- List of individual targets to notify
.IP \(bu 2
\fBstrategy\fP (\fIdict\fP) \-\- 
.sp
When to send notifications (default all)
.INDENT 2.0
.TP
.B strategy values
.INDENT 7.0
.IP \(bu 2
\fBall\fP \-\- Always
.IP \(bu 2
\fBfailure\fP \-\- On any failure
.IP \(bu 2
\fBfailure\-fixed\fP \-\- On failure and fixes
.IP \(bu 2
\fBchange\fP \-\- Only on state change
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBmessage\fP (\fIdict\fP) \-\- 
.sp
Channel notification message (default summary\-scm)
.INDENT 2.0
.TP
.B message  values
.INDENT 7.0
.IP \(bu 2
\fBsummary\-scm\fP \-\- Summary + SCM changes
.IP \(bu 2
\fBsummary\fP \-\- Just summary
.IP \(bu 2
\fBsummary\-build\fP \-\- Summary and build parameters
.IP \(bu 2
\fBsummary\-scm\-fail\fP \-\- Summary, SCM changes, and failed tests
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- jabber:
      notify\-on\-build\-start: true
      group\-targets:
        \- "foo\-room@conference\-2\-fooserver.foo.com"
      individual\-targets:
        \- "foo\-user@conference\-2\-fooserver.foo.com"
      strategy: all
      message: summary\-scm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B jacoco
Generate a JaCoCo coverage report.
Requires the Jenkins \fI\%JaCoCo Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBexec\-pattern\fP (\fIstr\fP) \-\- This is a file name pattern that can be used to
locate the jacoco report files (default
\fB**/**.exec\fP)
.IP \(bu 2
\fBclass\-pattern\fP (\fIstr\fP) \-\- This is a file name pattern that can be used
to locate class files (default \fB**/classes\fP)
.IP \(bu 2
\fBsource\-pattern\fP (\fIstr\fP) \-\- This is a file name pattern that can be used
to locate source files (default \fB**/src/main/java\fP)
.IP \(bu 2
\fBupdate\-build\-status\fP (\fIbool\fP) \-\- Update the build according to the results
(default False)
.IP \(bu 2
\fBinclusion\-pattern\fP (\fIstr\fP) \-\- This is a file name pattern that can be used
to include certain class files (optional)
.IP \(bu 2
\fBexclusion\-pattern\fP (\fIstr\fP) \-\- This is a file name pattern that can be used
to exclude certain class files (optional)
.IP \(bu 2
\fBtargets\fP (\fIdict\fP) \-\- .INDENT 2.0
.TP
.B targets
(instruction, branch, complexity, line, method, class)
.INDENT 7.0
.IP \(bu 2
\fBhealthy\fP (\fIint\fP): Healthy threshold (default 0)
.IP \(bu 2
\fBunhealthy\fP (\fIint\fP): Unhealthy threshold (default 0)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- jacoco:
      exec\-pattern: "**/**.exec"
      class\-pattern: "**/classes"
      source\-pattern: "**/src/main/java"
      status\-update: true
      targets:
        \- branch:
            healthy: 10
            unhealthy: 20
        \- method:
            healthy: 50
            unhealthy: 40
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B jira
Update relevant JIRA issues
Requires the Jenkins \fI\%JIRA Plugin\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- jira
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B join\-trigger
Trigger a job after all the immediate downstream jobs have completed
.INDENT 7.0
.TP
.B Parameters
\fBprojects\fP (\fIlist\fP) \-\- list of projects to trigger
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- join\-trigger:
      projects:
        \- project\-one
        \- project\-two
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B junit
Publish JUnit test results.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBresults\fP (\fIstr\fP) \-\- results filename
.IP \(bu 2
\fBkeep\-long\-stdio\fP (\fIbool\fP) \-\- Retain long standard output/error in test
results (default true).
.IP \(bu 2
\fBtest\-stability\fP (\fIbool\fP) \-\- Add historical information about test
results stability (default false).
Requires the Jenkins \fI\%Test stability Plugin\fP\&.
.UNINDENT
.UNINDENT
.sp
Minimal example using defaults:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
\- junit:
    results: nosetests.xml

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Full example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
\- junit:
    results: nosetests\-example.xml
    keep\-long\-stdio: false
    test\-stability: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B logparser
Requires the Jenkins \fI\%Log Parser Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBparse\-rules\fP (\fIstr\fP) \-\- full path to parse rules
.IP \(bu 2
\fBunstable\-on\-warning\fP (\fIbool\fP) \-\- mark build unstable on warning
.IP \(bu 2
\fBfail\-on\-error\fP (\fIbool\fP) \-\- mark build failed on error
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- logparser:
      parse\-rules: "/path/to/parserules"
      unstable\-on\-warning: true
      fail\-on\-error: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B maven\-deploy
Deploy artifacts to Maven repository.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBid\fP (\fIstr\fP) \-\- Repository ID
.IP \(bu 2
\fBurl\fP (\fIstr\fP) \-\- Repository URL
.IP \(bu 2
\fBunique\-version\fP (\fIbool\fP) \-\- Assign unique versions to snapshots
(default true)
.IP \(bu 2
\fBdeploy\-unstable\fP (\fIbool\fP) \-\- Deploy even if the build is unstable
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- maven\-deploy:
      id: example
      url: http://repo.example.com/maven2/
      unique\-version: true
      deploy\-unstable: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B performance
Publish performance test results from jmeter and junit.
Requires the Jenkins \fI\%Performance Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBfailed\-threshold\fP (\fIint\fP) \-\- Specify the error percentage threshold that
set the build failed. A negative value means
don\(aqt use this threshold (default 0)
.IP \(bu 2
\fBunstable\-threshold\fP (\fIint\fP) \-\- Specify the error percentage threshold that
set the build unstable. A negative value means
don\(aqt use this threshold (default 0)
.IP \(bu 2
\fBreport\fP (\fIdict\fP) \-\- .INDENT 2.0
.TP
.B (jmeter or junit)
(\fIdict\fP or \fIstr\fP): Specify a custom report file
(optional; jmeter default **/\fI\&.jtl, junit default *\fP/TEST\-*.xml)
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- performance:
      failed\-threshold: 85
      unstable\-threshold: \-1
      report:
         \- jmeter: "/special/file.jtl"
         \- junit: "/special/file.xml"

publishers:
  \- performance:
      failed\-threshold: 85
      unstable\-threshold: \-1
      report:
         \- jmeter
         \- junit

publishers:
  \- performance:
      failed\-threshold: 85
      unstable\-threshold: \-1
      report:
         \- jmeter: "/special/file.jtl"
         \- junit: "/special/file.xml"
         \- jmeter
         \- junit
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B pipeline
Specify a downstream project in a pipeline.
Requires the Jenkins \fI\%Build Pipeline Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBproject\fP (\fIstr\fP) \-\- the name of the downstream project
.IP \(bu 2
\fBpredefined\-parameters\fP (\fIstr\fP) \-\- parameters to pass to the other
job (optional)
.IP \(bu 2
\fBcurrent\-parameters\fP (\fIbool\fP) \-\- Whether to include the parameters passed
to the current build to the triggered job (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- pipeline:
      project: test_project
      current\-parameters: true
      predefined\-parameters: foo=bar

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can build pipeline jobs that are re\-usable in different pipelines by
using a \fIjob\-template\fP to define the pipeline jobs,
and variable substitution to specify the name of
the downstream job in the pipeline.
Job\-specific substitutions are useful here (see \fIproject\fP).
.sp
See \(aqsamples/pipeline.yaml\(aq for an example pipeline implementation.
.UNINDENT
.INDENT 0.0
.TP
.B plot
Plot provides generic plotting (or graphing).
.sp
Requires the Jenkins \fI\%Plot Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBtitle\fP (\fIstr\fP) \-\- title for the graph
(default: \(aq\(aq)
.IP \(bu 2
\fByaxis\fP (\fIstr\fP) \-\- title of Y axis
.IP \(bu 2
\fBgroup\fP (\fIstr\fP) \-\- name of the group to which the plot belongs
.IP \(bu 2
\fBnum\-builds\fP (\fIint\fP) \-\- number of builds to plot across
(default: plot all builds)
.IP \(bu 2
\fBstyle\fP (\fIstr\fP) \-\- Specifies the graph style of the plot
Can be: area, bar, bar3d, line, line3d, stackedArea,
stackedbar, stackedbar3d, waterfall
(default: \(aqline\(aq)
.IP \(bu 2
\fBuse\-description\fP (\fIbool\fP) \-\- When false, the X\-axis labels are formed
using build numbers and dates, and the
corresponding tooltips contain the build
descriptions. When enabled, the contents of
the labels and tooltips are swapped, with the
descriptions used as X\-axis labels and the
build number and date used for tooltips.
(default: False)
.IP \(bu 2
\fBcsv\-file\-name\fP (\fIstr\fP) \-\- Use for choosing the file name in which the data
will be persisted. If none specified and random
name is generated as done in the Jenkins Plot
plugin.
(default: random generated .csv filename, same
behaviour as the Jenkins Plot plugin)
.IP \(bu 2
\fBseries\fP (\fIlist\fP) \-\- 
.sp
list data series definitions
.INDENT 2.0
.TP
.B Serie
.INDENT 7.0
.IP \(bu 2
\fBfile\fP (\fIstr\fP) : files to include
.IP \(bu 2
\fBinclusion\-flag\fP filtering mode for CSV files. Possible
values are:
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBoff\fP (default)
.IP \(bu 2
\fBinclude\-by\-string\fP
.IP \(bu 2
\fBexclude\-by\-string\fP
.IP \(bu 2
\fBinclude\-by\-column\fP
.IP \(bu 2
\fBexclude\-by\-column\fP
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
\fBexclude\fP (\fIstr\fP) : exclude pattern for CSV file.
.IP \(bu 2
\fBurl\fP (\fIstr\fP) : for \(aqcsv\(aq and \(aqxml\(aq file types
used when you click on a point (default: empty)
.IP \(bu 2
\fBdisplay\-table\fP (\fIbool\fP) : for \(aqcsv\(aq file type
if true, original CSV will be shown above plot (default: False)
.IP \(bu 2
\fBlabel\fP (\fIstr\fP) : used by \(aqproperties\(aq file type
Specifies the legend label for this data series.
(default: empty)
.IP \(bu 2
\fBformat\fP (\fIstr\fP) : Type of file where we get datas.
Can be: properties, csv, xml
.IP \(bu 2
\fBxpath\-type\fP (\fIstr\fP) : The result type of the expression must
be supplied due to limitations in the java.xml.xpath parsing.
The result can be: node, nodeset, boolean, string, or number.
Strings and numbers will be converted to double. Boolean will
be converted to 1 for true, and 0 for false. (default: \(aqnode\(aq)
.IP \(bu 2
\fBxpath\fP (\fIstr\fP) : used by \(aqxml\(aq file type
Xpath which selects the values that should be plotted.
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- plot:
      \- title: MyPlot
        yaxis: Y
        group: PlotGroup
        num\-builds: \(aq\(aq
        style: line
        use\-description: false
        series:
            \- file: graph\-me\-second.properties
              label: MyLabel
              format: properties
            \- file: graph\-me\-first.csv
              url: \(aqhttp://srv1\(aq
              inclusion\-flag: \(aqoff\(aq
              display\-table: true
              format: csv
      \- title: MyPlot2
        yaxis: Y
        group: PlotGroup
        style: line
        use\-description: false
        series:
            \- file: graph\-me\-third.xml
              url: \(aqhttp://srv2\(aq
              format: xml
              xpath\-type: \(aqnode\(aq
              xpath: \(aq/*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B pmd
Publish trend reports with PMD.
Requires the Jenkins \fI\%PMD Plugin.\fP
.sp
The PMD component accepts a dictionary with the following values:
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP (\fIstr\fP) \-\- Report filename pattern (optional)
.IP \(bu 2
\fBcan\-run\-on\-failed\fP (\fIbool\fP) \-\- Also runs for failed builds, instead of just
stable or unstable builds (default false)
.IP \(bu 2
\fBshould\-detect\-modules\fP (\fIbool\fP) \-\- Determines if Ant or Maven modules should
be detected for all files that contain warnings (default false)
.IP \(bu 2
\fBhealthy\fP (\fIint\fP) \-\- Sunny threshold (optional)
.IP \(bu 2
\fBunhealthy\fP (\fIint\fP) \-\- Stormy threshold (optional)
.IP \(bu 2
\fBhealth\-threshold\fP (\fIstr\fP) \-\- Threshold priority for health status
(\(aqlow\(aq, \(aqnormal\(aq or \(aqhigh\(aq, defaulted to \(aqlow\(aq)
.IP \(bu 2
\fBthresholds\fP (\fIdict\fP) \-\- 
.sp
Mark build as failed or unstable if the number of
errors exceeds a threshold. (optional)
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.TP
.B thresholds
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBunstable\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B unstable
.INDENT 7.0
.IP \(bu 2
\fBtotal\-all\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-high\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-normal\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-low\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-all\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-high\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-normal\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-low\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBfailed\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B failed
.INDENT 7.0
.IP \(bu 2
\fBtotal\-all\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-high\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-normal\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-low\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-all\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-high\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-normal\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-low\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBdefault\-encoding\fP (\fIstr\fP) \-\- Encoding for parsing or showing files (optional)
.IP \(bu 2
\fBdo\-not\-resolve\-relative\-paths\fP (\fIbool\fP) \-\- (default false)
.IP \(bu 2
\fBdont\-compute\-new\fP (\fIbool\fP) \-\- If set to false, computes new warnings based on
the reference build (default true)
.IP \(bu 2
\fBuse\-stable\-build\-as\-reference\fP (\fIbool\fP) \-\- The number of new warnings will be
calculated based on the last stable build, allowing reverts of unstable
builds where the number of warnings was decreased. (default false)
.IP \(bu 2
\fBuse\-delta\-values\fP (\fIbool\fP) \-\- If set then the number of new warnings is
calculated by subtracting the total number of warnings of the current
build from the reference build.
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
 \- pmd:
    pattern: \(aq**/pmd\-result.xml\(aq
    healthy: 0
    unhealthy: 100
    health\-threshold: \(aqhigh\(aq
    thresholds:
        unstable:
            total\-high: 10
        failed:
            total\-high: 1

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Full example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
 \- pmd:
    pattern: \(aq**/pmd\-result.xml\(aq
    can\-run\-on\-failed: true
    should\-detect\-modules: true
    healthy: 0
    unhealthy: 100
    health\-threshold: \(aqhigh\(aq
    thresholds:
        unstable:
            total\-all: 90
            total\-high: 80
            total\-normal: 70
            total\-low: 60
        failed:
            total\-all: 90
            total\-high: 80
            total\-normal: 70
            total\-low: 60
    default\-encoding: \(aqutf\-8\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B post\-tasks
Adds support to post build task plugin
.sp
Requires the Jenkins \fI\%Post Build Task plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBtask\fP (\fIdict\fP) \-\- Post build task definition
.IP \(bu 2
\fBtask[matches]\fP (\fIlist\fP) \-\- list of matches when to run the task
.IP \(bu 2
\fBtask[matches][*]\fP (\fIdict\fP) \-\- match definition
.IP \(bu 2
\fBtask[matches][*][log\-text]\fP (\fIstr\fP) \-\- text to match against the log
.IP \(bu 2
\fBtask[matches][*][operator]\fP (\fIstr\fP) \-\- 
.sp
operator to apply with the next match
.INDENT 2.0
.TP
.B task[matches][*][operator] values (default \(aqAND\(aq)
.INDENT 7.0
.IP \(bu 2
\fBAND\fP
.IP \(bu 2
\fBOR\fP
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBtask[escalate\-status]\fP (\fIbool\fP) \-\- Escalate the task status to the job
(default \(aqfalse\(aq)
.IP \(bu 2
\fBtask[run\-if\-job\-successful]\fP (\fIbool\fP) \-\- Run only if the job was successful
(default \(aqfalse\(aq)
.IP \(bu 2
\fBtask[script]\fP (\fIstr\fP) \-\- Shell script to run (default \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- post\-tasks:
        \- matches:
            \- log\-text: line to match
              operator: AND
            \- log\-text: line to match
              operator: OR
            \- log\-text: line to match
              operator: AND
          escalate\-status: false
          run\-if\-job\-successful:false
          script: |
            echo "Here goes the task script"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B postbuildscript
Executes additional builders, script or Groovy after the build is
complete.
.sp
Requires the Jenkins \fI\%Post Build Script plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBgeneric\-script\fP (\fIlist\fP) \-\- Paths to Batch/Shell scripts
.IP \(bu 2
\fBgroovy\-script\fP (\fIlist\fP) \-\- Paths to Groovy scripts
.IP \(bu 2
\fBgroovy\fP (\fIlist\fP) \-\- Inline Groovy
.IP \(bu 2
\fBbuilders\fP (\fIlist\fP) \-\- Any supported builders, see \fBbuilders\fP\&.
.IP \(bu 2
\fBonsuccess\fP (\fIbool\fP) \-\- Scripts and builders are run only if the build succeed
(default False)
.IP \(bu 2
\fBonfailure\fP (\fIbool\fP) \-\- Scripts and builders are run only if the build fail
(default True)
.IP \(bu 2
\fBexecute\-on\fP (\fIstr\fP) \-\- For matrix projects, scripts can be run after each
axis is built (\fIaxes\fP), after all axis of the matrix
are built (\fImatrix\fP) or after each axis AND the matrix
are built (\fIboth\fP).
.UNINDENT
.UNINDENT
.sp
The \fIonsuccess\fP and \fIonfailure\fP options are confusing. If you want
the post build to always run regardless of the build status, you
should set them both to \fIfalse\fP\&.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- postbuildscript:
        generic\-script:
            \- \(aq/tmp/one.sh\(aq
            \- \(aq/tmp/two.sh\(aq
        groovy\-script:
            \- \(aq/tmp/one.groovy\(aq
            \- \(aq/tmp/two.groovy\(aq
        groovy:
            \- "/** This is some inlined groovy */"
            \- "/** Some more inlined groovy */"
        onsuccess: False
        onfailure: True

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can also execute \fBbuilders\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- postbuildscript:
        builders:
            \- shell: \(aqecho "Shell execution"\(aq
            \- ant: \(aqant_target\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Run once after the whole matrix (all axes) is built:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- postbuildscript:
        execute\-on: \(aqmatrix\(aq
        builders:
            \- shell: \(aqecho "Shell execution"\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B robot
Adds support for the Robot Framework Plugin
.sp
Requires the Jenkins \fI\%Robot Framework Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBoutput\-path\fP (\fIstr\fP) \-\- Path to directory containing robot xml and html files
relative to build workspace. (default \(aq\(aq)
.IP \(bu 2
\fBlog\-file\-link\fP (\fIstr\fP) \-\- Name of log or report file to be linked on jobs
front page (default \(aq\(aq)
.IP \(bu 2
\fBreport\-html\fP (\fIstr\fP) \-\- Name of the html file containing robot test report
(default \(aqreport.html\(aq)
.IP \(bu 2
\fBlog\-html\fP (\fIstr\fP) \-\- Name of the html file containing detailed robot test log
(default \(aqlog.html\(aq)
.IP \(bu 2
\fBoutput\-xml\fP (\fIstr\fP) \-\- Name of the xml file containing robot output
(default \(aqoutput.xml\(aq)
.IP \(bu 2
\fBpass\-threshold\fP (\fIstr\fP) \-\- Minimum percentage of passed tests to consider
the build successful (default 0.0)
.IP \(bu 2
\fBunstable\-threshold\fP (\fIstr\fP) \-\- Minimum percentage of passed test to
consider the build as not failed (default 0.0)
.IP \(bu 2
\fBonly\-critical\fP (\fIbool\fP) \-\- Take only critical tests into account when
checking the thresholds (default true)
.IP \(bu 2
\fBother\-files\fP (\fIlist\fP) \-\- list other files to archive (default \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- publishers:
    \- robot:
        output\-path: reports/robot
        log\-file\-link: report.html
        report\-html: report.html
        log\-html: log.html
        output\-xml: output.xml
        pass\-threshold: 80.0
        unstable\-threshold: 60.0
        only\-critical: false
        other\-files:
            \- extra\-file1.html
            \- extra\-file2.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ruby\-metrics
Rcov plugin parses rcov html report files and
shows it in Jenkins with a trend graph.
.sp
Requires the Jenkins \fI\%Ruby metrics plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBreport\-dir\fP (\fIstr\fP) \-\- Relative path to the coverage report directory
.IP \(bu 2
\fBtargets\fP (\fIdict\fP) \-\- .INDENT 2.0
.TP
.B targets
(total\-coverage, code\-coverage)
.INDENT 7.0
.IP \(bu 2
\fBhealthy\fP (\fIint\fP): Healthy threshold
.IP \(bu 2
\fBunhealthy\fP (\fIint\fP): Unhealthy threshold
.IP \(bu 2
\fBunstable\fP (\fIint\fP): Unstable threshold
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- ruby\-metrics:
      report\-dir: "coverage/rcov"
      target:
        \- total\-coverage:
             healthy: 80
             unhealthy: 0
             unstable: 0
        \- code\-coverage:
             healthy: 80
             unhealthy: 0
             unstable: 0

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B scp
Upload files via SCP
Requires the Jenkins \fI\%SCP Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBsite\fP (\fIstr\fP) \-\- name of the scp site
.IP \(bu 2
\fBtarget\fP (\fIstr\fP) \-\- destination directory
.IP \(bu 2
\fBsource\fP (\fIstr\fP) \-\- source path specifier
.IP \(bu 2
\fBkeep\-hierarchy\fP (\fIbool\fP) \-\- keep the file hierarchy when uploading
(default false)
.IP \(bu 2
\fBcopy\-after\-failure\fP (\fIbool\fP) \-\- copy files even if the job fails
(default false)
.IP \(bu 2
\fBcopy\-console\fP (\fIbool\fP) \-\- copy the console log (default false); if
specified, omit \(aqtarget\(aq
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- scp:
      site: \(aqexample.com\(aq
      files:
        \- target: \(aqdest/dir\(aq
          source: \(aqbase/source/dir/**\(aq
          keep\-hierarchy: true
          copy\-after\-failure: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B sitemonitor
This plugin checks the availability of an url.
.sp
It requires the \fI\%sitemonitor plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBsites\fP (\fIlist\fP) \-\- List of URLs to check
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- sitemonitor:
      sites:
        \- url: http://foo.example.com
        \- url: http://bar.example.com:8080/

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B sloccount
Generates the trend report for SLOCCount
.sp
Requires the Jenkins \fI\%SLOCCount Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBreport\-files\fP (\fIstr\fP) \-\- Setting that specifies the generated raw
SLOCCount report files.
Be sure not to include any non\-report files into
this pattern. The report files must have been
generated by sloccount using the
"\-\-wide \-\-details" options.
(default: \(aq**/sloccount.sc\(aq)
.IP \(bu 2
\fBcharset\fP (\fIstr\fP) \-\- The character encoding to be used to read the SLOCCount
result files. (default: \(aqUTF\-8\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- sloccount:
      report\-files: sloccount.sc
      charset: UTF\-8
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B sonar
Sonar plugin support.
Requires the Jenkins \fI\%Sonar Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBjdk\fP (\fIstr\fP) \-\- JDK to use (inherited from the job if omitted). (optional)
.IP \(bu 2
\fBbranch\fP (\fIstr\fP) \-\- branch onto which the analysis will be posted (optional)
.IP \(bu 2
\fBlanguage\fP (\fIstr\fP) \-\- source code language (optional)
.IP \(bu 2
\fBmaven\-opts\fP (\fIstr\fP) \-\- options given to maven (optional)
.IP \(bu 2
\fBadditional\-properties\fP (\fIstr\fP) \-\- sonar analysis parameters (optional)
.IP \(bu 2
\fBskip\-global\-triggers\fP (\fIdict\fP) \-\- .INDENT 2.0
.TP
.B Triggers
.INDENT 7.0
.IP \(bu 2
\fBskip\-when\-scm\-change\fP (\fIbool\fP): skip analysis when
build triggered by scm
.IP \(bu 2
\fBskip\-when\-upstream\-build\fP (\fIbool\fP): skip analysis when
build triggered by an upstream build
.IP \(bu 2
\fBskip\-when\-envvar\-defined\fP (\fIstr\fP): skip analysis when
the specified environment variable is set to true
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
This publisher supports the post\-build action exposed by the Jenkins
Sonar Plugin, which is triggering a Sonar Analysis with Maven.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- sonar:
      jdk: MyJdk
      branch: myBranch
      language: java
      maven\-opts: \-DskipTests
      additional\-properties: \-DsonarHostURL=http://example.com/
      skip\-global\-triggers:
          skip\-when\-scm\-change: true
          skip\-when\-upstream\-build: true
          skip\-when\-envvar\-defined: SKIP_SONAR
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ssh
Upload files via SCP.
Requires the Jenkins \fI\%Publish over SSH Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBsite\fP (\fIstr\fP) \-\- name of the ssh site
.IP \(bu 2
\fBtarget\fP (\fIstr\fP) \-\- destination directory
.IP \(bu 2
\fBtarget\-is\-date\-format\fP (\fIbool\fP) \-\- whether target is a date format. If true,
raw text should be quoted (default false)
.IP \(bu 2
\fBclean\-remote\fP (\fIbool\fP) \-\- should the remote directory be deleted before
transferring files (default false)
.IP \(bu 2
\fBsource\fP (\fIstr\fP) \-\- source path specifier
.IP \(bu 2
\fBcommand\fP (\fIstr\fP) \-\- a command to execute on the remote server (optional)
.IP \(bu 2
\fBtimeout\fP (\fIint\fP) \-\- timeout in milliseconds for the Exec command (optional)
.IP \(bu 2
\fBuse\-pty\fP (\fIbool\fP) \-\- run the exec command in pseudo TTY (default false)
.IP \(bu 2
\fBexcludes\fP (\fIstr\fP) \-\- excluded file pattern (optional)
.IP \(bu 2
\fBremove\-prefix\fP (\fIstr\fP) \-\- prefix to remove from uploaded file paths
(optional)
.IP \(bu 2
\fBfail\-on\-error\fP (\fIbool\fP) \-\- fail the build if an error occurs (default false).
.IP \(bu 2
\fBalways\-publish\-from\-master\fP (\fIbool\fP) \-\- transfer the files through the master
before being sent to the remote server (defaults false)
.IP \(bu 2
\fBflatten\fP (\fIbool\fP) \-\- only create files on the server, don\(aqt create
directories (default false).
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- ssh:
      site: \(aqserver.example.com\(aq
      target: \(aqdest/dir\(aq
      source: \(aqbase/source/dir/**\(aq
      remove\-prefix: \(aqbase/source/dir\(aq
      excludes: \(aq**/*.excludedfiletype\(aq
      use\-pty: true
      command: \(aqrm \-r jenkins_$BUILD_NUMBER\(aq
      timeout: 1800000
      flatten: true


.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B stash
This plugin will configure the Jenkins Stash Notifier plugin to
notify Atlassian Stash after job completes.
.sp
Requires the Jenkins \fI\%StashNotifier Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBurl\fP (\fIstring\fP) \-\- Base url of Stash Server (Default: "")
.IP \(bu 2
\fBusername\fP (\fIstring\fP) \-\- Username of Stash Server (Default: "")
.IP \(bu 2
\fBpassword\fP (\fIstring\fP) \-\- Password of Stash Server (Default: "")
.IP \(bu 2
\fBignore\-ssl\fP (\fIbool\fP) \-\- Ignore unverified SSL certificate (Default: False)
.IP \(bu 2
\fBcommit\-sha1\fP (\fIstring\fP) \-\- Commit SHA1 to notify (Default: "")
.IP \(bu 2
\fBinclude\-build\-number\fP (\fIbool\fP) \-\- Include build number in key
(Default: False)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- stash:
      url: "https://mystash"
      username: a
      password: b
      ignore\-ssl: true
      commit\-sha1: c
      include\-build\-number: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B tap
Adds support to TAP test result files
.sp
Requires the Jenkins \fI\%TAP Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBresults\fP (\fIstr\fP) \-\- TAP test result files
.IP \(bu 2
\fBfail\-if\-no\-results\fP (\fIbool\fP) \-\- Fail if no result (default False)
.IP \(bu 2
\fBfailed\-tests\-mark\-build\-as\-failure\fP (\fIbool\fP) \-\- Mark build as failure if test fails (default False)
.IP \(bu 2
\fBoutput\-tap\-to\-console\fP (\fIbool\fP) \-\- Output tap to console (default True)
.IP \(bu 2
\fBenable\-subtests\fP (\fIbool\fP) \-\- Enable subtests (Default True)
.IP \(bu 2
\fBdiscard\-old\-reports\fP (\fIbool\fP) \-\- Discard old reports (Default False)
.IP \(bu 2
\fBtodo\-is\-failure\fP (\fIbool\fP) \-\- Handle TODO\(aqs as failures (Default True)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- tap:
        results: puiparts.tap
        todo\-is\-failure: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B testng
This plugin publishes TestNG test reports.
.sp
Requires the Jenkins \fI\%TestNG Results Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP (\fIstr\fP) \-\- filename pattern to locate the TestNG XML report files
.IP \(bu 2
\fBescape\-test\-description\fP (\fIbool\fP) \-\- escapes the description string
associated with the test method while displaying test method details
(Default True)
.IP \(bu 2
\fBescape\-exception\-msg\fP (\fIbool\fP) \-\- escapes the test method\(aqs exception
messages. (Default True)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- testng:
        pattern: "**/target/surefire\-reports/testng\-results.xml"
        escape\-test\-description: false
        escape\-exception\-msg: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B text\-finder
This plugin lets you search keywords in the files you specified and
additionally check build status
.sp
Requires the Jenkins \fI\%Text\-finder Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBregexp\fP (\fIstr\fP) \-\- Specify a regular expression
.IP \(bu 2
\fBfileset\fP (\fIstr\fP) \-\- Specify the path to search
.IP \(bu 2
\fBalso\-check\-console\-output\fP (\fIbool\fP) \-\- Search the console output (default False)
.IP \(bu 2
\fBsucceed\-if\-found\fP (\fIbool\fP) \-\- Force a build to succeed if a string was found (default False)
.IP \(bu 2
\fBunstable\-if\-found\fP (\fIbool\fP) \-\- Set build unstable instead of failing the build (default False)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- text\-finder:
        regexp: "some string"
        fileset: "file.txt"
        also\-check\-console\-output: true
        succeed\-if\-found: false
        unstable\-if\-found: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B trigger
Trigger non\-parametrised builds of other jobs.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBproject\fP (\fIstr\fP) \-\- name of the job to trigger
.IP \(bu 2
\fBthreshold\fP (\fIstr\fP) \-\- when to trigger the other job (default \(aqSUCCESS\(aq),
alternatives: SUCCESS, UNSTABLE, FAILURE
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- trigger:
      project: other_job
      threshold: SUCCESS

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B trigger\-parameterized\-builds
Trigger parameterized builds of other jobs.
Requires the Jenkins \fI\%Parameterized Trigger Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBproject\fP (\fIstr\fP) \-\- name of the job to trigger
.IP \(bu 2
\fBpredefined\-parameters\fP (\fIstr\fP) \-\- parameters to pass to the other
job (optional)
.IP \(bu 2
\fBcurrent\-parameters\fP (\fIbool\fP) \-\- Whether to include the parameters passed
to the current build to the triggered job (optional)
.IP \(bu 2
\fBsvn\-revision\fP (\fIbool\fP) \-\- Pass svn revision to the triggered job (optional)
.IP \(bu 2
\fBgit\-revision\fP (\fIbool\fP) \-\- Pass git revision to the other job (optional)
.IP \(bu 2
\fBcondition\fP (\fIstr\fP) \-\- when to trigger the other job (default \(aqALWAYS\(aq)
.IP \(bu 2
\fBproperty\-file\fP (\fIstr\fP) \-\- Use properties from file (optional)
.IP \(bu 2
\fBfail\-on\-missing\fP (\fIbool\fP) \-\- Blocks the triggering of the downstream jobs
if any of the files are not found in the workspace (default \(aqFalse\(aq)
.IP \(bu 2
\fBrestrict\-matrix\-project\fP (\fIstr\fP) \-\- Filter that restricts the subset
of the combinations that the downstream project will run (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- trigger\-parameterized\-builds:
      \- project: other_job, foo, bar
        predefined\-parameters: foo=bar
      \- project: other_job1, other_job2
        predefined\-parameters: BUILD_NUM=${BUILD_NUMBER}
        property\-file: version.prop
        fail\-on\-missing: true
      \- project: yet_another_job
        predefined\-parameters: foo=bar
        git\-revision: true
        restrict\-matrix\-project: label=="x86"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B valgrind
This plugin publishes Valgrind Memcheck XML results.
.sp
Requires the Jenkins \fI\%Valgrind Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP (\fIstr\fP) \-\- Filename pattern to locate the Valgrind XML report files
(required)
.IP \(bu 2
\fBthresholds\fP (\fIdict\fP) \-\- 
.sp
Mark build as failed or unstable if the number of
errors exceeds a threshold. All threshold values are optional.
.INDENT 2.0
.TP
.B thresholds
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBunstable\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B unstable
.INDENT 7.0
.IP \(bu 2
\fBinvalid\-read\-write\fP (\fIint\fP)
.IP \(bu 2
\fBdefinitely\-lost\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBfailed\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B failed
.INDENT 7.0
.IP \(bu 2
\fBinvalid\-read\-write\fP (\fIint\fP)
.IP \(bu 2
\fBdefinitely\-lost\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBfail\-no\-reports\fP (\fIbool\fP) \-\- Fail build if no reports are found
(default false)
.IP \(bu 2
\fBfail\-invalid\-reports\fP (\fIbool\fP) \-\- Fail build if reports are malformed
(default false)
.IP \(bu 2
\fBpublish\-if\-aborted\fP (\fIbool\fP) \-\- Publish results for aborted builds
(default false)
.IP \(bu 2
\fBpublish\-if\-failed\fP (\fIbool\fP) \-\- Publish results for failed builds
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- valgrind:
      pattern: "test.xml"
      thresholds:
        unstable:
          invalid\-read\-write: 1
          definitely\-lost: 2
          total: 3
        failed:
          invalid\-read\-write: 4
          definitely\-lost: 5
          total: 6
      fail\-no\-reports: true
      fail\-invalid\-reports: true
      publish\-if\-aborted: true
      publish\-if\-failed: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B violations
Publish code style violations.
Requires the Jenkins \fI\%Violations Plugin.\fP
.sp
The violations component accepts any number of dictionaries keyed
by the name of the violations system.  The dictionary has the
following values:
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBmin\fP (\fIint\fP) \-\- sunny threshold
.IP \(bu 2
\fBmax\fP (\fIint\fP) \-\- stormy threshold
.IP \(bu 2
\fBunstable\fP (\fIint\fP) \-\- unstable threshold
.IP \(bu 2
\fBpattern\fP (\fIstr\fP) \-\- report filename pattern
.UNINDENT
.UNINDENT
.sp
Any system without a dictionary provided will use default values.
.sp
Valid systems are:
.INDENT 7.0
.INDENT 3.5
checkstyle, codenarc, cpd, cpplint, csslint, findbugs, fxcop,
gendarme, jcreport, jslint, pep8, pmd, pylint, simian, stylecop
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- violations:
      pep8:
        min: 0
        max: 1
        unstable: 1
        pattern: \(aq**/pep8.txt\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B warnings
Generate trend report for compiler warnings in the console log or
in log files.  Requires the Jenkins \fI\%Warnings Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBconsole\-log\-parsers\fP (\fIlist\fP) \-\- The parser to use to scan the console
log (default \(aq\(aq)
.IP \(bu 2
\fBworkspace\-file\-scanners\fP (\fIdict\fP) \-\- .INDENT 2.0
.TP
.B workspace\-file\-scanners
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBfile\-pattern\fP (\fIstr\fP) \-\- Fileset \(aqincludes\(aq setting that
specifies the files to scan for warnings
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBscanner\fP (\fIstr\fP) \-\- The parser to use to scan the files
provided in workspace\-file\-pattern (default \(aq\(aq)
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBfiles\-to\-include\fP (\fIstr\fP) \-\- Comma separated list of regular
expressions that specifies the files to include in the report
(based on their absolute filename). By default all files are
included
.IP \(bu 2
\fBfiles\-to\-ignore\fP (\fIstr\fP) \-\- Comma separated list of regular expressions
that specifies the files to exclude from the report (based on their
absolute filename). (default \(aq\(aq)
.IP \(bu 2
\fBrun\-always\fP (\fIbool\fP) \-\- By default, this plug\-in runs only for stable or
unstable builds, but not for failed builds.  Set to true if the
plug\-in should run even for failed builds.  (default false)
.IP \(bu 2
\fBdetect\-modules\fP (\fIbool\fP) \-\- Determines if Ant or Maven modules should be
detected for all files that contain warnings.  Activating this
option may increase your build time since the detector scans
the whole workspace for \(aqbuild.xml\(aq or \(aqpom.xml\(aq files in order
to assign the correct module names. (default false)
.IP \(bu 2
\fBresolve\-relative\-paths\fP (\fIbool\fP) \-\- Determines if relative paths in
warnings should be resolved using a time expensive operation that
scans the whole workspace for matching files.  Deactivate this
option if you encounter performance problems.  (default false)
.IP \(bu 2
\fBhealth\-threshold\-high\fP (\fIint\fP) \-\- The upper threshold for the build
health.  If left empty then no health report is created.  If
the actual number of warnings is between the provided
thresholds then the build health is interpolated (default \(aq\(aq)
.IP \(bu 2
\fBhealth\-threshold\-low\fP (\fIint\fP) \-\- The lower threshold for the build
health.  See health\-threshold\-high.  (default \(aq\(aq)
.IP \(bu 2
\fBhealth\-priorities\fP (\fIdict\fP) \-\- 
.sp
Determines which warning priorities
should be considered when evaluating the build health (default
all\-priorities)
.INDENT 2.0
.TP
.B health\-priorities values
.INDENT 7.0
.IP \(bu 2
\fBpriority\-high\fP \-\- Only priority high
.IP \(bu 2
\fBhigh\-and\-normal\fP \-\- Priorities high and normal
.IP \(bu 2
\fBall\-priorities\fP \-\- All priorities
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBtotal\-thresholds\fP (\fIdict\fP) \-\- 
.sp
If the number of total warnings is greater
than one of these thresholds then a build is considered as unstable
or failed, respectively. (default \(aq\(aq)
.INDENT 2.0
.TP
.B total\-thresholds
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBunstable\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B unstable
.INDENT 7.0
.IP \(bu 2
\fBtotal\-all\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-high\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-normal\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-low\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBfailed\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B failed
.INDENT 7.0
.IP \(bu 2
\fBtotal\-all\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-high\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-normal\fP (\fIint\fP)
.IP \(bu 2
\fBtotal\-low\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBnew\-thresholds\fP (\fIdict\fP) \-\- 
.sp
If the specified number of new warnings exceeds
one of these thresholds then a build is considered as unstable or
failed, respectively.  (default \(aq\(aq)
.INDENT 2.0
.TP
.B new\-thresholds
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBunstable\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B unstable
.INDENT 7.0
.IP \(bu 2
\fBnew\-all\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-high\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-normal\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-low\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBfailed\fP (\fIdict\fP)
.INDENT 7.0
.TP
.B failed
.INDENT 7.0
.IP \(bu 2
\fBnew\-all\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-high\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-normal\fP (\fIint\fP)
.IP \(bu 2
\fBnew\-high\fP (\fIint\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBuse\-delta\-for\-new\-warnings\fP (\fIbool\fP) \-\- If set then the number of new
warnings is calculated by subtracting the total number of warnings
of the current build from the reference build. This may lead to wrong
results if you have both fixed and new warnings in a build. If not set,
then the number of new warnings is calculated by an asymmetric set
difference of the warnings in the current and reference build. This
will find all new warnings even if the number of total warnings is
decreasing. However, sometimes false positives will be reported due
to minor changes in a warning (refactoring of variable of method
names, etc.) (default false)
.IP \(bu 2
\fBonly\-use\-stable\-builds\-as\-reference\fP (\fIbool\fP) \-\- The number of new warnings
will be calculated based on the last stable build, allowing reverts
of unstable builds where the number of warnings was decreased.
(default false)
.IP \(bu 2
\fBdefault\-encoding\fP (\fIstr\fP) \-\- Default encoding when parsing or showing files
Leave empty to use default encoding of platform (default \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- warnings:
      console\-log\-parsers:
        \- FxCop
        \- CodeAnalysis
      workspace\-file\-scanners:
        \- file\-pattern: \(aq**/*.out\(aq
          scanner: \(aqAcuCobol Compiler
        \- file\-pattern: \(aq**/*.warnings\(aq
          scanner: FxCop
      files\-to\-include: \(aq[a\-zA\-Z]\e.java,[a\-zA\-Z]\e.cpp\(aq
      files\-to\-ignore: \(aq[a\-zA\-Z]\e.html,[a\-zA\-Z]\e.js\(aq
      run\-always: true
      detect\-modules: true
      resolve\-relative\-paths: true
      health\-threshold\-high: 50
      health\-threshold\-low: 25
      health\-priorities: high\-and\-normal
      total\-thresholds:
          unstable:
              total\-all: 90
              total\-high: 90
              total\-normal: 40
              total\-low: 30
          failed:
              total\-all: 100
              total\-high: 100
              total\-normal: 50
              total\-low: 40
      new\-thresholds:
          unstable:
              new\-all: 100
              new\-high: 50
              new\-normal: 30
              new\-low: 10
          failed:
              new\-all: 100
              new\-high: 60
              new\-normal: 50
              new\-low: 40
      use\-delta\-for\-new\-warnings: true
      only\-use\-stable\-builds\-as\-reference: true
      default\-encoding: ISO\-8859\-9
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B workspace\-cleanup (post\-build)
Requires the Jenkins \fI\%Workspace Cleanup Plugin.\fP
.sp
The pre\-build workspace\-cleanup is available as a wrapper.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBinclude\fP (\fIlist\fP) \-\- list of files to be included
.IP \(bu 2
\fBexclude\fP (\fIlist\fP) \-\- list of files to be excluded
.IP \(bu 2
\fBdirmatch\fP (\fIbool\fP) \-\- Apply pattern to directories too (default: false)
.IP \(bu 2
\fBclean\-if\fP (\fIlist\fP) \-\- 
.sp
clean depending on build status
.INDENT 2.0
.TP
.B clean\-if values
.INDENT 7.0
.IP \(bu 2
\fBsuccess\fP (\fIbool\fP) (default: true)
.IP \(bu 2
\fBunstable\fP (\fIbool\fP) (default: true)
.IP \(bu 2
\fBfailure\fP (\fIbool\fP) (default: true)
.IP \(bu 2
\fBaborted\fP (\fIbool\fP) (default: true)
.IP \(bu 2
\fBnot\-built\fP (\fIbool\fP)  (default: true)
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBfail\-build\fP (\fIbool\fP) \-\- Fail the build if the cleanup fails (default: true)
.IP \(bu 2
\fBclean\-parent\fP (\fIbool\fP) \-\- Cleanup matrix parent workspace (default: false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
  \- workspace\-cleanup:
      include:
        \- "*.zip"
      clean\-if:
        \- success: true
        \- not\-built: false
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B xml\-summary
Adds support for the Summary Display Plugin
.sp
Requires the Jenkins \fI\%Summary Display Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBfiles\fP (\fIstr\fP) \-\- Files to parse (default \(aq\(aq)
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- xml\-summary:
        files: \(aq*_summary_report.xml\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B xunit
Publish tests results.  Requires the Jenkins \fI\%xUnit Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBthresholdmode\fP (\fIstr\fP) \-\- whether thresholds represents an absolute     number of tests or a percentage. Either \(aqnumber\(aq or \(aqpercent\(aq, will     default to \(aqnumber\(aq if omitted.
.IP \(bu 2
\fBthresholds\fP (\fIdict\fP) \-\- list containing the thresholds for both     \(aqfailed\(aq and \(aqskipped\(aq tests. Each entry should in turn have a     list of "threshold name: values". The threshold names are     \(aqunstable\(aq, \(aqunstablenew\(aq, \(aqfailure\(aq, \(aqfailurenew\(aq. Omitting a     value will resort on xUnit default value (should be 0).
.IP \(bu 2
\fBtypes\fP (\fIdict\fP) \-\- per framework configuration. The key should be     one of the internal types we support:    \(aqaunit\(aq, \(aqboosttest\(aq, \(aqchecktype\(aq, \(aqcpptest\(aq, \(aqcppunit\(aq, \(aqfpcunit\(aq,     \(aqjunit\(aq, \(aqmstest\(aq, \(aqnunit\(aq, \(aqphpunit\(aq, \(aqtusar\(aq, \(aqunittest\(aq, \(aqvalgrind\(aq.     The \(aqcustom\(aq type is not supported.
.UNINDENT
.UNINDENT
.sp
Each framework type can be configured using the following parameters:
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP (\fIstr\fP) \-\- An Ant pattern to look for Junit result files,     relative to the workspace root.
.IP \(bu 2
\fBrequireupdate\fP (\fIbool\fP) \-\- fail the build whenever fresh tests     results have not been found (default: true).
.IP \(bu 2
\fBdeleteoutput\fP (\fIbool\fP) \-\- delete temporary JUnit files (default: true)
.IP \(bu 2
\fBstoponerror\fP (\fIbool\fP) \-\- Fail the build whenever an error occur during     a result file processing (default: true).
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
publishers:
    \- xunit:
        thresholdmode: \(aqpercent\(aq
        thresholds:
          \- failed:
                unstable: 0
                unstablenew: 0
                failure: 0
                failurenew: 0
          \- skipped:
                unstable: 0
                unstablenew: 0
                failure: 0
                failurenew: 0
        types:
          \- phpunit:
              pattern: junit.log
          \- cppUnit:
              pattern: cppunit.log
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Reporters
.sp
Reporters are like publishers but only applicable to Maven projets.
.INDENT 0.0
.TP
.B \fBComponent\fP: reporters
.INDENT 7.0
.TP
.B Macro
reporter
.TP
.B Entry Point
jenkins_jobs.reporters
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job:
  name: test_job
  project\-type: maven

  reporters:
    \- email:
        recipients: breakage@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B email
Email notifications on build failure.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBrecipients\fP (\fIstr\fP) \-\- Recipient email addresses
.IP \(bu 2
\fBnotify\-every\-unstable\-build\fP (\fIbool\fP) \-\- Send an email for every
unstable build (default true)
.IP \(bu 2
\fBsend\-to\-individuals\fP (\fIbool\fP) \-\- Send an email to the individual
who broke the build (default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
reporters:
  \- email:
      recipients: breakage@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS SCM
.sp
The SCM module allows you to specify the source code location for the
project.  It adds the \fBscm\fP attribute to the \fIJob\fP definition,
which accepts any number of scm definitions.
.INDENT 0.0
.TP
.B \fBComponent\fP: scm
.INDENT 7.0
.TP
.B Macro
scm
.TP
.B Entry Point
jenkins_jobs.scm
.UNINDENT
.UNINDENT
.sp
The scm module allows referencing multiple repositories in a Jenkins job.
Note: Adding more than one scm definition requires the Jenkins \fI\%Multiple
SCMs plugin.\fP
.INDENT 0.0
.TP
.B Example of multiple repositories in a single job:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- scm:
    name: first\-scm
    scm:
      \- git:
         url: ssh://jenkins@review.openstack.org:29418/first.git
         branches:
          \- origin/master

\- scm:
    name: second\-scm
    scm:
      \- git:
         url: ssh://jenkins@review.openstack.org:29418/second.git
         branches:
          \- origin/master

\- scm:
    name: first\-and\-second
    scm:
      \- first\-scm
      \- second\-scm

\- job:
    name: my\-job
    scm:
      \- first\-and\-second

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B git
Specifies the git SCM repository for this job.
Requires the Jenkins \fI\%Git Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBurl\fP (\fIstr\fP) \-\- URL of the git repository
.IP \(bu 2
\fBcredentials\-id\fP (\fIstr\fP) \-\- ID of credentials to use to connect (optional)
.IP \(bu 2
\fBrefspec\fP (\fIstr\fP) \-\- refspec to fetch (default \(aq+refs/heads/*:refs/remotes/remoteName/*\(aq)
.IP \(bu 2
\fBname\fP (\fIstr\fP) \-\- name to fetch (default \(aqorigin\(aq)
.IP \(bu 2
\fBremotes\fP (\fIlist(str)\fP) \-\- 
.sp
list of remotes to set up (optional, only needed if
multiple remotes need to be set up)
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Remote
.INDENT 7.0
.IP \(bu 2
\fBurl\fP (\fIstring\fP) \- url of remote repo
.IP \(bu 2
\fBrefspec\fP (\fIstring\fP) \- refspec to fetch (optional)
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBcredentials\-id\fP \- ID of credentials to use to connect
(optional)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBbranches\fP (\fIlist(str)\fP) \-\- list of branch specifiers to build (default \(aq**\(aq)
.IP \(bu 2
\fBexcluded\-users\fP (\fIlist(str)\fP) \-\- list of users to ignore revisions from
when polling for changes. (if polling is enabled, optional)
.IP \(bu 2
\fBincluded\-regions\fP (\fIlist(str)\fP) \-\- list of file/folders to include (optional)
.IP \(bu 2
\fBexcluded\-regions\fP (\fIlist(str)\fP) \-\- list of file/folders to exclude (optional)
.IP \(bu 2
\fBlocal\-branch\fP (\fIstr\fP) \-\- Checkout/merge to local branch (optional)
.IP \(bu 2
\fBmerge\fP (\fIdict\fP) \-\- .INDENT 2.0
.TP
.B merge
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBremote\fP (\fIstring\fP) \- name of repo that contains branch to
merge to (default \(aqorigin\(aq)
.UNINDENT
.IP \(bu 2
\fBbranch\fP (\fIstring\fP) \- name of the branch to merge to
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBbasedir\fP (\fIstr\fP) \-\- location relative to the workspace root to clone to
(default: workspace)
.IP \(bu 2
\fBskip\-tag\fP (\fIbool\fP) \-\- Skip tagging (default false)
.IP \(bu 2
\fBshallow\-clone\fP (\fIbool\fP) \-\- Perform shallow clone (default false)
.IP \(bu 2
\fBprune\fP (\fIbool\fP) \-\- Prune remote branches (default false)
.IP \(bu 2
\fBclean\fP (\fIbool\fP) \-\- Clean after checkout (default false)
.IP \(bu 2
\fBfastpoll\fP (\fIbool\fP) \-\- Use fast remote polling (default false)
.IP \(bu 2
\fBdisable\-submodules\fP (\fIbool\fP) \-\- Disable submodules (default false)
.IP \(bu 2
\fBrecursive\-submodules\fP (\fIbool\fP) \-\- Recursively update submodules (default
false)
.IP \(bu 2
\fBuse\-author\fP (\fIbool\fP) \-\- Use author rather than committer in Jenkin\(aqs build
changeset (default false)
.IP \(bu 2
\fBgit\-tool\fP (\fIstr\fP) \-\- The name of the Git installation to use (default
\(aqDefault\(aq)
.IP \(bu 2
\fBreference\-repo\fP (\fIstr\fP) \-\- Path of the reference repo to use during clone
(optional)
.IP \(bu 2
\fBscm\-name\fP (\fIstr\fP) \-\- The unique scm name for this Git SCM (optional)
.IP \(bu 2
\fBwipe\-workspace\fP (\fIbool\fP) \-\- Wipe out workspace before build (default true)
.IP \(bu 2
\fBignore\-notify\fP (\fIbool\fP) \-\- Ignore notifyCommit URL accesses (default false)
.IP \(bu 2
\fBbrowser\fP (\fIstr\fP) \-\- what repository browser to use (default \(aq(Auto)\(aq)
.IP \(bu 2
\fBbrowser\-url\fP (\fIstr\fP) \-\- url for the repository browser (required if browser
is not \(aq(Auto)\(aq, no default)
.IP \(bu 2
\fBbrowser\-version\fP (\fIstr\fP) \-\- version of the repository browser (GitLab only,
default \(aq0.0\(aq)
.IP \(bu 2
\fBproject\-name\fP (\fIstr\fP) \-\- project name in Gitblit and ViewGit repobrowser
(optional)
.IP \(bu 2
\fBchoosing\-strategy\fP (\fIstr\fP) \-\- Jenkins class for selecting what to build
(default \(aqdefault\(aq)
.IP \(bu 2
\fBgit\-config\-name\fP (\fIstr\fP) \-\- Configure name for Git clone (optional)
.IP \(bu 2
\fBgit\-config\-email\fP (\fIstr\fP) \-\- Configure email for Git clone (optional)
.IP \(bu 2
\fBtimeout\fP (\fIstr\fP) \-\- Timeout for git commands in minutes (optional)
.UNINDENT
.TP
.B Browser values
.INDENT 7.0
.TP
.B auto
.TP
.B bitbucketweb
.TP
.B cgit
.TP
.B fisheye
.TP
.B gitblit
.TP
.B githubweb
.TP
.B gitlab
.TP
.B gitoriousweb
.TP
.B gitweb
.TP
.B redmineweb
.TP
.B stash
.TP
.B viewgit
.UNINDENT
.TP
.B Choosing\-strategy values
.INDENT 7.0
.TP
.B default
.TP
.B inverse
.TP
.B gerrit
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
scm:
  \- git:
      url: https://example.com/project.git
      branches:
        \- master
        \- stable
      browser: githubweb
      browser\-url: http://github.com/foo/example.git
      timeout: 20

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B repo
Specifies the repo SCM repository for this job.
Requires the Jenkins \fI\%Repo Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBmanifest\-url\fP (\fIstr\fP) \-\- URL of the repo manifest
.IP \(bu 2
\fBmanifest\-branch\fP (\fIstr\fP) \-\- The branch of the manifest to use (optional)
.IP \(bu 2
\fBmanifest\-file\fP (\fIstr\fP) \-\- Initial manifest file to use when initialising
(optional)
.IP \(bu 2
\fBmanifest\-group\fP (\fIstr\fP) \-\- Only retrieve those projects in the manifest
tagged with the provided group name (optional)
.IP \(bu 2
\fBdestination\-dir\fP (\fIstr\fP) \-\- Location relative to the workspace root to clone
under (optional)
.IP \(bu 2
\fBrepo\-url\fP (\fIstr\fP) \-\- custom url to retrieve the repo application (optional)
.IP \(bu 2
\fBmirror\-dir\fP (\fIstr\fP) \-\- Path to mirror directory to reference when
initialising (optional)
.IP \(bu 2
\fBjobs\fP (\fIint\fP) \-\- Number of projects to fetch simultaneously (default 0)
.IP \(bu 2
\fBcurrent\-branch\fP (\fIbool\fP) \-\- Fetch only the current branch from the server
(default true)
.IP \(bu 2
\fBquiet\fP (\fIbool\fP) \-\- Make repo more quiet
(default true)
.IP \(bu 2
\fBlocal\-manifest\fP (\fIstr\fP) \-\- Contents of .repo/local_manifest.xml, written
prior to calling sync (optional)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
scm:
  \- repo:
      manifest\-url: https://example.com/project/
      manifest\-branch: stable
      manifest\-file: repo.xml
      manifest\-group: drivers
      destination\-dir: build
      repo\-url: https://internal.net/projects/repo
      mirror\-dir: ~/git/project/
      jobs: 3
      current\-branch: false
      quiet: false
      local\-manifest: |
        <?xml version="1.0" encoding="UTF\-8"?>
        <manifest>
          <project path="external/project" name="org/project"
            remote="gerrit" revision="master" />
        </manifest>

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B store
Specifies the Visualworks Smalltalk Store repository for this job.
Requires the Jenkins \fI\%Visualworks Smalltalk Store Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBscript\fP (\fIstr\fP) \-\- name of the Store script to run
.IP \(bu 2
\fBrepository\fP (\fIstr\fP) \-\- name of the Store repository
.IP \(bu 2
\fBversion\-regex\fP (\fIstr\fP) \-\- regular expression that specifies which pundle
versions should be considered (optional)
.IP \(bu 2
\fBminimum\-blessing\fP (\fIstr\fP) \-\- minimum blessing level to consider (optional)
.IP \(bu 2
\fBparcel\-builder\-file\fP (\fIstr\fP) \-\- name of the file to generate as input to
a later parcel building step (optional \- if not specified, then
no parcel builder file will be generated)
.IP \(bu 2
\fBpundles\fP (\fIlist\fP) \-\- .INDENT 2.0
.TP
.B (package or bundle)
(\fIdict\fP): A package or bundle to check
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
scm:
  \- store:
      script: someStoreScript
      repository: StoreRepository
      version\-regex: "[0\-9]+"
      minimum\-blessing: Integrated
      parcel\-builder\-file: parcelBuilderInput
      pundles:
        \- package: SomePackage
        \- package: AnotherPackage
        \- bundle: SomeBundle

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B svn
Specifies the svn SCM repository for this job.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBurl\fP (\fIstr\fP) \-\- URL of the svn repository
.IP \(bu 2
\fBbasedir\fP (\fIstr\fP) \-\- location relative to the workspace root to checkout to
(default \(aq.\(aq)
.IP \(bu 2
\fBworkspaceupdater\fP (\fIstr\fP) \-\- optional argument to specify
how to update the workspace (default wipeworkspace)
.IP \(bu 2
\fBexcluded\-users\fP (\fIlist(str)\fP) \-\- list of users to ignore revisions from
when polling for changes (if polling is enabled; parameter is optional)
.IP \(bu 2
\fBincluded\-regions\fP (\fIlist(str)\fP) \-\- list of file/folders to include
(optional)
.IP \(bu 2
\fBexcluded\-regions\fP (\fIlist(str)\fP) \-\- list of file/folders to exclude (optional)
.IP \(bu 2
\fBexcluded\-commit\-messages\fP (\fIlist(str)\fP) \-\- list of commit messages to exclude
(optional)
.IP \(bu 2
\fBexclusion\-revprop\-name\fP (\fIstr\fP) \-\- revision svn\-property to ignore (optional)
.IP \(bu 2
\fBignore\-property\-changes\-on\-directories\fP (\fIbool\fP) \-\- ignore svn\-property only
changes of directories (default false)
.IP \(bu 2
\fBfilter\-changelog\fP (\fIbool\fP) \-\- If set Jenkins will apply the same inclusion
and exclusion patterns for displaying changelog entries as it does for
polling for changes (default false)
.IP \(bu 2
\fBrepos\fP (\fIlist\fP) \-\- 
.sp
list of repositories to checkout (optional)
.INDENT 2.0
.TP
.B Repo
.INDENT 7.0
.IP \(bu 2
\fBurl\fP (\fIstr\fP) \-\- URL for the repository
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBbasedir\fP (\fIstr\fP) \-\- Location relative to the workspace
root to checkout to (default \(aq.\(aq)
.UNINDENT
.UNINDENT
.UNINDENT

.UNINDENT
.TP
.B Workspaceupdater values
.INDENT 7.0
.TP
.B wipeworkspace
.INDENT 7.0
.IP \(bu 2
deletes the workspace before checking out
.UNINDENT
.TP
.B revertupdate
.INDENT 7.0
.IP \(bu 2
do an svn revert then an svn update
.UNINDENT
.TP
.B emulateclean
.INDENT 7.0
.IP \(bu 2
delete unversioned/ignored files then update
.UNINDENT
.TP
.B update
.INDENT 7.0
.IP \(bu 2
do an svn update as much as possible
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Multiple repos example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
scm:
  \- svn:
     workspaceupdater: update
     repos:
       \- url: http://svn.example.com/repo
         basedir: .
       \- url: http://svn.example.com/repo2
         basedir: repo2

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Advanced commit filtering example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
scm:
  \- svn:
      url: http://svn.apache.org/repos/asf/spamassassin/trunk
      workspaceupdater: wipeworkspace
      included\-regions:
          \- /region1/.*\e.cpp
          \- /region2
      excluded\-regions:
          \- /region3/.*\e.jpg
          \- /region4
      excluded\-users:
          \- user1
          \- user2
      excluded\-commit\-messages:
          \- test\-msg
          \- test\-msg2
      exclusion\-revprop\-name: propname
      filter\-changelog: true
      ignore\-property\-changes\-on\-directories: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B tfs
Specifies the Team Foundation Server repository for this job.
Requires the Jenkins \fI\%Team Foundation Server Plugin.\fP
.sp
\fBNOTE\fP: TFS Password must be entered manually on the project if a
user name is specified. The password will be overwritten with an empty
value every time the job is rebuilt with Jenkins Job Builder.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBserver\-url\fP (\fIstr\fP) \-\- The name or URL of the team foundation server.
If the server has been registered on the machine then it is only
necessary to enter the name.
.IP \(bu 2
\fBproject\-path\fP (\fIstr\fP) \-\- The name of the project as it is registered on the
server.
.IP \(bu 2
\fBlogin\fP (\fIstr\fP) \-\- The user name that is registered on the server. The user
name must contain the name and the domain name. Entered as
domain\euser or user@domain (optional).
\fBNOTE\fP: You must enter in at least two slashes for the
domain\euser format in JJB YAML. It will be rendered normally.
.IP \(bu 2
\fBuse\-update\fP (\fIstr\fP) \-\- If true, Hudson will not delete the workspace at end
of each build. This causes the artifacts from the previous build to
remain when a new build starts. (default true)
.IP \(bu 2
\fBlocal\-path\fP (\fIstr\fP) \-\- The folder where all files will be retrieved into.
The folder name is a relative path, under the workspace of the current
job. (default .)
.IP \(bu 2
\fBworkspace\fP (\fIstr\fP) \-\- 
.sp
The name of the workspace under which the source
should be retrieved. This workspace is created at the start of a
download, and deleted at the end. You can normally omit the property
unless you want to name a workspace to avoid conflicts on the server
(i.e. when you have multiple projects on one server talking to a
Team Foundation Server). (default Hudson\-${JOB_NAME}\-${NODE_NAME})
.sp
The TFS plugin supports the following macros that are replaced in the
workspace name:
.INDENT 2.0
.IP \(bu 2
${JOB_NAME} \- The name of the job.
.IP \(bu 2
.INDENT 2.0
.TP
.B ${USER_NAME} \- The user name that the Hudson server or slave is
running as.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B ${NODE_NAME} \- The name of the node/slave that the plugin currently
is executed on. Note that this is not the hostname, this value is
the Hudson configured name of the slave/node.
.UNINDENT
.IP \(bu 2
${ENV} \- The environment variable that is set on the master or slave.
.UNINDENT

.IP \(bu 2
\fBweb\-access\fP (\fIdict\fP) \-\- 
.sp
Adds links in "changes" views within Jenkins to an
external system for browsing the details of those changes. The "Auto"
selection attempts to infer the repository browser from other jobs,
if supported by the SCM and a job with matching SCM details can be
found. (optional, default Auto).
.INDENT 2.0
.TP
.B web\-access value
.INDENT 7.0
.IP \(bu 2
\fBweb\-url\fP \-\- Enter the URL to the TSWA server. The plugin will
strip the last path (if any) of the URL when building URLs for
change set pages and other pages. (optional, default
uses server\-url)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
scm:
  \- tfs:
     server\-url: "tfs.company.com"
     project\-path: "$/myproject"
     login: "mydomain\e\ejane"
     use\-update: false
     local\-path: "../foo/"
     workspace: "Hudson\-${JOB_NAME}"
     web\-access:
         \- web\-url: "http://TFSMachine:8080"

scm:
  \- tfs:
     server\-url: "tfs.company.com"
     project\-path: "$/myproject"
     login: "jane@mydomain"
     use\-update: false
     local\-path: "../foo/"
     workspace: "Hudson\-${JOB_NAME}"
     web\-access:

scm:
  \- tfs:
     server\-url: "tfs.company.com"
     project\-path: "$/myproject"
     login: "mydomain\e\ejane"
     use\-update: false
     local\-path: "../foo/"
     workspace: "Hudson\-${JOB_NAME}"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B workspace
Specifies the cloned workspace for this job to use as a SCM source.
Requires the Jenkins \fI\%Clone Workspace SCM Plugin.\fP
.sp
The job the workspace is cloned from must be configured with an
clone\-workspace publisher
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBparent\-job\fP (\fIstr\fP) \-\- The name of the parent job to clone the
workspace from.
.IP \(bu 2
\fBcriteria\fP (\fIstr\fP) \-\- Set the criteria to determine what build of the parent
project to use. Can be one of \(aqAny\(aq, \(aqNot Failed\(aq or \(aqSuccessful\(aq.
(default: Any)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
scm:
  \- workspace:
      parent\-job: my\-upstream\-job
      criteria: Any

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Triggers
.sp
Triggers define what causes a Jenkins job to start building.
.INDENT 0.0
.TP
.B \fBComponent\fP: triggers
.INDENT 7.0
.TP
.B Macro
trigger
.TP
.B Entry Point
jenkins_jobs.triggers
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job:
  name: test_job

  triggers:
    \- timed: \(aq@daily\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B build\-result
Configure jobB to monitor jobA build result. A build is scheduled if there
is a new build result that matches your criteria (unstable, failure, ...).
Requires the Jenkins \fI\%BuildResultTrigger Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBgroups\fP (\fIlist\fP) \-\- List groups of jobs and results to monitor for
.IP \(bu 2
\fBjobs\fP (\fIlist\fP) \-\- The jobs to monitor (required)
.IP \(bu 2
\fBresults\fP (\fIlist\fP) \-\- Build results to monitor for (default success)
.IP \(bu 2
\fBcombine\fP (\fIbool\fP) \-\- Combine all job information.  A build will be
scheduled only if all conditions are met (default false)
.IP \(bu 2
\fBcron\fP (\fIstr\fP) \-\- The cron syntax with which to poll the jobs for the
supplied result (default \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- build\-result:
      combine: true
      cron: \(aq* * * * *\(aq
      groups:
        \- jobs:
            \- foo
            \- example
          results:
            \- unstable
        \- jobs:
            \- foo2
          results:
            \- not\-built
            \- aborted
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B gerrit
Trigger on a Gerrit event.
Requires the Jenkins \fI\%Gerrit Trigger Plugin\fP version >= 2.6.0.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBtrigger\-on\-patchset\-uploaded\-event\fP (\fIbool\fP) \-\- Trigger on patchset upload
.IP \(bu 2
\fBtrigger\-on\-change\-abandoned\-event\fP (\fIbool\fP) \-\- Trigger on change abandoned.
Requires Gerrit Trigger Plugin version >= 2.8.0
.IP \(bu 2
\fBtrigger\-on\-change\-merged\-event\fP (\fIbool\fP) \-\- Trigger on change merged
.IP \(bu 2
\fBtrigger\-on\-change\-restored\-event\fP (\fIbool\fP) \-\- Trigger on change restored.
Requires Gerrit Trigger Plugin version >= 2.8.0
.IP \(bu 2
\fBtrigger\-on\-comment\-added\-event\fP (\fIbool\fP) \-\- Trigger on comment added
.IP \(bu 2
\fBtrigger\-on\-draft\-published\-event\fP (\fIbool\fP) \-\- Trigger on draft published
event
.IP \(bu 2
\fBtrigger\-on\-ref\-updated\-event\fP (\fIbool\fP) \-\- Trigger on ref\-updated
.IP \(bu 2
\fBtrigger\-approval\-category\fP (\fIstr\fP) \-\- Approval category for comment added
.IP \(bu 2
\fBtrigger\-approval\-value\fP (\fIint\fP) \-\- Approval value for comment added
.IP \(bu 2
\fBoverride\-votes\fP (\fIbool\fP) \-\- Override default vote values
.IP \(bu 2
\fBgerrit\-build\-successful\-verified\-value\fP (\fIint\fP) \-\- Successful \(aq\(aqVerified\(aq\(aq
value
.IP \(bu 2
\fBgerrit\-build\-failed\-verified\-value\fP (\fIint\fP) \-\- Failed \(aq\(aqVerified\(aq\(aq value
.IP \(bu 2
\fBgerrit\-build\-successful\-codereview\-value\fP (\fIint\fP) \-\- Successful
\(aq\(aqCodeReview\(aq\(aq value
.IP \(bu 2
\fBgerrit\-build\-failed\-codereview\-value\fP (\fIint\fP) \-\- Failed \(aq\(aqCodeReview\(aq\(aq value
.IP \(bu 2
\fBfailure\-message\fP (\fIstr\fP) \-\- Message to leave on failure (default \(aq\(aq)
.IP \(bu 2
\fBsuccessful\-message\fP (\fIstr\fP) \-\- Message to leave on success (default \(aq\(aq)
.IP \(bu 2
\fBunstable\-message\fP (\fIstr\fP) \-\- Message to leave when unstable (default \(aq\(aq)
.IP \(bu 2
\fBprojects\fP (\fIlist\fP) \-\- 
.sp
list of projects to match
.INDENT 2.0
.TP
.B Project
.INDENT 7.0
.IP \(bu 2
\fBproject\-compare\-type\fP (\fIstr\fP) \-\-  \(aq\(aqPLAIN\(aq\(aq, \(aq\(aqANT\(aq\(aq or
\(aq\(aqREG_EXP\(aq\(aq
.IP \(bu 2
\fBproject\-pattern\fP (\fIstr\fP) \-\- Project name pattern to match
.IP \(bu 2
\fBbranch\-compare\-type\fP (\fIstr\fP) \-\- \(aq\(aqPLAIN\(aq\(aq, \(aq\(aqANT\(aq\(aq or
\(aq\(aqREG_EXP\(aq\(aq (not used if \fIbranches\fP list is specified)
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBbranch\-pattern\fP (\fIstr\fP) \-\- Branch name pattern to match
(not used if \fIbranches\fP list is specified)
.UNINDENT
.IP \(bu 2
\fBbranches\fP (\fIlist\fP) \-\- List of branches to match
(optional)
.INDENT 2.0
.TP
.B Branch
.INDENT 7.0
.IP \(bu 2
\fBbranch\-compare\-type\fP (\fIstr\fP) \-\- \(aq\(aqPLAIN\(aq\(aq,
\(aq\(aqANT\(aq\(aq or \(aq\(aqREG_EXP\(aq\(aq (optional) (default
\(aq\(aqPLAIN\(aq\(aq)
.IP \(bu 2
\fBbranch\-pattern\fP (\fIstr\fP) \-\- Branch name pattern
to match
.UNINDENT
.UNINDENT
.IP \(bu 2
\fBfile\-paths\fP (\fIlist\fP) \-\- List of file paths to match
(optional)
.INDENT 2.0
.TP
.B File Path
.INDENT 7.0
.IP \(bu 2
\fBcompare\-type\fP (\fIstr\fP) \-\- \(aq\(aqPLAIN\(aq\(aq, \(aq\(aqANT\(aq\(aq
or \(aq\(aqREG_EXP\(aq\(aq (optional) (default \(aq\(aqPLAIN\(aq\(aq)
.IP \(bu 2
\fBpattern\fP (\fIstr\fP) \-\- File path pattern to
match
.UNINDENT
.UNINDENT
.IP \(bu 2
\fBtopics\fP (\fIlist\fP) \-\- List of topics to match
(optional)
.INDENT 2.0
.TP
.B File Path
.INDENT 7.0
.IP \(bu 2
\fBcompare\-type\fP (\fIstr\fP) \-\- \(aq\(aqPLAIN\(aq\(aq, \(aq\(aqANT\(aq\(aq
or \(aq\(aqREG_EXP\(aq\(aq (optional) (default \(aq\(aqPLAIN\(aq\(aq)
.IP \(bu 2
\fBpattern\fP (\fIstr\fP) \-\- Topic name pattern to
match
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBskip\-vote\fP (\fIdict\fP) \-\- 
.sp
map of build outcomes for which Jenkins must skip
vote. Requires Gerrit Trigger Plugin version >= 2.7.0
.INDENT 2.0
.TP
.B Outcome
.INDENT 7.0
.IP \(bu 2
\fBsuccessful\fP (\fIbool\fP)
.IP \(bu 2
\fBfailed\fP (\fIbool\fP)
.IP \(bu 2
\fBunstable\fP (\fIbool\fP)
.IP \(bu 2
\fBnotbuilt\fP (\fIbool\fP)
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBsilent\fP (\fIbool\fP) \-\- When silent mode is on there will be no communication
back to Gerrit, i.e. no build started/failed/successful approve
messages etc. If other non\-silent jobs are triggered by the same
Gerrit event as this job, the result of this job\(aqs build will not be
counted in the end result of the other jobs. (default false)
.IP \(bu 2
\fBescape\-quotes\fP (\fIbool\fP) \-\- escape quotes in the values of Gerrit change
parameters (default true)
.IP \(bu 2
\fBno\-name\-and\-email\fP (\fIbool\fP) \-\- Do not pass compound \(aqname and email\(aq
parameters (default false)
.IP \(bu 2
\fBdynamic\-trigger\-enabled\fP (\fIbool\fP) \-\- Enable/disable the dynamic trigger
(default false)
.IP \(bu 2
\fBdynamic\-trigger\-url\fP (\fIstr\fP) \-\- if you specify this option, the Gerrit
trigger configuration will be fetched from there on a regular interval
.IP \(bu 2
\fBtrigger\-for\-unreviewed\-patches\fP (\fIbool\fP) \-\- trigger patchset\-created events
for changes that were uploaded while connection to Gerrit was down
(default false). Requires Gerrit Trigger Plugin version >= 2.11.0
.IP \(bu 2
\fBcustom\-url\fP (\fIstr\fP) \-\- Custom URL for a message sent to Gerrit. Build
details URL will be used if empty. (default \(aq\(aq)
.IP \(bu 2
\fBserver\-name\fP (\fIstr\fP) \-\- Name of the server to trigger on, or \(aq\(aq__ANY__\(aq\(aq to
trigger on any configured Gerrit server (default \(aq__ANY__\(aq).  Requires
Gerrit Trigger Plugin version >= 2.11.0
.UNINDENT
.UNINDENT
.sp
You may select one or more Gerrit events upon which to trigger.
You must also supply at least one project and branch, optionally
more.  If you select the comment\-added trigger, you should also
indicate which approval category and value you want to trigger the
job.
.sp
Until version 0.4.0 of Jenkins Job Builder, camelCase keys were used to
configure Gerrit Trigger Plugin, instead of hyphenated\-keys.  While still
supported, camedCase keys are deprecated and should not be used.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- gerrit:
      trigger\-on\-comment\-added\-event: true
      trigger\-approval\-category: \(aqAPRV\(aq
      trigger\-approval\-value: 1
      projects:
        \- project\-compare\-type: \(aqPLAIN\(aq
          project\-pattern: \(aqtest\-project\(aq
          branches:
            \- branch\-compare\-type: \(aqPLAIN\(aq
              branch\-pattern: \(aqmaster\(aq
            \- branch\-compare\-type: \(aqPLAIN\(aq
              branch\-pattern: \(aqstable\(aq
          file\-paths:
              \- compare\-type: ANT
                pattern: subdirectory/**
          topics:
              \- compare\-type: ANT
                pattern: refactor\-xy**
      skip\-vote:
          successful: true
          failed: true
          unstable: true
          notbuilt: true
      silent: false
      escape\-quotes: false
      no\-name\-and\-email: false
      dynamic\-trigger\-enabled: true
      dynamic\-trigger\-url: http://myhost/mytrigger
      trigger\-for\-unreviewed\-patches: true
      server\-name: my\-server

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B github
Trigger a job when github repository is pushed to.
Requires the Jenkins \fI\%GitHub Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- github
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B github\-pull\-request
Build pull requests in github and report results.
Requires the Jenkins \fI\%GitHub Pull Request Builder Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBadmin\-list\fP (\fIlist\fP) \-\- the users with admin rights (optional)
.IP \(bu 2
\fBwhite\-list\fP (\fIlist\fP) \-\- users whose pull requests build (optional)
.IP \(bu 2
\fBorg\-list\fP (\fIlist\fP) \-\- orgs whose users should be white listed (optional)
.IP \(bu 2
\fBcron\fP (\fIstring\fP) \-\- cron syntax of when to run (optional)
.IP \(bu 2
\fBtrigger\-phrase\fP (\fIstring\fP) \-\- when filled, commenting this phrase
in the pull request will trigger a build (optional)
.IP \(bu 2
\fBonly\-trigger\-phrase\fP (\fIbool\fP) \-\- only commenting the trigger phrase
in the pull request will trigger a build (default false)
.IP \(bu 2
\fBgithub\-hooks\fP (\fIbool\fP) \-\- use github hook (default false)
.IP \(bu 2
\fBpermit\-all\fP (\fIbool\fP) \-\- build every pull request automatically
without asking (default false)
.IP \(bu 2
\fBauto\-close\-on\-fail\fP (\fIbool\fP) \-\- close failed pull request automatically
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- github\-pull\-request:
      admin\-list:
        \- user1
        \- user2
      white\-list:
        \- user3
        \- user4
      org\-list:
        \- org1
        \- org2
      cron: \(aq* * * * *\(aq
      trigger\-phrase: \(aqretest this please\(aq
      only\-trigger\-phrase: true
      github\-hooks: true
      permit\-all: false
      auto\-close\-on\-fail: false

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B gitlab\-merge\-request
Build merge requests in gitlab and report results.
Requires the Jenkins \fI\%Gitlab MergeRequest Builder Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBcron\fP (\fIstring\fP) \-\- cron syntax of when to run (required)
.IP \(bu 2
\fBproject\-path\fP (\fIstring\fP) \-\- gitlab\-relative path to project (required)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- gitlab\-merge\-request:
      cron: \(aq* * * * *\(aq
      project\-path: \(aqtest/project\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B pollscm
Poll the SCM to determine if there has been a change.
.INDENT 7.0
.TP
.B Parameter
the polling interval (cron syntax)
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- pollscm: "\e*/15 * * * \e*"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B pollurl
Trigger when the HTTP response from a URL changes.
Requires the Jenkins \fI\%URLTrigger Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBcron\fP (\fIstring\fP) \-\- cron syntax of when to run (default \(aq\(aq)
.IP \(bu 2
\fBpolling\-node\fP (\fIstring\fP) \-\- Restrict where the polling should run.
(optional)
.IP \(bu 2
\fBurls\fP (\fIlist\fP) \-\- 
.sp
List of URLs to monitor
.INDENT 2.0
.TP
.B URL
.INDENT 7.0
.IP \(bu 2
\fBurl\fP (\fIstr\fP) \-\- URL to monitor for changes (required)
.IP \(bu 2
\fBproxy\fP (\fIbool\fP) \-\- Activate the Jenkins proxy (default false)
.IP \(bu 2
\fBtimeout\fP (\fIint\fP) \-\- Connect/read timeout in seconds
(default 300)
.IP \(bu 2
\fBusername\fP (\fIstring\fP) \-\- User name for basic authentication
(optional)
.IP \(bu 2
\fBpassword\fP (\fIstring\fP) \-\- Password for basic authentication
(optional)
.IP \(bu 2
\fBcheck\-status\fP (\fIint\fP) \-\- Check for a specific HTTP status
code (optional)
.IP \(bu 2
\fBcheck\-etag\fP (\fIbool\fP) \-\- Check the HTTP ETag for changes
(default false)
.IP \(bu 2
\fBcheck\-date\fP (\fIbool\fP) \-\- Check the last modification date of
the URL (default false)
.IP \(bu 2
\fBcheck\-content\fP (\fIlist\fP) \-\- List of content type changes to
monitor
.INDENT 2.0
.TP
.B Content Type
.INDENT 7.0
.IP \(bu 2
\fBsimple\fP (\fIbool\fP) \-\- Trigger on any change to
the content of the URL (default false)
.IP \(bu 2
\fBjson\fP (\fIlist\fP) \-\- Trigger on any change to
the listed JSON paths
.IP \(bu 2
\fBtext\fP (\fIlist\fP) \-\- Trigger on any change to
the listed regular expressions
.IP \(bu 2
\fBxml\fP (\fIlist\fP) \-\- Trigger on any change to
the listed XPath expressions
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- pollurl:
      cron: \(aq* * * * *\(aq
      polling\-node: \(aqlabel expression\(aq
      urls:
        \- url: \(aqhttp://example.com/url1\(aq
          proxy: false
          timeout: 442
          username: username
          password: sekr3t
          check\-status: 202
          check\-etag: false
          check\-date: true
          check\-content:
            \- simple: true
            \- json:
              \- \(aq$..author\(aq
              \- \(aq$.store..price\(aq
        \- url: \(aqhttp://example.com/url2\(aq
          proxy: true
          check\-etag: true
          check\-content:
            \- simple: false
            \- xml:
              \- \(aq//author\(aq
              \- \(aq/store//price\(aq
            \- text:
              \- \(aq\ed+\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B reverse
This trigger can be configured in the UI using the checkbox with the
following text: \(aqBuild after other projects are built\(aq.
.sp
Set up a trigger so that when some other projects finish building, a new
build is scheduled for this project. This is convenient for running an
extensive test after a build is complete, for example.
.sp
This configuration complements the "Build other projects" section in the
"Post\-build Actions" of an upstream project, but is preferable when you
want to configure the downstream project.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBjobs\fP (\fIstr\fP) \-\- List (comma separated) of jobs to watch.
.IP \(bu 2
\fBresult\fP (\fIstr\fP) \-\- Build results to monitor for between the following
options: success, unstable and failure. (default \(aqsuccess\(aq).
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- reverse:
        jobs: \(aqFantastic\-job\(aq
        result: \(aqfailure\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B script
Triggers the job using shell or batch script.
Requires the Jenkins \fI\%ScriptTrigger Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBlabel\fP (\fIstr\fP) \-\- Restrict where the polling should run. (default \(aq\(aq)
.IP \(bu 2
\fBscript\fP (\fIstr\fP) \-\- A shell or batch script. (default \(aq\(aq)
.IP \(bu 2
\fBcron\fP (\fIstr\fP) \-\- cron syntax of when to run (default \(aq\(aq)
.IP \(bu 2
\fBenable\-concurrent\fP (\fIbool\fP) \-\- Enables triggering concurrent builds.
(default false)
.IP \(bu 2
\fBexit\-code\fP (\fIint\fP) \-\- If the exit code of the script execution returns this
expected exit code, a build is scheduled. (default 0)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- script:
        script: \(aqexit 0\(aq
        cron: \(aqH/15 * * * *\(aq
        enable\-concurrent: False
        label: master
        exit\-code: 0


.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B timed
Trigger builds at certain times.
.INDENT 7.0
.TP
.B Parameter
when to run the job (cron syntax)
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- timed: "@midnight"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Wrappers
.sp
Wrappers can alter the way the build is run as well as the build output.
.INDENT 0.0
.TP
.B \fBComponent\fP: wrappers
.INDENT 7.0
.TP
.B Macro
wrapper
.TP
.B Entry Point
jenkins_jobs.wrappers
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ansicolor
Translate ANSI color codes to HTML in the console log.
Requires the Jenkins \fI\%Ansi Color Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBcolormap\fP (\fIstring\fP) \-\- (optional) color mapping to use
.UNINDENT
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- ansicolor

# Explicitly setting the colormap
wrappers:
  \- ansicolor:
      colormap: vga
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B build\-name
Set the name of the build
Requires the Jenkins \fI\%Build Name Setter Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBname\fP (\fIstr\fP) \-\- Name for the build.  Typically you would use a variable
from Jenkins in the name.  The syntax would be ${FOO} for
the FOO variable.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- build\-name:
      name: Build\-${FOO}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B build\-user\-vars
Set environment variables to the value of the user that started the build.
Requires the Jenkins \fI\%Build User Vars Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- build\-user\-vars
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ci\-skip
Skip making a build for certain push.
Just add [ci skip] into your commit\(aqs message to let Jenkins know,
that you do not want to perform build for the next push.
Requires the Jenkins \fI\%Ci Skip Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- ci\-skip

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B copy\-to\-slave
Copy files to slave before build
Requires the Jenkins \fI\%Copy To Slave Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBincludes\fP (\fIlist\fP) \-\- list of file patterns to copy
.IP \(bu 2
\fBexcludes\fP (\fIlist\fP) \-\- list of file patterns to exclude
.IP \(bu 2
\fBflatten\fP (\fIbool\fP) \-\- flatten directory structure
.IP \(bu 2
\fBrelative\-to\fP (\fIstr\fP) \-\- base location of includes/excludes,
must be userContent ($JENKINS_HOME/userContent)
home ($JENKINS_HOME) or workspace
.IP \(bu 2
\fBinclude\-ant\-excludes\fP (\fIbool\fP) \-\- exclude ant\(aqs default excludes
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- copy\-to\-slave:
      includes:
        \- file1
        \- file2*.txt
      excludes:
        \- file2bad.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B delivery\-pipeline
If enabled the job will create a version based on the template.
The version will be set to the environment variable PIPELINE_VERSION and
will also be set in the downstream jobs.
.sp
Requires the Jenkins \fI\%Delivery Pipeline Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBversion\-template\fP (\fIstr\fP) \-\- Template for generated version e.g
1.0.${BUILD_NUMBER} (default: \(aq\(aq)
.IP \(bu 2
\fBset\-display\-name\fP (\fIbool\fP) \-\- Set the generated version as the display name
for the build (default: false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
    \- delivery\-pipeline:
        version\-template: 1.0.0\-${BUILD_NUMBER}
        set\-display\-name: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B env\-file
Add or override environment variables to the whole build process
Requires the Jenkins \fI\%Environment File Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBproperties\-file\fP (\fIstr\fP) \-\- path to the properties file (default \(aq\(aq)
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- env\-file:
      properties\-file: ${WORKSPACE}/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B env\-script
Add or override environment variables to the whole build process.
Requires the Jenkins \fI\%Environment Script Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBscript\-content\fP \-\- The script to run (default: \(aq\(aq)
.IP \(bu 2
\fBonly\-run\-on\-parent\fP \-\- Only applicable for Matrix Jobs. If true, run only
on the matrix parent job (default: false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- env\-script:
      script\-content: \(aqecho foo=bar\(aq
      only\-run\-on\-parent: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B exclusion
Add a resource to use for critical sections to establish a mutex on. If
another job specifies the same resource, the second job will wait for the
blocked resource to become available.
.sp
Requires the Jenkins \fI\%Exclusion Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBresources\fP (\fIlist\fP) \-\- List of resources to add for exclusion
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- exclusion:
      resources:
          \- myresource1
          \- myresource2

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B inject
Add or override environment variables to the whole build process
Requires the Jenkins \fI\%EnvInject Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBproperties\-file\fP (\fIstr\fP) \-\- path to the properties file (default \(aq\(aq)
.IP \(bu 2
\fBproperties\-content\fP (\fIstr\fP) \-\- key value pair of properties (default \(aq\(aq)
.IP \(bu 2
\fBscript\-file\fP (\fIstr\fP) \-\- path to the script file (default \(aq\(aq)
.IP \(bu 2
\fBscript\-content\fP (\fIstr\fP) \-\- contents of a script (default \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- inject:
      properties\-file: /usr/local/foo
      properties\-content: PATH=/foo/bar
      script\-file: /usr/local/foo.sh
      script\-content: echo $PATH
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B inject\-ownership\-variables
Inject ownership variables to the build as environment variables.
Requires the Jenkins \fI\%EnvInject Plugin and Jenkins Ownership plugin
<https://wiki.jenkins\-ci.org/display/JENKINS/EnvInject+Plugin>\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBjob\-variables\fP (\fIbool\fP) \-\- inject job ownership variables to the job
(default false)
.IP \(bu 2
\fBnode\-variables\fP (\fIbool\fP) \-\- inject node ownership variables to the job
(default false)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- inject\-ownership\-variables:
      job\-variables: true
      node\-variables: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B inject\-passwords
Inject passwords to the build as environment variables.
Requires the Jenkins \fI\%EnvInject Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBglobal\fP (\fIbool\fP) \-\- inject global passwords to the job
.IP \(bu 2
\fBjob\-passwords\fP (\fIlist\fP) \-\- 
.sp
key value pair of job passwords
.INDENT 2.0
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP) Name of password
.IP \(bu 2
\fBpassword\fP (\fIstr\fP) Encrypted password
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- inject\-passwords:
      global: true
      job\-passwords:
        \- name: ADMIN
          password: 0v8ZCNaHwq1hcx+sHwRLdg9424uBh4Pin0zO4sBIb+U=
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B jclouds
Uses JClouds to provide slave launching on most of the currently
usable Cloud infrastructures.
Requires the Jenkins \fI\%JClouds Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBsingle\-use\fP (\fIbool\fP) \-\- Whether or not to terminate the slave after use
(default: False).
.IP \(bu 2
\fBinstances\fP (\fIlist\fP) \-\- The name of the jclouds template to create an
instance from, and its parameters.
.IP \(bu 2
\fBcloud\-name\fP (\fIstr\fP) \-\- The name of the jclouds profile containing the
specified template.
.IP \(bu 2
\fBcount\fP (\fIint\fP) \-\- How many instances to create (default: 1).
.IP \(bu 2
\fBstop\-on\-terminate\fP (\fIbool\fP) \-\- Whether or not to suspend instead of terminate
the instance (default: False).
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- jclouds:
      single\-use: True
      instances:
        \- jenkins\-dev\-slave:
            cloud\-name: mycloud1
            count: 1
            stop\-on\-terminate: True
        \- jenkins\-test\-slave:
            cloud\-name: mycloud2
            count: 2
            stop\-on\-terminate: False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B locks
Control parallel execution of jobs.
Requires the Jenkins \fI\%Locks and Latches Plugin.\fP
.INDENT 7.0
.TP
.B Arg
list of locks to use
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
    \- locks:
        \- FOO
        \- FOO2

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B logfilesize
Abort the build if its logfile becomes too big.
Requires the Jenkins \fI\%Logfilesizechecker Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBset\-own\fP (\fIbool\fP) \-\- Use job specific maximum log size instead of global
config value (default false).
.IP \(bu 2
\fBfail\fP (\fIbool\fP) \-\- Make builds aborted by this wrapper be marked as "failed"
(default false).
.IP \(bu 2
\fBsize\fP (\fIint\fP) \-\- Abort the build if logfile size is bigger than this
value (in MiB, default 128). Only applies if set\-own is true.
.UNINDENT
.UNINDENT
.sp
Minimum config example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- logfilesize

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Full config example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- logfilesize:
      set\-own: true
      size: 1024
      fail: true

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B logstash build wrapper
Dump the Jenkins console output to Logstash
Requires the Jenkins \fI\%logstash plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBuse\-redis\fP \-\- Boolean to use Redis. (default: true)
.IP \(bu 2
\fBredis\fP \-\- 
.sp
Redis config params
.INDENT 2.0
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBhost\fP (\fIstr\fP) Redis hostname        (default \(aqlocalhost\(aq)
.UNINDENT
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBport\fP (\fIint\fP) Redis port number (default 6397)
.UNINDENT
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBdatabase\-number\fP (\fIint\fP)        Redis database number (default 0)
.UNINDENT
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBdatabase\-password\fP (\fIstr\fP)        Redis database password (default \(aq\(aq)
.UNINDENT
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBdata\-type\fP (\fIstr\fP)        Redis database type (default \(aqlist\(aq)
.UNINDENT
.TP
.B Parameter
.INDENT 7.0
.IP \(bu 2
\fBkey\fP (\fIstr\fP) Redis key (default \(aqlogstash\(aq)
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- logstash:
      use\-redis: True
      redis:
        host: \(aqlocalhost\(aq
        port: 6379
        database\-number: 0
        database\-password: \(aqpassword\(aq
        data\-type: \(aqlist\(aq
        key: \(aqlogstash\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mask\-passwords
Hide passwords in the console log.
Requires the Jenkins \fI\%Mask Passwords Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- mask\-passwords
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B matrix\-tie\-parent
Tie parent to a node.
Requires the Jenkins \fI\%Matrix Tie Parent Plugin.\fP
Note that from Jenkins version 1.532 this plugin\(aqs functionality is
available under the "advanced" option of the matrix project configuration.
.INDENT 7.0
.TP
.B Parameters
\fBnode\fP (\fIstr\fP) \-\- Name of the node.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
project\-type: matrix
wrappers:
  \- matrix\-tie\-parent:
      node: Unix

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B pathignore
This plugin allows SCM\-triggered jobs to ignore
build requests if only certain paths have changed.
.sp
Requires the Jenkins \fI\%Pathignore Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBignored\fP (\fIstr\fP) \-\- A set of patterns to define ignored changes
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- pathignore:
      ignored: "docs, tests"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B port\-allocator
Assign unique TCP port numbers
Requires the Jenkins \fI\%Port Allocator Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBname\fP (\fIstr\fP) \-\- Variable name of the port or a specific port number
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- port\-allocator:
      name: SERVER_PORT
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B pre\-scm\-buildstep
Execute a Build Step before running the SCM
Requires the Jenkins \fI\%pre\-scm\-buildstep.\fP
.INDENT 7.0
.TP
.B Parameters
\fBbuildsteps\fP (\fIlist\fP) \-\- 
.sp
List of build steps to execute
.INDENT 7.0
.TP
.B Buildstep
Any acceptable builder, as seen in the example
.UNINDENT

.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- pre\-scm\-buildstep:
    \- shell: |
        #!/bin/bash
        echo "Doing somethiung cool"
    \- shell: |
        #!/bin/zsh
        echo "Doing somethin cool with zsh"
    \- ant: "target1 target2"
      ant\-name: "Standard Ant"
    \- inject:
         properties\-file: example.prop
         properties\-content: EXAMPLE=foo\-bar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B rbenv
Set the rbenv implementation.
Requires the Jenkins \fI\%rbenv plugin.\fP
.sp
All parameters are optional.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBruby\-version\fP (\fIstr\fP) \-\- Version of Ruby to use  (default: 1.9.3\-p484)
.IP \(bu 2
\fBignore\-local\-version\fP (\fIbool\fP) \-\- If true, ignore local Ruby
version (defined in the ".ruby\-version" file in workspace) even if it
has been defined  (default: false)
.IP \(bu 2
\fBpreinstall\-gem\-list\fP (\fIstr\fP) \-\- List of gems to install
(default: \(aqbundler,rake\(aq)
.IP \(bu 2
\fBrbenv\-root\fP (\fIstr\fP) \-\- RBENV_ROOT  (default: $HOME/.rbenv)
.IP \(bu 2
\fBrbenv\-repo\fP (\fIstr\fP) \-\- Which repo to clone rbenv from
(default: \fI\%https://github.com/sstephenson/rbenv.git\fP)
.IP \(bu 2
\fBrbenv\-branch\fP (\fIstr\fP) \-\- Which branch to clone rbenv from  (default: master)
.IP \(bu 2
\fBruby\-build\-repo\fP (\fIstr\fP) \-\- Which repo to clone ruby\-build from
(default: \fI\%https://github.com/sstephenson/ruby\-build.git\fP)
.IP \(bu 2
\fBruby\-build\-branch\fP (\fIstr\fP) \-\- Which branch to clone ruby\-build from
(default: master)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- rbenv:
      ruby\-version: 2.0.0\-p353
      ignore\-local\-version: false
      preinstall\-gem\-list: "bundler,rake"
      rbenv\-root: "$HOME/.rbenv"
      rbenv\-repo: "https://github.com/sstephenson/rbenv.git"
      rbenv\-branch: "master"
      ruby\-build\-repo: "https://github.com/sstephenson/ruby\-build.git"
      ruby\-build\-branch: "master"

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B release
Add release build configuration
Requires the Jenkins \fI\%Release Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBkeep\-forever\fP (\fIbool\fP) \-\- Keep build forever (default true)
.IP \(bu 2
\fBoverride\-build\-parameters\fP (\fIbool\fP) \-\- Enable build\-parameter override
.IP \(bu 2
\fBversion\-template\fP (\fIstring\fP) \-\- Release version template
.IP \(bu 2
\fBparameters\fP (\fIlist\fP) \-\- Release parameters (see the \fIParameters\fP module)
.IP \(bu 2
\fBpre\-build\fP (\fIlist\fP) \-\- Pre\-build steps (see the \fIBuilders\fP module)
.IP \(bu 2
\fBpost\-build\fP (\fIlist\fP) \-\- Post\-build steps (see \fIBuilders\fP)
.IP \(bu 2
\fBpost\-success\fP (\fIlist\fP) \-\- Post successful\-build steps (see \fIBuilders\fP)
.IP \(bu 2
\fBpost\-failed\fP (\fIlist\fP) \-\- Post failed\-build steps (see \fIBuilders\fP)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- release:
      keep\-forever: false
      parameters:
          \- string:
              name: RELEASE_BRANCH
              default: \(aq\(aq
              description: Git branch to release from.
      post\-success:
          \- shell: |
              #!/bin/bash
              copy_build_artefacts.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B rvm\-env
Set the RVM implementation
Requires the Jenkins \fI\%Rvm Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBimplementation\fP (\fIstr\fP) \-\- Type of implementation. Syntax is RUBY[@GEMSET],
such as \(aq1.9.3\(aq or \fI\%\(aqjruby@foo\fP\(aq.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- rvm\-env:
      implementation: 1.9.3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B sauce\-ondemand
Allows you to integrate Sauce OnDemand with Jenkins.  You can
automate the setup and tear down of Sauce Connect and integrate
the Sauce OnDemand results videos per test.  Requires the Jenkins \fI\%Sauce
OnDemand Plugin\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBenable\-sauce\-connect\fP (\fIbool\fP) \-\- launches a SSH tunnel from their cloud
to your private network (default false)
.IP \(bu 2
\fBsauce\-host\fP (\fIstr\fP) \-\- The name of the selenium host to be used.  For
tests run using Sauce Connect, this should be localhost.
ondemand.saucelabs.com can also be used to conenct directly to
Sauce OnDemand,  The value of the host will be stored in the
SAUCE_ONDEMAND_HOST environment variable.  (default \(aq\(aq)
.IP \(bu 2
\fBsauce\-port\fP (\fIstr\fP) \-\- The name of the Selenium Port to be used.  For
tests run using Sauce Connect, this should be 4445.  If using
ondemand.saucelabs.com for the Selenium Host, then use 4444.
The value of the port will be stored in the SAUCE_ONDEMAND_PORT
environment variable.  (default \(aq\(aq)
.IP \(bu 2
\fBoverride\-username\fP (\fIstr\fP) \-\- If set then api\-access\-key must be set.
Overrides the username from the global config. (default \(aq\(aq)
.IP \(bu 2
\fBoverride\-api\-access\-key\fP (\fIstr\fP) \-\- If set then username must be set.
Overrides the api\-access\-key set in the global config. (default \(aq\(aq)
.IP \(bu 2
\fBstarting\-url\fP (\fIstr\fP) \-\- The value set here will be stored in the
SELENIUM_STARTING_ULR environment variable.  Only used when type
is selenium. (default \(aq\(aq)
.IP \(bu 2
\fBtype\fP (\fIstr\fP) \-\- 
.sp
Type of test to run (default selenium)
.INDENT 2.0
.TP
.B type values
.INDENT 7.0
.IP \(bu 2
\fBselenium\fP
.IP \(bu 2
\fBwebdriver\fP
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBplatforms\fP (\fIlist\fP) \-\- The platforms to run the tests on.  Platforms
supported are dynamically retrieved from sauce labs.  The format of
the values has only the first letter capitalized, no spaces, underscore
between os and version, underscore in internet_explorer, everything
else is run together.  If there are not multiple version of the browser
then just the first version number is used.
Examples: Mac_10.8iphone5.1 or Windows_2003firefox10
or Windows_2012internet_explorer10 (default \(aq\(aq)
.IP \(bu 2
\fBlaunch\-sauce\-connect\-on\-slave\fP (\fIbool\fP) \-\- Whether to launch sauce connect
on the slave. (default false)
.IP \(bu 2
\fBhttps\-protocol\fP (\fIstr\fP) \-\- The https protocol to use (default \(aq\(aq)
.IP \(bu 2
\fBsauce\-connect\-options\fP (\fIstr\fP) \-\- Options to pass to sauce connect
(default \(aq\(aq)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- sauce\-ondemand:
      enable\-sauce\-connect: true
      sauce\-host: foo
      sauce\-port: 8080
      override\-username: foo
      override\-api\-access\-key: 123lkj123kh123l;k12323
      type: webdriver
      platforms:
        \- Linuxandroid4
        \- Linuxfirefox10
        \- Linuxfirefox11
      launch\-sauce\-connect\-on\-slave: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B ssh\-agent\-credentials
Sets up the user for the ssh agent plugin for jenkins.
.sp
Requires the Jenkins \fI\%SSH\-Agent Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
\fBuser\fP (\fIstr\fP) \-\- The user id of the jenkins user credentials (required)
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- ssh\-agent\-credentials:
      user: \(aq49d20745\-9889\-4c02\-b286\-fc6fb89c36bd\(aq

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B timeout
Abort the build if it runs too long.
Requires the Jenkins \fI\%Build Timeout Plugin.\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBfail\fP (\fIbool\fP) \-\- Mark the build as failed (default false)
.IP \(bu 2
\fBwrite\-description\fP (\fIbool\fP) \-\- Write a message in the description
(default false)
.IP \(bu 2
\fBtimeout\fP (\fIint\fP) \-\- Abort the build after this number of minutes (default 3)
.IP \(bu 2
\fBtimeout\-var\fP (\fIstr\fP) \-\- Export an environment variable to reference the
timeout value (optional)
.IP \(bu 2
\fBtype\fP (\fIstr\fP) \-\- Timeout type to use (default absolute)
.IP \(bu 2
\fBelastic\-percentage\fP (\fIint\fP) \-\- Percentage of the three most recent builds
where to declare a timeout (default 0)
.IP \(bu 2
\fBelastic\-default\-timeout\fP (\fIint\fP) \-\- Timeout to use if there were no previous
builds (default 3)
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- timeout:
      timeout: 90
      timeout\-var: \(aqBUILD_TIMEOUT\(aq
      fail: true
      type: absolute

.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- timeout:
      fail: false
      type: likely\-stuck

.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
 wrappers:
    \- timeout:
        timeout\-var: \(aqBUILD_TIMEOUT\(aq
        fail: true
        elastic\-percentage: 150
        elastic\-default\-timeout: 90
        type: elastic

.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B timestamps
Add timestamps to the console log.
Requires the Jenkins \fI\%Timestamper Plugin.\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- timestamps
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B workspace\-cleanup (pre\-build)
Requires the Jenkins \fI\%Workspace Cleanup Plugin.\fP
.sp
The post\-build workspace\-cleanup is available as a publisher.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBinclude\fP (\fIlist\fP) \-\- list of files to be included
.IP \(bu 2
\fBexclude\fP (\fIlist\fP) \-\- list of files to be excluded
.IP \(bu 2
\fBdirmatch\fP (\fIbool\fP) \-\- Apply pattern to directories too
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
wrappers:
  \- workspace\-cleanup:
      include:
        \- "*.zip"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Zuul
.sp
The Zuul module adds triggers that configure jobs for use with \fI\%Zuul\fP\&. It
essentially adds the jobs parameters \fI\%expected by Zuul\fP\&.
.sp
With Zuul version 2.0 and later, this is optional. The jobs are
triggered via the Jenkins Gearman plugin which passes the parameters
internally.  You might still want to explicitly define parameters to
retain the possibility of triggering jobs manually via the Jenkins web
interface (build with parameters).
.sp
To change the Zuul notification URL, set a global default:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- defaults:
  name: global
  zuul\-url: http://127.0.0.1:8001/jenkins_endpoint
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above URL is the default.
.INDENT 0.0
.TP
.B zuul
Configure this job to be triggered by Zuul.
.sp
Adds parameters describing the change triggering the build such as the
branch name, change number and patchset.
.sp
See parameters \fI\%expected by Zuul\fP\&.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- zuul
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B zuul\-post
Configure this post\-merge job to be triggered by Zuul.
.sp
Adds parameters describing the reference update triggering the build, which
are the previous and next revisions in full (40 hexadecimal sha1) and short
form.
.sp
See parameters \fI\%expected by Zuul\fP\&.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
triggers:
  \- zuul\-post
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Module Execution
.sp
The jenkins job builder modules are executed in sequence.
.INDENT 0.0
.TP
.B Generally the sequence is:
.INDENT 7.0
.IP 1. 3
parameters/properties
.IP 2. 3
scm
.IP 3. 3
triggers
.IP 4. 3
wrappers
.IP 5. 3
prebuilders (maven only, configured like \fIbuilders\fP)
.IP 6. 3
builders (maven, freestyle, matrix, etc..)
.IP 7. 3
postbuilders (maven only, configured like \fIbuilders\fP)
.IP 8. 3
publishers/reporters/notifications
.UNINDENT
.UNINDENT
.SH EXTENDING
.sp
Jenkins Job Builder is quite modular.  It is easy to add new
attributes to existing components, a new module to support a Jenkins
plugin, or include locally defined methods to deal with an
idiosyncratic build system.
.SS The Builder
.sp
The \fBBuilder\fP class manages Jenkins jobs. It\(aqs responsible for
creating/deleting/updating jobs and can be called from your application. You
can pass it a filename or an open file\-like object that represents your YAML
configuration. See the \fBjenkins_jobs/builder.py\fP file for more details.
.SS XML Processing
.sp
Most of the work of building XML from the YAML configuration file is
handled by individual functions that implement a single
characteristic.  For example, see the
\fBjenkins_jobs/modules/builders.py\fP file for the Python module that
implements the standard Jenkins builders.  The \fBshell\fP function at
the top of the file implements the standard \fIExecute a shell\fP build
step.  All of the YAML to XML functions in Jenkins Job Builder have
the same signature:
.INDENT 0.0
.TP
.B component(parser, xml_parent, data)
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBparser\fP (\fIYAMLParser\fP) \-\- the jenkins jobs YAML parser
.IP \(bu 2
\fBxml_parent\fP (\fIElement\fP) \-\- this attribute\(aqs parent XML element
.IP \(bu 2
\fBdata\fP (\fIdict\fP) \-\- the YAML data structure for this attribute and below
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The function is expected to examine the YAML data structure and create
new XML nodes and attach them to the xml_parent element.  This general
pattern is applied throughout the included modules.
.SS Modules
.sp
Nearly all of Jenkins Job Builder is implemented in modules.  The main
program has no concept of builders, publishers, properties, or any
other aspects of job definition.  Each of those building blocks is
defined in a module, and due to the use of setuptools entry points,
most modules are easily extensible with new components.
.sp
To add a new module, define a class that inherits from
\fBjenkins_jobs.modules.base.Base\fP, and add it to the
\fBjenkins_jobs.modules\fP entry point in your setup.py.
.INDENT 0.0
.TP
.B class jenkins_jobs.modules.base.Base(registry)
A base class for a Jenkins Job Builder Module.
.sp
The module is initialized before any YAML is parsed.
.INDENT 7.0
.TP
.B Parameters
\fBregistry\fP (\fIModuleRegistry\fP) \-\- the global module registry.
.UNINDENT
.INDENT 7.0
.TP
.B component_list_type = None
The component list type will be used to look up possible
implementations of the component type via entry points (entry
points provide a list of components, so it should be plural).
Set both component_type and component_list_type to None if module
doesn\(aqt have components.
.UNINDENT
.INDENT 7.0
.TP
.B component_type = None
The component type for components of this module.  This will be
used to look for macros (they are defined singularly, and should
not be plural).
Set both component_type and component_list_type to None if module
doesn\(aqt have components.
.UNINDENT
.INDENT 7.0
.TP
.B gen_xml(parser, xml_parent, data)
Update the XML element tree based on YAML data.  Override
this method to add elements to the XML output.  Create new
Element objects and add them to the xml_parent.  The YAML data
structure must not be modified.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBparser\fP (\fIYAMLParser\fP) \-\- the global YAML Parser
.IP \(bu 2
\fBxml_parent\fP (\fIElement\fP) \-\- the parent XML element
.IP \(bu 2
\fBdata\fP (\fIdict\fP) \-\- the YAML data structure
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B handle_data(parser)
This method is called before any XML is generated.  By
overriding this method, the module may manipulate the YAML
data structure on the parser however it likes before any XML
is generated.  If it has changed the data structure at all, it
must return \fBTrue\fP, otherwise, it must return \fBFalse\fP\&.
.INDENT 7.0
.TP
.B Parameters
\fBparser\fP (\fIYAMLParser\fP) \-\- the global YAML Parser
.TP
.B Return type
boolean
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B sequence = 10
The sequence number for the module.  Modules are invoked in the
order of their sequence number in order to produce consistently
ordered XML output.
.UNINDENT
.UNINDENT
.SS Components
.sp
Most of the standard modules supply a number of components, and it\(aqs
easy to provide your own components for use by those modules.  For
instance, the Builders module provides several builders, such as the
\fIshell\fP builder as well as the \fItrigger_builds\fP builder.  If you
wanted to add a new builder, all you need to do is write a function
that conforms to the \fIComponent Interface\fP,
and then add that function to the appropriate entry point (via a
setup.py file).
.SS Module Registry
.sp
All modules and their associated components are registered in the
module registry. It can be accessed either from modules via the registry
field, or via the parser parameter of components.
.INDENT 0.0
.TP
.B class jenkins_jobs.builder.ModuleRegistry(config)
.INDENT 7.0
.TP
.B dispatch(component_type, parser, xml_parent, component, template_data={})
This is a method that you can call from your implementation of
Base.gen_xml or component.  It allows modules to define a type
of component, and benefit from extensibility via Python
entry points and Jenkins Job Builder \fIMacros\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBcomponent_type\fP (\fIstring\fP) \-\- the name of the component
(e.g., \fIbuilder\fP)
.IP \(bu 2
\fBparser\fP (\fIYAMLParser\fP) \-\- the global YAML Parser
.IP \(bu 2
\fBxml_parent\fP (\fIElement\fP) \-\- the parent XML element
.IP \(bu 2
\fBtemplate_data\fP (\fIdict\fP) \-\- values that should be interpolated into
the component definition
.UNINDENT
.UNINDENT
.sp
See \fBjenkins_jobs.modules.base.Base\fP for how to register
components of a module.
.sp
See the Publishers module for a simple example of how to use
this method.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fIgenindex\fP
.IP \(bu 2
\fImodindex\fP
.IP \(bu 2
\fIsearch\fP
.UNINDENT
.SH AUTHOR
Jenkins Job Builder Maintainers
.SH COPYRIGHT
2012, Jenkins Job Builder Maintainers
.\" Generated by docutils manpage writer.
.