Jenkins Integration

With a Jenkins integration, you can call existing pipelines from Keptn. In addition, with the optional keptn-jenkins-library you can even provide information back to Keptn (e.g., test.finished with result=fail).

Note: The instructions on this page assume that you do not have jmeter-service installed.

Configure Jenkins

Note: Keptn needs to reach your Jenkins installation (either directly or via a proxy). This goes way beyond our documentation, therefore we suggest reaching out to your Jenkins administrator.

Open your Jenkins UI, log in as an administrator, and configure the pipeline you want to call
Select the pipeline you want to call, and click on “Configure”.
Select “Build triggers” and tick “Trigger builds remotely”
Create an authentication token (e.g., using a local password manager) - you will need this token later when creating the webhook in Keptn
Also note down the URL shown below (e.g., http://jenkins.127.0.0.1.nip.io/jobs/build?token=) - you will need it later when creating the webhook in Keptn

Enable Trigger builds remotely on Jenkins

Store sensitive data in a secret

To secure the sensitive data of your Jenkins webhook URL, a secret needs to be created:

Go to Uniform page > Secret and click the Add Secret
Enter a name (e.g., jenkins-secret) and select keptn-webhook-service as a secret scope
Enter a unique name for the key (e.g., my-pipeline-secret)
Copy-paste the authentication token from the previous step into the value field:

Create a secret for storing the Jenkins authentication token

Set up Jenkins integration via Webhook

To create a webhook integration, a subscription needs to be created:

Go to Uniform page > Uniform, select the webhook-service, and click the Add subscription button.
For this integration, we would like trigger a Jenkins pipeline when a test task in the dev and staging stage is triggered. Therefore, you need to select:
- Task: test
- Task suffix: triggered
- Filter: Stage:dev, Stage:staging
Once the above-configured event gets fired, the Jenkins pipeline has to be triggered. Therefore, you need to select/enter:
- Request method: GET
- URL: The webhook URL from above: http://jenkins.127.0.0.1.nip.io/jobs/build?token=
- Reference the secret to add the webhook identifier at the end of the URL. Therefore, clicking on the key icon, select the secret jenkins-secret and the key my-pipeline-secret. This will reference the secret value containing the sensitive data of your webhook URL: http://jenkins.127.0.0.1.nip.io/jobs/build?token={{.secret.jenkins-secret.my-pipeline-secret}}
Create a secret for storing the Jenkins authentication token
Finally, click Create subscription to save and enable the webhook for your Slack integration.

With those steps done, Keptn is triggering a Jenkins Pipeline whenever a test.triggered event occurs.

Advanced: Integrate Jenkins response

While the previous example just triggers a Jenkins Pipeline, it does not tell Keptn whether the pipeline has succeeded or not.

In order to do this, the following steps are needed:

Change the webhook to use /buildWithParameters instead of /build
Append parameters to the webhook URL, e.g., /buildWithParameters?token={{.secret.jenkins-secret.my-pipeline-secret}}&triggeredid={{.id}}&shkeptncontext={{.shkeptncontext}}&stage={{.data.stage}}
Change the webhook configuration to not auto-respond with a .finished event (sendFinished: false)
Install keptn-jenkins-library on your Jenkins Server
Configure secrets and environments variable as detailed in the install instructions of keptn-jenkins-library
Modify the Jenkins Pipeline to accept triggeredid, shkeptncontext and stage (see example below)
Use the keptn-jenkins-library function sendFinishedEvent at the end of your pipeline (see example below)

Modified webhook.yaml

apiVersion: webhookconfig.keptn.sh/v1alpha1
kind: WebhookConfig
metadata:
  name: webhook-configuration
spec:
  webhooks:
    - type: sh.keptn.event.test.triggered
      requests:
        - curl --request GET
          http://jenkins.127.0.0.1.nip.io/job/my-pipeline/buildWithParameters?token={{.secret.jenkins-secret.my-pipeline-secret}}&shkeptncontext={{.shkeptncontext}}&triggeredid={{.id}}&stage={{.data.stage}} --fail-with-body
      sendFinished: false
      envFrom: ...

Jenkinsfile

@Library('keptn-library@5.0')_
def keptn = new sh.keptn.Keptn()

node {
    properties([
        parameters([
         string(defaultValue: 'stage', description: 'Stage of your Keptn project where tests are triggered in', name: 'stage', trim: false), 
         string(defaultValue: '', description: 'Keptn Context ID', name: 'shkeptncontext', trim: false), 
         string(defaultValue: '', description: 'Triggered ID', name: 'triggeredid', trim: false), 
        ])
    ])

    def commit_id

    stage('Preparation') {
        checkout scm
    }

    stage('Initialize Keptn') {
        keptn.keptnInit project:"sockshop", service:"carts", stage:"${params.stage}"
    }

    stage('Test') {
        // Run your tests here
    }

    stage('Send Finished Event Back to Keptn') {
        // Send test.finished Event back
        def keptnContext = keptn.sendFinishedEvent eventType: "test", keptnContext: "${params.shkeptncontext}", triggeredId: "${params.triggeredid}", result:"pass", status:"succeeded", message:"jenkins tests succeeded"
        String keptn_bridge = env.KEPTN_BRIDGE
        echo "Open Keptns Bridge: ${keptn_bridge}/trace/${keptnContext}"
    }
}

Cleanup

To delete a webhook, click on the trash can icon next to the subscription. Note that deleting a webhook is permanent and cannot be reversed. Once deleted, Keptn will no longer send requests to the endpoint.