how to get $CAUSE in workflow

Question

Jenkins has a $CAUSE variable available to freestyle build jobs.

How can I access this or something similar in workflow?

My team makes use of it in email output of existing ad-hoc builds. We'd like to continue the same in new workflow based jobs.

Answer 1

It looks like Workflow builds don't have this variable injected. However you can retrieve the required info from currentBuild.rawBuild object using hudson.model.Run.getCause() or hudson.model.Run.getCauses() method.

Example:

Workflow script:

println "CAUSE ${currentBuild.rawBuild.getCause(hudson.model.Cause$UserIdCause).properties}"

results with this output:

Running: Print Message
CAUSE [userName:John Smith, userId:jsmith, class:class hudson.model.Cause$UserIdCause, shortDescription:Started by user John Smith]

Other Cause subtypes can be found in the javadoc.

There is also a good get-build-cause example which is based on this answer in the jenkins Pipeline Examples repository.

Answer 2

As of early 2018, it looks like that information is now available with JENKINS-31576 being closed:

def manualTrigger = true
currentBuild.upstreamBuilds?.each { b ->
  echo "Upstream build: ${b.getFullDisplayName()}"
  manualTrigger = false
}

Answer 3

Looks like as of Jenkins 2.22 (JENKINS-41272), you can access the currentBuild.getBuildCauses() method to get an array of build causes. For example:

environment {
  CAUSE = "${currentBuild.getBuildCauses()[0].shortDescription}"
}

steps {
  echo "Build caused by ${env.CAUSE}"
}

Answer 4

I'm replying to Jazzschmidt's answer, as I just don't have enough rep... previousBuild does the wrong thing, as it gets the previously launched job of the same type, not the job that launched the current one. If that job was first launched by someone, that's who you'll get. Otherwise, the response will be NULL, which will then cause an exception trying to get its userId.

To get the "original" cause, you have to traverse the causes using UpstreamCause. This is what I ended up doing, though there may be other ways:

@NonCPS
def getCauser() {
  def build = currentBuild.rawBuild
  def upstreamCause
  while(upstreamCause = build.getCause(hudson.model.Cause$UpstreamCause)) {
    build = upstreamCause.upstreamRun
  }
  return build.getCause(hudson.model.Cause$UserIdCause).userId
}

Answer 5

To get cause if build was triggered by user , SCM or pull request you can use this:

def SCMTriggerCause
def UserIdCause
def GitHubPRCause
def PRCause = currentBuild.rawBuild.getCause(org.jenkinsci.plugins.github.pullrequest.GitHubPRCause)
def SCMCause = currentBuild.rawBuild.getCause(hudson.triggers.SCMTrigger$SCMTriggerCause)
def UserCause = currentBuild.rawBuild.getCause(hudson.model.Cause$UserIdCause)

if (PRCause) {
    println PRCause.getShortDescription()
} else if (SCMCause) {
    println SCMCause.getShortDescription()
} else if (UserCause) {
    println UserCause.getShortDescription()
}else {
   println "unknown cause"
}

Note: you have to run in a script section

credit to this github: https://github.com/benwtr/jenkins_experiment/blob/master/Jenkinsfile

Answer 6

We all like one-liners, so let me share one here:

env.STARTED_BY = currentBuild.getBuildCauses().iterator().next().userId ?: "SYSTEM"

To break it down, after 2.22 pipeline plugin release there is a nice getBuildCauses method added to access build causes.

If you run your job like:

def causes = currentBuild.getBuildCauses()
causes.each {
    echo "$it"
}
echo "${causes.iterator().next().userId}"

you will see:

[Pipeline] echo
[_class:hudson.model.Cause$UserIdCause, shortDescription:Started by user User Name (user.name), userId:user.name, userName:User Name (user.name)]
[Pipeline] echo
user.name

and if it was started by cron then you will see:

[Pipeline] echo
[_class:hudson.triggers.TimerTrigger$TimerTriggerCause, shortDescription:Started by timer]
[Pipeline] echo
null

Answer 7

$BUILD_CAUSE env is not available for pipelines, and in multibranch pipeline even currentBuild.rawBuild.getCause(hudson.model.Cause$UserIdCause) would fail, if build was triggered by SCM change or timer. So, I implemented below workaround..

    def manualTrigger = false
    node('master'){
       def causes = currentBuild.rawBuild.getCauses()
       for(cause in causes) {
          if(cause.properties.shortDescription =~ 'Started by user') {
             manualTrigger = true
             break
          }
      }
  }

And rest of my workflow is in another node

   node('nodefarm') {
       if(manualTrigger) {
         // do build stuff here
       } else {
         //build not triggered by user.
       }
   } 

Answer 8

In case the build is triggered by an upstream build, you have to traverse the currentBuild hierarchy.

For example:

println getCauser(currentBuild).userId

@NonCPS
def getCauser(def build) {
    while(build.previousBuild) {
        build = build.previousBuild
    }

    return build.rawBuild.getCause(hudson.model.Cause$UserIdCause)
}

This will return the user id of the original user cause.

Answer 9

I guess you are talking about a macro defined in the Email Ext plugin. There is ongoing work to make that plugin directly support Workflow. I am not sure about the status of this specific macro.

Answer 10

All the answers involve being inside the running job. However you can get this post build to query history by doing this:

 def job = hudson.model.Hudson.instance.getItem("test_job");
 def build = job.getBuild("8141")
 println(build.getCauses())

[job/run_tests/9532[job/master_pipeline/10073[job/GitBuildHook/9527[hudson.model.Cause$RemoteCause@3c1d9a68]]]]

in this case the test was caused by 3 jobs calling each other which was triggered by git commit RemoteCause. since I'm using python to gather this, I can reformat the string to return causes as a list like this

def get_build_cause(jenkins_session, job_name, build_number):
    Q =(  f'def job = hudson.model.Hudson.instance.getItem("{job_name}");\n'
        f'def build = job.getBuild("{build_number}")\n'
        'println(build.getCauses())'
    )
    
    causes = jenkins_session.run_script( Q ).strip().split('[')
    causes[-1] = causes[-1][:-(len(causes)-1)]
    return causes

for more info on python api see https://python-jenkins.readthedocs.io/en/latest/api.html#jenkins.Jenkins.run_script

Edit :
This is the API doc of methods for the cause object. If you are into doing it the hard way :-) https://javadoc.jenkins-ci.org/hudson/model/Cause.UpstreamCause.html