How to set custom build cause on invoke() in Python JenkinsAPI

Question

I am trying to set custom causes for Jenkins builds using the jenkins api.

The jenkins api has an invoke() method for invoking new builds that receives the cause parameter.

# this is a jenkinsapi.Job method
invoke(self, securitytoken=None, block=False,
           build_params=None, cause=None, files=None, delay=5):

The cause param is dealt with like this:

if cause:
        build_params['cause'] = cause

I am trying to find out what format to use when defining a custom cause. In order to do this I first extracted the cause of a build to see what it looks like using jenkinsapi.Build method get_causes().

This yields a list of dictionaries as expected (only 1 cause), example:

[{'shortDescription': 'description of cause',
  'userId': 'userid',
  'userName': 'username'}]

With this knowledge, I tried invoking builds while specifying cause as a list of dictionaries in the same format, but this didn't work, upon collecting the causes from this new build, only the normal default cause was there.

So, my question is what do I need to do to create a custom cause?

Answer 1

I've found two ways to add in the custom cause but only one way which works with the Jenkin's API. I'm still hoping there's an alternative solution.

To get the custom cause setting to work I had to enable this setting in each Jenkin's job:

After enabling that setting, I was able to trigger the Job with a custom cause which would show up in the console.

job.invoke(securitytoken="asecuretoken", cause="A custom cause.")

The main trouble I have with this route is that it doesn't fill out the amount of information I see from custom plugins. That's the alternative I've found to using the cause in this manner but it requires more work to implement.

I've found a good example which customizes the build messages based on a REST request is the GitLab Jenkin's Plugin.