Skip to content

Integrations

Atomist natively supports several continuous integration (CI) platforms, listening for CI events, correlating them with the commits that triggered the build, and showing contextualized notifications in a Slack channel linked to the repository. To enable this capability, just add the desired Atomist CI webhook URL to your CI configuration.

Note

In the examples below, replace WORKSPACE_ID with your workspace ID.

CircleCI

To send events from CircleCI to Atomist, add the following snippet to your .circleci/config.yml configuration file.

notify:
  webhooks:
    - url: https://webhook.atomist.com/atomist/circle/teams/WORKSPACE_ID

Jenkins

You can send events from Jenkins to Atomist using the notification plugin, configuring it to send its payload to https://webhook.atomist.com/atomist/jenkins/teams/WORKSPACE_ID, replacing WORKSPACE_ID with your Atomist workspace ID.

If you configure your build using a Jenkinsfile, add the following function to your Jenkinsfile.

import groovy.json.JsonOutput

/**
 * Notify the Atomist services about the status of a build based from a
 * git repository.
 */
def notifyAtomist(String workspaceIds, String buildStatus, String buildPhase="FINALIZED") {
    if (!workspaceIds) {
        echo 'No Atomist workspace IDs, not sending build notification'
        return
    }
    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: [
                    url: env.GIT_URL,
                    branch: env.COMMIT_BRANCH,
                    commit: env.COMMIT_SHA
                ]
            ]
        ]
    )
    workspaceIds.split(',').each { workspaceId ->
        String endpoint = "https://webhook.atomist.com/atomist/jenkins/teams/${workspaceId}"
        sh "curl --silent -X POST -H 'Content-Type: application/json' -d '${payload}' ${endpoint}"
    }
}

Ensure your build has an environment variable named ATOMIST_WORKSPACES whose value is your Atomist workspace ID or, if you want to send the event to more than one Atomist workspace, the value should be a comma-separated list of your Atomist workspace IDs.

Then call notifyAtomist when the build starts (in the first stage) and ends (in the post block), sending the appropriate status and phase.

  • Start: notifyAtomist(env.ATOMIST_WORKSPACES, "STARTED", "STARTED")
  • Succesful: notifyAtomist(env.ATOMIST_WORKSPACES, "SUCCESS")
  • Unstable: notifyAtomist(env.ATOMIST_WORKSPACES, "UNSTABLE")
  • Failure: notifyAtomist(env.ATOMIST_WORKSPACES, "FAILURE")

Here is a simple example Jenkinsfile pipeline that sends the appropriate webhook payloads at the appropriate time.

/**
 * Simple Jenkins pipeline for Maven builds
 */
pipeline {
    agent any

    environment {
        MVN = 'mvn -B -V'
    }

    stages {
        stage('Notify') {
            steps {
                echo 'Sending build start...'
                notifyAtomist(env.ATOMIST_WORKSPACES, 'STARTED', 'STARTED')
            }
        }

        stage('Set version') {
            steps {
                echo 'Setting version...'
                sh "${env.MVN} versions:set -DnewVersion=${env.COMMIT_SHA} versions:commit"
            }
        }

        stage('Build, Test, and Package') {
            steps {
                echo 'Building, testing, and packaging...'
                sh "${env.MVN} clean package"
            }
        }
    }

    post {
        always {
            echo 'Post notification...'
            notifyAtomist(env.ATOMIST_WORKSPACES, currentBuild.currentResult)
        }
    }
}

Travis CI

To send events from Travis CI to Atomist, add the following snippet to your .travis.yml configuration file.

notifications:
  webhooks:
    urls:
      - https://webhook.atomist.com/atomist/travis/teams/WORKSPACE_ID
    on_success: always
    on_failure: always
    on_start: always
    on_cancel: always
    on_error: always

Other

If you use a different CI tool than those listed above, you can send your build payload to Atomist using its generic build payload webhook endpoint. Atomist provides a helper Bash script you can call from your CI solution to post webhook payloads to Atomist. The script can be found in the Atomist utilities repository and can be invoked as follows:

bash atomist-post-webhook.bash build WORKSPACE_ID

If your CI platform is not supported by the above script or you prefer to use your own script, below is an example of how to send the necessary JSON payload using curl.

curl -s -f -X POST -H "Content-Type: application/json" \
    --data-binary "{\"branch\":\"BRANCH\",\"repository\":{\"owner_name\":\"REPO_OWNER\",\"name\":\"REPO_NAME\"},\"commit\":\"SHA\",\"status\":\"STATUS\",\"type\":\"TYPE\"}" \
    https://webhook.atomist.com/atomist/build/teams/WORKSPACE_ID

When using the above command, replace the ALL_CAPS strings as follows:

String Description
BRANCH Branch of commit being built
REPO_OWNER Owner, i.e., organization or user, of repository
REPO_NAME Name of repository
SHA Full commit SHA
STATUS Build status: “started”, “failed”, “error”, “passed”, “canceled”
TYPE Build trigger: “push”, “pull_request”, “tag”, “cron”, “manual”

There are other optional elements you can include in your webhook POST payload. Here is the complete list of build payload elements.

Property JSON Type Description
branch string Branch of commit (required if build type is “push”)
build_url string Web URL for build report/log
commit string Full commit SHA (required)
compare_url string Commit comparison URL showing changes
id string Build ID, must be unique among all builds associated with a given repository
name string Name for build
number number Build number
provider string Name of CI provider
pull_request_number number Pull request number (only valid and required if build type is “pull_request”)
repository.owner_name string Owner, i.e., organization or user, of repository (required)
repository.name string Name of repository (required)
status string Build status: “started”, “failed”, “error”, “passed”, “canceled” (required)
tag string Tag being build, only valid and required if build type is “tag”
type string Build trigger: “push”, “pull_request”, “tag”, “cron”, “manual” (required)

See the build webhook documentation for more details.