A hands-on experience with Configure Blocks in Jenkins Job DSL.
This post is an example of using Configure Blocks. I’ll make an effort an try to explain what Configure Blocks are with my own words.
Basically, the whole DSL language output is a job configuration XML file. You are given a high level API to shape out that XML, that’s it. In some cases, where there’s no simple high level API available yet, you can use a bit lower level methods to mess around with resulting XML. That’s exactly what configure blocks are - a fallback mechanism to squeeze more juice out of Job DSL plugin.
Here’s an example, a default configuration of Git plugin will not update submodules recursively and will use default 10 minutes timeout for submodules update operation.
Job DSL provides an API to enable recursive submodules update. This is how you can use it in DSL
That was easy. Here’s how the Jenkins job will look like now.
What if you want to change default timeout for submodules operations now? Unfortunately there’s no DSL command for that yet. This is exactly the case where you’d want to use Configure Block. Scanning through Configure Block examples, I have found this one. Looks like it’s quite easy to add new nodes to the job XML, but you have to figure out how to name those nodes first. The best way to find that out is to modify the job via Jenkins UI and then look at the job XML. So open the job configuration page in the browser, type in the 20 minutes custom timeout value and click save.
Now it’s time to locate the XML on file system. All the jobs data is located in
JENKINS_HOME, the easiest way to find Jenkins Home location is again via Jenkins UI. Go to
Jenkins > Manage Jenkins > Configure System and have a look at the top of the page.
Navigate to Jenkins Home, then to
jobs directory, then find the directory of your particular job, this is very straightforward task, finally you will see
config.xml in that directory, open it and have a look. This is the node you are looking for
Specifically you are interested in this block of code
<timeout>20</timeout> node? This is exactly what you want to generate using Configure Block. This is how you can do that
That looks easy, doesn’t it? But hold on a sec before you celebrate. Run a DSL script first then have a look at resulting XML before looking at job configuration via Jenkins UI. Locate the SCM node again
Hm… Looks a bit strange doesn’t it? The
recursiveSubmodules nodes are outside of
hudson.plugins.git.extensions.impl.SubmoduleOption for some reason. At least the values look right. So now go ahead and open the job configuration in Jenkins UI or hit refresh if you had it open all this time.
Wait… What did just happen there? The recursive update checkbox is cleared!
Let’s have a look at job XML one more time.
scm node is moved up in the XML and is changed a bit. Also, the
recursiveSubmodules as well as
disableSubmodules are moved inside the
hudson.plugins.git.extensions.impl.SubmoduleOption node, but somehow
recursiveSubmodules has lost its custom value in the process. Whatever Jenkins is doing under the hood is a mystery for me. This may be a bug in Jenkins Job DSL plugin or a known limitation. Brief search in project JIRA and discussion group didn’t come back with any results. That means if you are working with Configure Blocks, keep the following in mind
When changing one particular node, either do all changes via Job DSL API or via Configure Block, but never mix the two.
If you want to have both recursive submodule update and custom timeout configured, set both of them via Configure Block.