Solutions Delivery Platform

2.0 Upgrade Guide

Hey everyone! JTE 2.0 is finally here. We really appreciate everyone’s patience while we worked on this major release. This page is going to help walk you through the breaking changes associated with 2.0.

Library File Structure

In order to support library resources, the file structure of libraries has been reorganized.

Pre 2.0

.
├── libraryA (1)
│  ├── library_config.groovy (2)
│  ├── someOtherStep.groovy (3)
│  └── someStep.groovy (3)
└── libraryB (1)
   ├── library_config.groovy (2)
   ├── someOtherStep.groovy (3)
   └── someStep.groovy (3)
1 libraries are directories
2 library configuration file goes at root of the library directory
3 steps are *.groovy files that go at the root of the library directory

Post 2.0

.
├── libraryA (1)
│  ├── library_config.groovy (2)
│  ├── resources (3)
│  │  └── someScript.sh
│  └── steps (4)
│     ├── someOtherStep.groovy
│     └── someStep.groovy
└── libraryB (1)
   ├── library_config.groovy (2)
   ├── resources (3)
   │  └── someData.json
   └── steps (4)
      ├── someOtherStep.groovy
      └── someStep.groovy
1 Libraries are still directories identified by the directory name
2 The library configuration file still lives at the root of the library directory
3 A new resources directory has been created where reusable files are stored
4 Steps have been moved into a new steps directory

@override & @merge annotations

Previously, the ability to govern pipeline configuration changes were confined to the block-level - with no way to govern individual fields. To address this, JTE has pivoted from the flags merge=true & override=true to the annotations @merge & @override. These annotations can be placed on individual fields within a block, enabling field-level governance.

Pre 2.0

Pipeline Configuration
someBlock{
  merge = true (1)
  my_governed_field = "some value" (2)
}
anotherBlock{
  override = true (3)
  may_not_be_changed = true
  default_value_may_be_changed = true
}
1 indicates that the subsequent configuration file could add fields to someBlock
2 my_governed_field would not be modifiable
3 indicates that this entire block can be overwritten. There is no way for administrators to provide default values that can be overridden without requiring subsequent configurations to define the entire block.

Post 2.0

Pipeline Configuration
@merge someBlock{ (1)
  my_governed_field = "some value"
}
anotherBlock{ (2)
  may_not_be_changed = true (3)
  @override default_value = true  (4)
}
1 indicates that subsequent pipeline configurations can add additional fields to someBlock
2 subsequent pipeline configurations may not add fields to anotherBlock
3 subsequent pipeline configurations may not modify the may_not_be_changed field
4 a default value can be provided for the default_value field - but subsequent pipeline configurations may override this field. This previously was not possible prior to field-level governance provided by JTE 2.0.

Top level pipeline configuration values and the jte{} block

Previously, there were top level configuration values like allow_scm_jenkinsfile and pipeline_template. These values are now in the jte block in the pipeline_config

Pre 2.0

Pipeline Configuration
allow_scm_jenkinsfile = false
pipeline_template = "my_template"
someBlock{
  merge = true
  my_governed_field = "some value"
}
anotherBlock{
  override = true
  may_not_be_changed = true
  default_value_may_be_changed = true
}

Post 2.0

Pipeline Configuration
jte{
  allow_scm_jenkinsfile = false
  pipeline_template = "my_template"
}

@merge someBlock{
  my_governed_field = "some value"
}
anotherBlock{
  may_not_be_changed = true
  @override default_value = true
}

Lifecycle Hook: hookContext

JTE provides some syntactic sugar by means of autowiring variables to library steps to simplify library development.

Previously, library steps that implemented lifecycle hooks were required to accept a method parameter to accept the hook context. This parameter was typically called context but could be called anything.

Pre 2.0

someStep.groovy
@AfterStep({ context.step == "build" }) (1)
void call(context){ (2)
  println "running after the ${context.step} step" (3)
}
1 Hook annotations take an optional closure parameter to determine if the hook should execute. This closure was previously autowired with a context variable to query information about what triggered the hook.
2 Hook steps were required to take a method parameter, typically called context
3 Hook steps would use that method parameter to query information about what triggered the hook

Post 2.0

someStep.groovy
@AfterStep({ hookContext.step == "build"}) (1)
void call(){ (2)
  println "running after the ${hookContext.step} step" (3)
}
1 the context variable in annotation closures has been renamed hookContext
2 Hook steps no longer take a method parameter
3 Hook steps are autowired a hookContext variable

Configuration Changes

We took the opportunity during a major release to do some major refactoring!

Global Configurations

There have been updates to the underlying class structure of the Global Governance Tier configured in Manage Jenkins > Configure System > Jenkins Templating Engine. This will impact the Jenkins Configuration as Code (JCasC) YAML schema used to configure JTE.

We would recommend configuring the Global Governance Tier manually the way you require and exporting the JCasC YAML to see the schema required to automate configuring JTE.

Job Configurations

There have been updates to the underlying package and class structure for JTE as a whole as well as feature development for adhoc pipeline jobs. This impacts Job DSL scripts used to configure jobs utilizing JTE.

JTE also now supports fetching the pipeline configuration and pipeline template for a one-off pipeline job, which results in some changes to the structure of Job DSL for ad-hoc pipeline jobs.

Job DSL supports Dynamic DSL which means that Job DSL supports the Jenkins Templating Engine settings. We would recommend utilizing the Job DSL API Viewer on your Jenkins Instance once JTE 2.0 has been installed to see how to configure JTE settings.