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, set the “Notifications Endpoints” URL to https://webhook.atomist.com/jenkins and check that the other parameters match the information shown below.

Configure Webhook

Now, Jenkins is set up to send build notifications to Atomist. Go back to the Connect Atomist to CI page to see what Atomist does with these notifications.

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('Build') {
            steps {
                // notifiy Atomist the buid starts now
                notifyAtomist("UNSTABLE", "STARTED")
                // ...
            }
            // ...
        }
    }
    // ...
}

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.

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.