Customize Jenkins with Groovy Scripts

This document shows how to customize Jenkins with Groovy scripts.

Groovy scripts are applied to Jenkins after Configuration as Code (CasC).

This tutorial assumes you have a running Jenkins instance set up.

If you haven’t installed Jenkins with Operator yet, visit Installation section to find out how to do it.

Below you can learn how to use JenkinsGroovyScript Custom Resources (CRs).

If you don’t need to use any secret data in a script, you only have to create JenkinsGroovyScript CR.

Below you can find a yaml manifest containing an example JenkinsGroovyScript CR. Copy it to a file, change jenkins-namespace and jenkins-cr-name to the namespace and name of Jenkins instance you’re customizing, then kubectl apply it.

Note the spec.data field - this is where you put your script.

apiVersion: carthago.cloud/v1beta1
kind: JenkinsGroovyScript
metadata:
  name: groovy-script
  namespace: jenkins
  labels:
    carthago.cloud/jenkins: jenkins
spec:
  data: |
    import jenkins.model.Jenkins

    def systemMessage = "Hello World!"

    Jenkins jenkins = Jenkins.getInstance()
    jenkins.setSystemMessage(systemMessage)
    jenkins.save()    

This event will trigger JenkinsGroovyScript reconcile loop and our configuration will be applied.

You should see “Hello World!” message in Jenkins dashboard.

If you need to use confidential data in the script, you have to start by creating a Secret resource to wrap it in. Then you can reference it in JenkinsGroovyScript CR.

Kubernetes stores secrets in base64 format, so we have to encode it. Running:

$ echo -n "Hello World!" | base64

will produce the following output:

SGVsbG8gd29ybGQ=

which we can use to create a Secret, so that we can safely access this data in groovy script.

Copy the Secret manifest you can find below to a file, change jenkins-namespace to the namespace of Jenkins instance you’re customizing, then kubectl apply it.

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: jenkins-conf-secrets
  namespace: <jenkins-namespace>
  labels:   
    carthago.cloud/jenkinsgroovyscript: <groovy-script-name>
data:
  SYSTEM_MESSAGE: SGVsbG8gd29ybGQ=

You don’t have to add the carthago.cloud/jenkinsgroovyscript label, but if you don’t, changes to this secret won’t trigger JenkinsGroovyScripts reconciliation loop, and in cases where you eg. update the secret, you’ll have to trigger it manually - for example, by deleting and creating JenkinsGroovyScript CR.

We still need to create JenkinsGroovyScript CR containing the script we want to apply.

Since the secret is already present in the Cluster before we create the JenkinsGroovyScript, we can safely reference its value in spec.secretRef section.

Below you can find JenkinsGroovyScript manifest referencing the secret created earlier. Copy it to a file, change jenkins-namespace and jenkins-cr-name to the namespace and name of Jenkins instance you’re customizing, then kubectl apply it.

apiVersion: carthago.cloud/v1beta1
kind: JenkinsGroovyScript
metadata:
  name: groovy-script
  namespace: <jenkins-namespace>
  labels:
    carthago.cloud/jenkins: <jenkins-cr-name>
spec:
  secretRef:
    namespace: <jenkins-namespace>
    name: jenkins-conf-secrets
  data: |
    import jenkins.model.Jenkins

    def systemMessage = secrets["SYSTEM_MESSAGE"]

    Jenkins jenkins = Jenkins.getInstance()
    jenkins.setSystemMessage(systemMessage)
    jenkins.save()    

This event will trigger JenkinsGroovyScript reconcile loop and our configuration will be applied automatically.

Our Jenkins instance will see it and bind it to previously created Secret, thanks to the reference we provided.

You will see “Hello World!” on the main page.

When you want a script your scripts to execute in a specific order, you can use JenkinsGroovyScript’s spec.dependsOn field to specify the dependency script by providing its name and namespace. When you do this, the script that specifies a dependency will wait for its dependency before running.

Here’s how it should look like. The script that has the following yaml fragment will be executed only after the script named dependency-script from namespace default will be applied to Jenkins.

spec:
  dependsOn:
    name: dependency-script
    namespace: default

Configuring scripts execution order in Helm chart’s values.yaml is identical to configuring it directly in JenkinsGroovyScript CR.

If you need a script to be run after another, specify the name and namespace of the dependency script in .spec.jenkinsGroovyScripts.dependsOn.