jenkins jenkins-pipeline jenkins-declarative-pipeline

custom jenkins declarative pipeline dsl with named arguments

I've been trying for a while now to start working towards moving our free style projects over to pipeline. To do so I feel like it would be best to build up a shared library since most of our builds are the same. I read through this blog post from Jenkins. I came up with the following

// vars/buildGitWebProject.groovy
def call(body) {
    def args= [:]
    body.resolveStrategy = Closure.DELEGATE_FIRST
    body.delegate = args
    body()

    pipeline {
        agent {
            node {
                label 'master'
                customWorkspace "c:\\jenkins_repos\\${args.repositoryName}\\${args.branchName}"
            }
        }
        environment {
            REPOSITORY_NAME = "${args.repositoryName}"
            BRANCH_NAME = "${args.branchName}"
            SOLUTION_NAME = "${args.solutionName}"
        }
        options {
            buildDiscarder(logRotator(numToKeepStr: '3'))
            skipStagesAfterUnstable()
            timestamps()
        }
        stages {
            stage("checkout") {
                steps {
                    script{
                        assert REPOSITORY_NAME != null : "repositoryName is null. Please include it in configuration."
                        assert BRANCH_NAME != null : "branchName is null. Please include it in configuration."
                        assert SOLUTION_NAME != null : "solutionName is null. Please include it in configuration."
                    }
                    echo "building with ${REPOSITORY_NAME}"
                    echo "building with ${BRANCH_NAME}"
                    echo "building with ${SOLUTION_NAME}"
                    checkoutFromGitWeb(args)
                }
            }
            stage('build and test') {
                steps {
                    executeRake(
                        "set_assembly_to_current_version",
                        "build_solution[$args.solutionName, Release, Any CPU]",
                        "copy_to_deployment_folder",
                        "execute_dev_dropkick"
                    )
                }
            }
        }
        post {
            always {
                sendEmail(args)
            }
        }
    }
}

in my pipeline project I configured the Pipeline to use Pipeline script and the script is as follows:

buildGitWebProject {
    repositoryName:'my-git-repo'
    branchName: 'qa'
    solutionName: 'my_csharp_solution.sln'
    emailTo='[email protected]'
}

I've tried with and without the environment block but the result ends up being the same that the value is 'null' for each of those arguments. Oddly enough the script portion of the code doesn't make the build fail either... so not sure what's wrong with that. Also the echo parts show null as well. What am I doing wrong?

Solution

Your Closure body is not behaving the way you expect/believe it should.

At the beginning of your method you have:

def call(body) {
  def args= [:]
  body.resolveStrategy = Closure.DELEGATE_FIRST
  body.delegate = args
  body()

Your call body is:

buildGitWebProject {
    repositoryName:'my-git-repo'
    branchName: 'qa'
    solutionName: 'my_csharp_solution.sln'
    emailTo='[email protected]'
}

Let's take a stab at debugging this.

If you add a println(args) after the body() in your call(body) method you will see something like this:

[emailTo:[email protected]]

But, only one of the values got set. What is going on?

There are a few things to understand here:

What does setting a delegate of a Closure do?
Why does repositoryName:'my-git-repo' not do anything?
Why does emailTo='[email protected]' set the property in the map?

What does setting a delegate of a Closure do?

This one is mostly straightforward, but I think it helps to understand. Closure is powerful and is the Swiss Army knife of Groovy. The delegate essentially sets what the this is in the body of the Closure. You are also using the resolveStrategy of Closure.DELEGATE_FIRST, so methods and properties from the delegate are checked first, and then from the enclosing scope (owner) - see the Javadoc for an in-depth explanation. If you call methods like size(), put(...), entrySet(), etc., they are all first called on the delegate. The same is true for property access.

Why does repositoryName:'my-git-repo' not do anything?

This may appear to be a Groovy map literal, but it is not. These are actually labeled statements. If you surround it instead with square brackets like [repositoryName:'my-git-repo'] then that would be a map literal. But, that is all you would be doing there - is creating a map literal. We want to make sure that these objects are consumed in the Closure

Why does emailTo='[email protected]' set the property in the map?

This is using the map property notation feature of Groovy. As mentioned earlier, you have set the delegate of the Closure to def args= [:], which is a Map. You also set the resolveStrategy of Closure.DELEGATE_FIRST. This makes your emailTo='[email protected]' resolve to being called on args, which is why the emailTo key is set to the value. This is equivalent to calling args.emailTo='[email protected]'.

So, how do you fix this?

If you want to keep your Closure syntax approach, you could change the body of your call to anything that essentially stores values in the delegated args map:

buildGitWebProject {
  repositoryName = 'my-git-repo'
  branchName = 'qa'
  solutionName = 'my_csharp_solution.sln'
  emailTo = '[email protected]'
}

buildGitWebProject {
  put('repositoryName', 'my-git-repo')
  put('branchName', 'qa')
  put('solutionName', 'my_csharp_solution.sln')
  put('emailTo', '[email protected]')
}

buildGitWebProject {
  delegate.repositoryName = 'my-git-repo'
  delegate.branchName = 'qa'
  delegate.solutionName = 'my_csharp_solution.sln'
  delegate.emailTo = '[email protected]'
}

buildGitWebProject {
  // example of Map literal where the square brackets are not needed
  putAll(
      repositoryName:'my-git-repo',
      branchName: 'qa',
      solutionName: 'my_csharp_solution.sln',
      emailTo: '[email protected]'
  )
}

Another way would be to have your call take in the Map as an argument and remove your Closure.

def call(Map args) {
    // no more args and delegates needed right now
}

buildGitWebProject(
    repositoryName: 'my-git-repo',
    branchName: 'qa',
    solutionName: 'my_csharp_solution.sln',
    emailTo: '[email protected]'
)

There are also some other ways you could model your API, it will depend on the UX you want to provide.

Side note around declarative pipelines in shared library code:

It's worth keeping in mind the limitations of declarative pipelines in shared libraries. It looks like you are already doing it in vars, but I'm just adding it here for completeness. At the very end of the documentation it is stated:

Only entire pipelines can be defined in shared libraries as of this time. This can only be done in vars/*.groovy, and only in a call method. Only one Declarative Pipeline can be executed in a single build, and if you attempt to execute a second one, your build will fail as a result.