Jenkins

There are several ways to connect Atomist to Jenkins. If you are not using a Jenkinsfile to configure your build, the easiest way to connect Atomist to Jenkins is using the Notification plugin. If you are using a Jenkinsfile to configure either a Pipeline or Multibranch Pipeline job, you can connect Atomist and Jenkins using the pipeline configuration in the Jenkinsfile.

Notification plugin

If you don’t already have the Notification plugin installed, go to the Plugin Manager in the Jenkins administrative interface, select it, and complete the installation.

Install Notification Plugin

To enable the plugin, be sure to restart Jenkins after installation.

Notification Plugin Installation Status

Now that the Notification plugin is installed and enabled, it’s time to configure the plugin to notify Atomist. Select a project that you would like Atomist to get events from then select “Configure” from the left column.

Configure Project

In the “Job Notifications” section of the project configuration, click the “Add Endpoint” button.

Add Notification

On the “Job Notifications” configuration tab, add an endpoint, setting the “Notifications Endpoints” URL to https://webhook.atomist.com/atomist/jenkins and leave the other values at their defaults: Format: JSON, Protocol: HTTP, Event: All Events, Timeout: 30000, and Log: 0.

Configure Webhook

Now, Jenkins is set up to send build notifications to Atomist. You should go to the getting started with the Atomist Bot page to see how build events are integrated into messages with the other events in your development flow.

Jenkinsfile

If your Jenkins build is configured using a Jenkinsfile, you can connect Atomist and Jenkins by adding a bit of “pipeline code” to the same Jenkinsfile. The rest of these instructions assume your Jenkins instance already has the Pipeline plugins installed and it is properly configured for your project. If you do not have the Pipeline plugins installed and configured, use the Notification plugin to connect Atomist and Jenkins. The instructions below will work for properly configured Pipeline and Multibranch Pipeline jobs.

Before we configure Jenkins to send build events to Atomist, we add a couple functions to our Jenkinsfile. First, we add a function that gathers information from Git.

/*
 * Retrieve current SCM information from local checkout
 */
def getSCMInformation() {
    def gitRemoteUrl = sh(returnStdout: true, script: 'git config --get remote.origin.url').trim()
    def gitCommitSha = sh(returnStdout: true, script: 'git rev-parse HEAD').trim()
    def gitBranchName = sh(returnStdout: true, script: 'git name-rev --always --name-only HEAD').trim().replace('remotes/origin/', '')

    return [
        url: gitRemoteUrl,
        branch: gitBranchName,
        commit: gitCommitSha
    ]
}

The getSCMInformation() function shells out to run the git command to collect the Git remote URL, commit SHA, and branch name, and then returns that information.

The second function shells out to use cURL to post a JSON payload to the Atomist webhook URL.

import groovy.json.JsonOutput

/*
 * Notify the Atomist services about the status of a build based from a
 * git repository.
 */
def notifyAtomist(buildStatus, buildPhase="FINALIZED",
                  endpoint="https://webhook.atomist.com/atomist/jenkins") {

    def payload = JsonOutput.toJson([
        name: env.JOB_NAME,
        duration: currentBuild.duration,
        build      : [
            number: env.BUILD_NUMBER,
            phase: buildPhase,
            status: buildStatus,
            full_url: env.BUILD_URL,
            scm: getSCMInformation()
        ]
    ])

    sh "curl --silent -XPOST -H 'Content-Type: application/json' -d '${payload}' ${endpoint}"
}

Note that the notifyAtomist() function calls the getSCMInformation() function. The rest of the JSON payload is constructed from the build environment provided by Jenkins as environment variables.

With those functions defined, we can now configure our Pipeline or Multibranch Pipeline job. First, we call the notifyAtomist() function from within our build step.

pipeline {
    // ...
    stages {
        stage('Checkout') {
            // retrieve the code to build
            checkout scm

            // notifiy Atomist the buid starts now. This must happen
            // after the checkout so we have commit information to send
            notifyAtomist("STARTED", "STARTED")
            // ...
        }

        // ...

        stage('Build') {
            steps {
            }
            // ...
        }
    }
    // ...
}

It is best to call the notifyAtomist() function as early in the build process as possible. The commented ellipses, // ..., indicate that we are only showing the portions of the Jenkinsfile relevant to adding the single function call.

The notification that a build starts must be done after you checked out the code that will be built. The commit information is necessary for Atomist to associate that event to the right repository and channel.

We also add calls to the notifyAtomist() function in the post section of the pipeline configuration to notify Atomist when the build completes.

pipeline {
    // ...
    post {
        success {
            notifyAtomist("SUCCESS")
        }
        unstable {
            notifyAtomist("UNSTABLE")
        }
        failure {
            notifyAtomist("FAILURE")
        }
    }
}

If your configuration already contains a post section, simply add the calls to notifyAtomist() to the success, unstable, and failure subsections.

Once Jenkins picks up those changes, CI events will start flowing to Atomist. You should go to the getting started with the Atomist Bot page to see how build events are integrated into messages with the other events in your development flow.