Integrate with Jenkins

What does the integration offer?

Use Compass Jenkins Integration to forward Jenkins build alerts to Compass. Compass determines the right people to notify based on on-call schedules, notifies via email, text messages (SMS), phone calls and iOS and Android push notifications, and escalates alerts until the alert is acknowledged or closed.

How does the integration work?

When a build related problem occurs in Jenkins, an alert is created in Compass automatically through the integration.

Set up the integration

Jenkins is an API-based integration. Setting it up involves the following steps:

Add a Jenkins integration in Compass
Configure the integration in Jenkins

Add a Jenkins integration

Bidirectional integrations aren’t supported in the Standard plan. All the other integrations are supported at a team level in Standard.

If you're using the Standard plan in Compass, you can add this integration only from your team’s operations page. Adding an integration from your team’s operations page makes your team the owner of the integration. This means Compass only assigns the alerts received through this integration to your team.

To add a Jenkins integration in Compass, complete the following steps:

Go to your team’s operations page.
On the left navigation panel, select Integrations and then Add integration.
Run a search and select “Jenkins”.
On the next screen, enter a name for the integration.
Optional: Select a team in Assignee team if you want a specific team to receive alerts from the integration.
Select Continue.
The integration is saved at this point.
Expand the Steps to configure the integration section and copy the API URL and API key.
You will use these while configuring the integration in Jenkins later.
Select Turn on integration.
The rules you create for the integration will work only if you turn on the integration.

Configure the integration in Jenkins

To configure the integration in Jenkins, complete the following steps:

In the Jenkins machine, go to Manage Jenkins > Go to plugin manager > Available and search for Compass Plugin, select and install it.
Go back to Jenkins main page.
Go to Manage Jenkins > Configure System > Compass Notifier Settings to set global plugin configuration.
- Enter the API URL and API key copied previously into appropriate fields. API URL is set to a default value but also can be configured.
- Enter the Teams to notify and alert Tags.
  These fields are used as default settings, override them for specific jobs.
Post-build action:
1. Select Configure and activate Compass Plugin for the Jenkins Job.
2. Scroll to the Post-Build Actions section of the project configuration.
3. Select Add post-build action.
4. Select Send Alert to Compass from the list displayed.
  The "Send Alert to Compass" section appears in the window.
5. Select Save to save these changes.
Job configuration:
1. Go to Configure > Send Alert to Compass to configure the Jenkins Job settings for Compass plugin.
2. Select Enable Sending Alerts to send an alert to Compass.
3. Select Notify Build Start to send an alert to Compass that notifies on build start.
4. Enter the API URL and API key copied previously into the appropriate fields. If these fields are filled, global settings are overridden.
5. Enter the teams to notify and alert tags. Fill these fields to override global settings.
6. Select the priority of the build status alert from Priority field.
7. Select the priority of the build start status alert from Build Start Alert's Priority field.

Configure the Step function in Compass

You can call Compass Trigger Step function from your pipeline stages or post actions. Compass Step function can be called with the following parameters (or without any parameter): tags(comma separated), teams(comma separated), priority, apiKey and apiUrl
An example request would be the following:

step

jsm(tags: "tag1,tag2" ,  teams: "team1",  priority: "P1")

API key and API URL

You can configure API key and API URL from Manage Jenkins > Configure System > Compass Notifier Settings.
You can also override API key and API URL from the step function call like following: jsm(apiKey: "myApiKey", apiUrl: "myApiUrl")

Sample pipeline script

pipeline {
    agent any
    stages {
        stage('pre') {
            steps {
                sh 'echo "pre success!"; exit 0'
            }
        }
        stage('post') {
            steps {
                sh 'echo "post success!"; exit 0'
            }
        }
        stage('Test') {
            steps {
                sh 'echo "Failed!"; exit 1'
            }
        }
    }
    post {
        always {
            echo 'This will always run'
        }
        success {
            echo 'This will run only if successful'
              jiraservicemanagement(tags: "informational")
        }
        failure {
            echo 'This will run only if failed'
            jiraservicemanagement(tags: "failure, critical", 
                     teams: "engineering", priority:"P1")
        }
        unstable {
            echo 'This will run only if the run was marked as unstable'
            jiraservicemanagement()
        }
        changed {
            echo 'This will run only if the state of the Pipeline has changed'
            echo 'For example, if the Pipeline was previously failing but is now successful'
        }
    }
}