This plug-in allow Jenkins to notify ontrack about events like build creation, status of running job, etc... but also allows Jenkins to require information from ontrack.
It allows to run the following actions:
- creating a new build
- promoting an existing build
- validating an existing build according to the result of the build
- execute any arbitrary DSL as a step or as a publisher
- setup a build environment using the DSL
- evaluating a condition based on a DSL evaluation
Finally, the Ontrack plugin defines an extension to the Job DSL so that it can be setup programmatically.
You can install the Ontrack Jenkins plug-in on any Jenkins version starting from 1.580.
To configure the build, go in Manage Jenkins > Configure System and enter the following data in the Ontrack configuration section:
- Configuration name in ontrack — name of the Jenkins configuration in Ontrack ; this configuration will be used to generated back links to the Jenkins instance you are configuring. This will be used by the Build notifier.
- URL — base URL to the Ontrack instance
- User and Password — user used for the connection to Ontrack - this user must have enough rights for the actions it has to carry from within Jenkins. Usually, giving a Controller role should be enough.
Five individual plug-ins are provided by the general Ontrack plug-in.
Add Ontrack: Build creation in the Post build actions in order to create a build for an existing branch.
Parameters are the project name, the branch name and the name of the build to create. Each parameter can use ${VAR} notations in order to get the value for a VAR environment variable or parameter.
The Ontrack build will be associated with a link to the Jenkins build.
Add Ontrack: Promoted run creation in the Post build actions in order to promote an existing build.
Parameters are the project name, the branch name, the name of the build to promote and the name of the promotion level. Each parameter can use ${VAR} notations in order to get the value for a VAR environment variable or parameter.
Add Ontrack: Validation run creation in the Post build actions in order to create a validation run for an existing build.
Parameters are the project name, the branch name, the name of the build to validate and the name of the validation stamp. Each parameter can use ${VAR} notations in order to get the value for a VAR environment variable or parameter.
The status of the validation run depends on the Jenkins's build current result:
| Jenkins | Ontrack |
|---|---|
| SUCCESS | PASSED |
| UNSTABLE | WARNING |
| ABORTED | INTERRUPTED |
| Other | FAILED |
Add Ontrack: DSL in the Build steps in order to run the Ontrack DSL in the build steps. The build will fail or succeed according to the result of the DSL.
See below for details about using the DSL.
Add Ontrack: DSL in the Post build actions in order to run the Ontrack DSL in the post build actions.
See below for details about using the DSL.
Use the Ontrack: Trigger to add a trigger which fires the job according to the indicated setup.
The DSL can be used to allow the computation of a parameter for the running build.
Select Ontrack: Single Parameter in the list of parameters.
Enter a DSL which returns one object and extracts a property of this object using the Value property field. The resulting string will be used as the value for the parameter.
The DSL can be used to allow the selection among a list of values computed by the DSL.
Select Ontrack: Parameter Choice in the list of parameters.
Enter a DSL which returns a list of objects (a single object would be converted into a singleton list) and extracts a property of each item using the Value property field. The resulting list of strings is then used for the selection.
The Ontrack Jenkins plug-in provides a Run Condition which evaluates the result of the DSL into a boolean.
The DSL configuration is the same than above.
The result of the DSL execution is evaluated according to the following rules:
- if a
Stringdifferent than '' (blank), evaluates tofalse - if a
Boolean, uses its value - in any other case, evaluates to
true
The Ontrack plugin provides an extension to the EnvInject plugin, allowing to run an Ontrack DSL in order to setup the build environment.
The DSL must return a map of <name, value> and this is injected into the build environment.
Following variables are bound to the script context:
ontrack- see the DSL section belowjenkins- see the DSL section belowbuild- the currentAbstractBuildbeing configuredout- aPrintStreamwhich can be used for loggingenv-hudson.EnvVarsinstance which can be used to access current environment or build parameters.
The set of bound variables is different than the one used in other DSL actions.
The Ontrack DSL allows you to pilot Ontrack using a simple script language.
The script is written using Groovy with Ontrack and Jenkins specific extensions.
An ontrack object is made available - please look in the Ontrack DSL documentation for the details of what you can do.
A jenkins object is made available, in order to allow you to have access to the current build. This object has the following methods and properties:
build- access to the current buildlistener- access to the build listenerenv(String name, String value)- sets an environment variable in the current buildsuccess-trueif the current status of the build is SUCCESSunstable-trueif the current status of the build is UNSTABLEfailure-trueif the current status of the build is FAILURE
All DSL steps and actions take additional parameters other than the DSL script itself.
Comma-separated list of environment variables or parameters to make available into the script as Groovy variables. For example, if you put BUILD_NUMBER,SVN_REVISION, the BUILD_NUMBER and SVN_REVISION values can be directly accessed from within the DSL.
You can define variables to inject into the script by using a property-like format.
For example, the following text:
BRANCH = 1.0
BUILD = ${VERSION}
would inject the corresponding BRANCH and BUILD variables in the script:
ontrack.branch('PRJ', BRANCH).build(VERSION, "Build ${VERSION}")In the text:
- declare properties using
name = valuesyntax - empty lines are ignored
- lines started by
#are ignored - patterns like
${VAR}are expanded usingVARfrom the current environment variables.
If set, the connections (request + response) to Ontrack will be logged in the build console output. This can be useful for debugging the plug-in's behaviour.
The Ontrack plug-in provides the following extensions to the Job DSL.
job(...) {
publishers {
ontrackBuild(project, branch, buildName)
}
}job(...) {
publishers {
ontrackPromotion(project, branch, build, promotionLevel)
}
}job(...) {
publishers {
ontrackValidation(project, branch, build, validationStamp)
}
}job(...) {
publishers {
ontrackDsl {
// Path to the DSL (relative to workspace)
path(String value)
// Ontrack DSL script
script(String value)
// Injects environment variables
// Can be called several times
environment(String... names)
// Inject property values
properties(String properties)
// Enables or disables the log
log(boolean enabled = true)
}
}
}job(...) {
steps {
ontrackDsl {
// Path to the DSL (relative to workspace)
path(String value)
// Ontrack DSL script
script(String value)
// Injects environment variables
// Can be called several times
environment(String... names)
// Inject property values
properties(String properties)
// Enables or disables the log
log(boolean enabled = true)
}
}
}job(...) {
triggers {
ontrackTrigger '0 0 H/* * *', 'project', 'branch', 'PROMOTION', 'VERSION'
}
}and PROMOTION can be a valid Ontrack promotion level name or
- blank to mean the last build
*to mean the last promoted build
Future versions of the Ontrack plug-in will bring Job DSL extensions to support:
- environment contributions
- parameters
This mostly depend on the version of the Job DSL which the Ontrack DSL must support (1.35 as of now).
All the plug-in actions rely themselves on the DSL language. Only the most basic and common actions (build creation, promotion, validation) have been extracted as separate actions.
Everything else should be encoded using the DSL step or action.