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).

Prerequisites

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).

Using Groovy scripts without Secrets

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.

Using Groovy scripts with Secrets

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.

Creating a Secret with data to use in the script

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>
data:
  SYSTEM_MESSAGE: SGVsbG8gd29ybGQ=

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.