Skip to content

Pipeline Configuration Syntax

This page will cover the mechanics of JTE's Pipeline Configuration DSL.

Motivation

Originally, the JTE Pipeline Configuration was written in more standard structures like JSON or YAML.

Structure Challenge
JSON Too verbose to be comfortable writing.
YAML Users would frequently make errors with YAML syntax that resulted in a different configuration than expected.

In the end, a Groovy DSL provided the best of both words in terms of verbosity and forgiveness.

Over time, the features made available through a custom DSL became useful.

Data Structure Storage

While not required to understand the DSL, it can accelerate your learning if you're familiar with LinkedHashMaps The Pipeline Configuration syntax is a nested builder language that relies on Blocks and Properties to build a LinkedHashMap representing the configuration.

Property Setting

Properties of the Pipeline Configuration are set using Groovy's Variable Assignment syntax.

pipeline_config.groovy
foo = "bar"

assert pipelineConfig == [ foo: "bar" ]

Don't Declare Variables

The DSL relies on setProperty(String propertyName, Object value) being executed to persist the Pipeline Configuration property values.

Take the following example:

pipeline_config.groovy
x = "x" 
String y = "y"

assert pipelineConfig == [ x: "x" ]

The y value is not persisted.

Blocks

The Pipeline Configuration DSL supports nested properties using Blocks.

pipeline_config.groovy
a{
  x = 1,
  y = 2
}

assert pipelineConfig == [
  a: [
    x: 1
    y: 2
  ]
]

Empty Blocks and Unset Properties

A special case is empty blocks and unset properties. Both situations result in an empty map being set in the Pipeline Configuration.

pipeline_config.groovy
a{
  x = 1
  y{}
  z
}

assert pipelineConfig == [
  a: [
    x: 1,
    y: [:],
    z: [:]
  ]
]

Pipeline Governance Annotations

To support Pipeline Governance, the Pipeline Configuration DSL uses special annotations to control which aspects of the configuration the next configuration in the Configuration Hierarchy is able to modify.

These annotations are called @override and @merge and both can be placed on a block and property.

pipeline_config.groovy
@merge a{
  x = 1
  @override y = 2
}

Learn More

To learn more about how these annotations work, check out Merging Pipeline Configurations

Back to top