Solutions Delivery Platform

Configuration Files

With the Jenkins Templating Engine, configuration files are used to populate templates with the information necessary to execute.

The configuration file is a groovy file named pipeline_config.groovy that gets placed at the root of the source code repository or within a pipeline configuration repository.

Syntax

The configuration file is a custom groovy domain specific language intended to avoid the burdensome syntax of JSON without the whitespace pitfalls of YAML.

While the flexibility of what can be done within a configuration file is limited by the sandbox, the file is executed as a groovy script and builds a configuration object.

The configuration file acts as a nested builder language will accept any arbitrary configuration. Beyond several JTE configuration fields, it is up to specific primitives and libraries to provide meaning to the keys and values provided within a configuration.

Specification

The following is an overview of the configuration file schema.

jte{ (1)
    allow_scm_jenkinsfile = true
    pipeline_template = "some_template"
    permissive_initialization = false
    reverse_library_resolution = false
}

template_methods{} (2)

libraries{ (3)
    someLibrary {} (4)
}

stages{} (5)
application_environments{} (6)
keywords{} (7)
1 The jte block defines framework-level configurations
2 template_methods define the list of steps that may be invoked from a template
3 The libraries block declares the libraries to be loaded
4 Nested blocks within libraries represent a library to be loaded and parameters to pass to the library via the autowired config variable
5 Stages keep templates DRY to grouping steps
6 Application Environments encapsulate environmental context
7 Keywords define variables for use in templates

JTE Block

Field Description Default Value

allow_scm_jenkinsfile

whether or not to permit application-specific pipeline templates within source code repositories.

true

pipeline_template

A named template to fetch from a Governance Tier, per the Pipeline Template Selection process

null

permissive_initialization

Whether or not JTE will allow a naming collision within the binding. For example, two library’s that both contribute a step by the same name or a keyword and application environment by the same name.

false

reverse_library_resolution

Normally, JTE resolves libraries based on the library sources from the highest governance tier down towards the job, default library selection. This flag, if enabled, reverses the library search order

false

It is strongly recommended that permissive_initialization remain false. Before enabling, ask yourself if there is perhaps a better name for the steps and primitives that are being created instead of allowing JTE to load multiple primitives by the same name.

When permissive_initialization is enabled the original, using the shorthand invocation will throw an exception. JTE requires that if multiple steps or primitives have the same name that they be accessed via the Primitive Namespace.

Environment Substitutions

In Jenkins, environment variables are made accessible via the env global variable. This variable is resolvable within your pipeline configuration file.

This also means that Build Parameters can be access within the pipeline configuration file as they are stored on the env variable.

For example, in the following configuration:

pipeline_config.groovy
libraries{
    someLibrary{
        someField = env.buildParam ?: "default if not set"
    }
}

libraries.someLibrary.someField would resolve to the Build Parameter named buildParam and would default to default if not set if buildParam was not truthy.