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
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
@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
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
@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
@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. |