×
Find plugins

IBM Cloud DevOps1.1.0Minimum Jenkins requirement: 2.46.2ID: ibm-cloud-devops

Installs: 10
Last released: 19 days ago
Maintainers
Xunrong Li
Patrick Joy
Vijay Jegaselvan
Eric Jodet

Description

This plugin lets you integrate Jenkins with IBM DevOps Insights. DevOps Insights tracks your deployment risk based on the data that you publish to it. It allows you to add gates to your pipelines so that you can stop builds that don't meet test criteria from getting deployed. You can also use DevOps Insights to analyze your code repository, which can yield valuable information about error-prone files, commit trends, and team dynamics.

Here is a dashboard that shows deployment risk:

At a high level, here are the integration steps.  These steps are described later in this document.

  • Create an IBM Bluemix account
  • Create a toolchain. Learn more about toolchains here.
  • Create promotion policies
  • Install the Jenkins plugin
  • Configure your Jenkins project to publish test results to DevOps Insights, automatically evaluate build quality at gates, and track your deployment risk. 

The plugin provides post-build actions to support the integration. DevOps Insights aggregates and analyzes the results from unit tests, functional tests, code coverage tools, static security code scans, dynamic security code scans to determine whether your code meets predefined policies at gates in your deployment process. If your code does not meet or exceed a policy, the deployment is halted, preventing risky changes from being released. You can use DevOps Insights as a safety net for your continuous delivery environment, a way to implement and improve quality standards over time, and a data visualization tool to help you understand your project's health.

Creating a Bluemix Account

Go to IBM Bluemix to create a free account.  It will take you only a few minutes to create an account.

Creating a toolchain

Before you can integrate DevOps Insights with a Jenkins project, you must create a toolchain.

  1. To create a toolchain, go to the Create a Toolchain page and follow the instructions on that page. This step is expected to take only a few minutes.

  2. Add DevOps Insights tool to the toolchain by clicking "Add Tool" and selecting DevOps Insights card. For details, see the DevOps Insights documentation.  This step should take only a minute or so.

Creating Promotion Policies

Go to Toolchains page and click on your toolchain.  Then, click on DevOps card.   Click on the Settings menu item in the left nav bar.  Then, click on Policies.  

 

Now, you can define one or more promotion policies.  Each policy will take only a few minutes to create.

 

 

Installing the plugin

Install this plugin via the Jenkins plugin manager
 

Integrating with Jenkins Pipeline

This plugin supports both declarative or scripted formats.  It also supports Jenkins jobs.


Exposing required environment variables

Next, open the pipeline definition.

In the definition, add the following environment variables. These variables are required for the pipeline to integrate with DevOps Insights.

Tip: See the Jenkins pipeline documentation for more information about the credentials command.

Tip: If you are using the the scripted pipeline format, set your credentials with withCredentials and your environment with withEnv instead of credentials and environment, which are used in the example below. See the Jenkins documentation for more about withCredentials.

 

These environment variables and credentials are used by the IBM Cloud DevOps plugin to interact with DevOps Insights. Here is an example of setting them in the declarative pipeline format.

environment {
        IBM_CLOUD_DEVOPS_CREDS = credentials('BM_CRED')
        IBM_CLOUD_DEVOPS_ORG = 'dlatest'
        IBM_CLOUD_DEVOPS_APP_NAME = 'Weather-App'
        IBM_CLOUD_DEVOPS_TOOLCHAIN_ID = '1111111-aaaa-2222-bbbb-333333333'
        IBM_CLOUD_DEVOPS_WEBHOOK_URL = 'https://jenkins:5a55555a-a555-5555-5555-a555aa55a555:55555555-5555-5555-5555-555555555555@devops-api.ng.bluemix.net/v1/toolint/messaging/webhook/publish'
    }

Adding Cloud DevOps steps

The Cloud DevOps plugin adds four steps to Jenkins pipelines for you to use. Use these steps in your pipelines to interact with DevOps Insights.

  • publishBuildRecord, which publishes build information to DevOps Insights
  • publishTestResult, which publishes test results to DevOps Insights
  • publishDeployRecord, which publishes deployment records to DevOps Insights
  • evaluateGate, which enforces DevOps Insights policies

Add these steps to your pipeline definition wherever you need them to run. For example, you might upload test results after running a test, and then evaluate those results at a gate after they are uploaded.

Publishing build records

Publish build records with the publishBuildRecord step. This step requires four parameters.

Here are the parameters in an example command:

publishBuildRecord gitBranch: "${GIT_MASTER}", gitCommit: "${GIT_COMMIT}", gitRepo: "https://github.com/username/reponame", result:"SUCCESS" 

Tip: Jenkins Pipeline does not expose Git information as environment variables. You can get the Git commit ID by using the command sh(returnStdout: true, script: 'git rev-parse HEAD').trim().

 

Publishing test results

 

Publish build records with the publishTestResult step. This step requires two parameters.

 

 

 

Here are the parameters in example commands. The first command publishes Mocha unit test results, and the second command publishes code coverage test results.

publishTestResult type:'unittest', fileLocation: './mochatest.json'
publishTestResult type:'code', fileLocation: './tests/coverage/reports/coverage-summary.json'

 

 

Publishing SonarQube results

After you configure a SonarQube scanner and server by following the instructions in the SonarQube docs, you can publish scan results to DevOps Insights.

To configure your Jenkins Pipeline to accept these results, add the following three parameters to it:

 

 

Here are the SonarQube parameters used in a sample stage:

stage ('SonarQube analysis') {
    steps {
        script {
            def scannerHome = tool 'Default SQ Scanner';
            withSonarQubeEnv('Default SQ Server') {
               
                env.SQ_HOSTNAME = SONAR_HOST_URL;
                env.SQ_AUTHENTICATION_TOKEN = SONAR_AUTH_TOKEN;
                env.SQ_PROJECT_KEY = "My Project Key";
                
                run SonarQube scan ...
            }
        }
    }
}
stage ("SonarQube Quality Gate") {
     steps {
        ...
     }
     post {
        always {
            publishSQResults SQHostURL: "${SQ_HOSTNAME}", SQAuthToken: "${SQ_AUTHENTICATION_TOKEN}", SQProjectKey:"${SQ_PROJECT_KEY}"
        }
     }
}


Publishing deployment records

 

Publish deployment records with the publishDeployRecord step. This step requires two parameters. It can also accept one optional parameter.

 

 

 

Here are the parameters in example commands. The first command publishes the deployment record for a staging environment; the second command publishes the deployment record for a production environment.

publishDeployRecord environment: "STAGING", appUrl: "http://staging-Weather-App.mybluemix.net", result:"SUCCESS"
publishDeployRecord environment: "PRODUCTION", appUrl: "http://Weather-App.mybluemix.net", result:"SUCCESS"

 

Adding gates

 

Add gates to your pipeline by using the evaluateGate command. Gates enforce DevOps Insights policies, which set test requirements for build promotion.

 

This step requires one parameters. It can also accept one optional parameter.

 

 

 

Here are the parameters in an example command. In this command, the pipeline will continue running regardless of the gate's decision.

evaluateGate policy: 'Weather App Policy', forceDecision: 'true'

 

Communicating with toolchains

 

Send pipeline status to Bluemix toolchains by using the notifyOTC command. To learn more about integrating Jenkins with toolchains, see Notifying tool chains section below. 

This step requires two parameters and can take an additional optional one.

 

 

 

Here are examples of using the notifyOTC step in both declarative and scripted pipeline definitions:

 

notifyOTC stageName: "Deploy", status: "SUCCESS"

 

Examples declarative and scripted pipeline

 

Here are two complete pipeline examples defined as declarative Jenkinsfile and a scripted Jenkinsfile

 

 

Integrating with freeform Jenkins project

Configuring Jenkins jobs for the Deployment Risk dashboard

After the plugin is installed, you can integrate DevOps Insights into your Jenkins project.

Follow these steps to use Deployment Risk's gates and dashboard with your project.

  1. Open the configuration of any jobs that you have, such as build, test, or deployment.

  2. Add a post-build action for the corresponding type:

    • For build jobs, use Publish build information to IBM Cloud DevOps.

    • For test jobs, use Publish test result to IBM Cloud DevOps.

    • For SonarQube jobs, use Publish SonarQube test result to IBM Cloud DevOps.
    • For deployment jobs, use Publish deployment information to IBM Cloud DevOps.

  3. Complete the required fields. These will vary depending on job type.

    • From the Credentials list, select your Bluemix ID and password. If they are not saved in Jenkins, click Add to add and save them. Test your connection with Bluemix by clicking Test Connection.

    • In the Build Job Name field, specify your build job's name exactly as it is in Jenkins. If the build occurs with the test job, leave this field empty. If the build job occurs outside of Jenkins, select the Builds are being done outside of Jenkins check box and specify the build number and build URL.

    • For the environment, if the tests are running in build stage, select only the build environment. If the tests are running in the deployment stage, select the deploy environment and specify the environment name. Two values are supported: STAGING and PRODUCTION.

    • For the Result File Location field, specify the result file's location. If the test doesn't generate a result file, leave this field empty. The plugin uploads a default result file that is based on the status of current test job.

    • For the SonarQube hostname and SonarQube authentication token fields, specify the hostname and token that are configured on your SonarQube Server. For the SonarQube project key field, specify the project key of the SonarQube project that you wish to scan. 

    These images show example configurations:

Publish build information

Publish test result

Publish SonarQube test result

Publish deployment information


4. If you want to use DevOps Insights policy gates to control a downstream deployment job, add a post-build action, IBM Cloud DevOps Gate. Choose a policy and specify the scope of the test results. To allow the policy gates to prevent downstream deployments, select the Fail the build based on the policy rules check box. The following image shows an example configuration:

 

5. Run your Jenkins Build job.

6. View the Deployment Risk dashboard by going to IBM Bluemix DevOps, selecting your toolchain, and clicking DevOps Insights.

 

The Deployment Risk dashboard relies on the presence of a gate after a staging deployment job. If you want to use the dashboard, make sure that you have a gate after you deploy to the staging environment, but before you deploy to a production environment.

 

Notifying toolchains

You can configure your Jenkins jobs to send notifications to tools integrated to your toolchain (e.g., Slack, PagerDuty), and use traceability to track code deployments through tags, labels, and comments in your Git repository (repo).

 

Both Freestyle projects and Pipeline are supported.

Prerequisites

Create a toolchain

Refer to Bluemix documentation in order to create a tool chain  that will integrate your Jenkins server to other tools such as Github, Insights, Slack and PagerDuty. 

Jenkins Webhook URL

  1. On your tool chain main page, click the 3 dots in top top right corner of the Jenkins tile, and select configure.
  2. Take note - copy / paste it in a notepad - of the Generated toolchain webhook URL. Webhook URL uses a format like:
    https://jenkins:c3cd97bc-b987-43bd-8020-c14bd1b1366a:8996de45-380a-40b2-a099-65a6eeb9a466@devops-api.ng.bluemix.net/v1/toolint/messaging/webhook/publish

Add bluemix credentials to Jenkins

This configuration step is common to both Freestyle or Pipeline projects.

  1. On the Manage Jenkins page, select Manage Credentials
  2. Scope: global
  3. Username: your bluemix user id
  4. Password: corresponding password
  5. ID: IBM_CLOUD_DEVOPS_CREDS
  6. (optional) Description: Bluemix creds
  7. Save your changes

These credentials will be used in Freestyle or Pipeline jobs using the credentials ID.

 

Freestyle job

  1. Create a new Freestyle project
  2. Select "This project is parameterized".
  3. Add the String following parameters:

  4. Source Code Management: select Git, and enter the URL and branch of the Git repository as configured in your toolchain.


  5. Build triggers: select Poll SCM in order to start job automatically after a Git commit. Enter your schedule options.


  6. Build Environment
    - Select Use secret text(s) or file(s)
    - Add Username and password (separated)
    - Username Variable: IBM_CLOUD_DEVOPS_CREDS_USR
    - Password Variable: IBM_CLOUD_DEVOPS_CREDS_PSW
    - Credentials: select the bluemix specific credentials you added to Jenkins server 


  7.  Build step is not detailed here, as the script deploying your application to bluemix might be specific to your environment.
     Below is a simple sample Shell script example that pushes your application to bluemix. 

    cf api https://api.ng.bluemix.net
    cf login -u $IBM_CLOUD_DEVOPS_CREDS_USR -p $IBM_CLOUD_DEVOPS_CREDS_PSW -o $IBM_CLOUD_DEVOPS_ORG -s $IBM_CLOUD_DEVOPS_SPACE
    cf push $IBM_CLOUD_DEVOPS_APP_NAME -n $IBM_CLOUD_DEVOPS_APP_NAME
  8. Post-build action: add the Notify OTC post-build action.
  9. Select the options matching your needs:
    - Notify Slack on Job started, completed or finalized events,
    - Notify PagerDuty on Job faliures only
    - Select Track deployment of code changes to enable traceability to track code deployments through tags, labels, and comments in your Git repository.


  10. Save your changes.
  11. You may test your Freestyle job by either:
    - Jenkins: select "Build with parameters" and launch a build.
    - Git: commit some changes and wait for SCM polling (if enabled) to pick up the changes and launch a build.

 

Pipeline

  1. Create a new Pipeline.
  2. Deployment script is not detailed here. To use IBM Cloud DevOps with the Jenkins pipeline project, you can follow the declarative or scripted jenkinsfile.

Publish the status of your pipeline stages to your Bluemix Toolchain

Configure your Jenkins pipelines to send notifications to tools integrated to your Bluemix Toolchain (e.g. Slack, PagerDuty).

  • Ensure you added the 5 required environment variables to your script, as detailed here.

    environment {
    	IBM_CLOUD_DEVOPS_CREDS = credentials('IBM_CLOUD_DEVOPS_CREDS')
    	IBM_CLOUD_DEVOPS_ORG = 'dlatest'
    	IBM_CLOUD_DEVOPS_APP_NAME = 'Weather-V1'
    	IBM_CLOUD_DEVOPS_TOOLCHAIN_ID = '1320cec1-daaa-4b63-bf06-7001364865d2'       
    	IBM_CLOUD_DEVOPS_WEBHOOK_URL =
    'https://jenkins:5a55555a-a555-5555-5555-a555aa55a555:55555555-5555-5555-5555-555555555555@devops-api.ng.bluemix.net/v1/toolint/messaging/webhook/publish'
    }
  • Use the notifyOTC command
  • (required) stageName - the name of the current pipeline stage.
  • (required) status - the completion status of the current pipeline stage. ('SUCCESS', 'FAILURE', and 'ABORTED' will be augmented with color)
  • (optional) webhookUrl - the webhook obtained from the Jenkins card on your toolchain.
  • Declarative Pipeline Example:

    stage('Deploy') {
        steps {
          ...
        }
        post {
            success {
                notifyOTC stageName: "Deploy", status: "SUCCESS"
            }
            failure {
                notifyOTC stageName: "Deploy", status: "FAILURE"
            }
        }
    }

Track deployment of code changes

Configure your Jenkins pipelines to send deployable mapping messages to your Bluemix Toolchain,
to track code deployments through tags, labels, and comments in your Git repository.

Use this notification only for status 'SUCCESS'. Any other status will be discarded.

  • Add a new environment variable to your script:
    IBM_CLOUD_DEVOPS_SPACE: the bluemix space where your application is deployed

    environment {
    	IBM_CLOUD_DEVOPS_CREDS = credentials('IBM_CLOUD_DEVOPS_CREDS')
    	IBM_CLOUD_DEVOPS_ORG = 'dlatest'
     	IBM_CLOUD_DEVOPS_SPACE= 'production'
    	IBM_CLOUD_DEVOPS_APP_NAME = 'Weather-V1'
    	IBM_CLOUD_DEVOPS_TOOLCHAIN_ID = '1320cec1-daaa-4b63-bf06-7001364865d2'       
    	IBM_CLOUD_DEVOPS_WEBHOOK_URL =
    'https://jenkins:5a55555a-a555-5555-5555-a555aa55a555:55555555-5555-5555-5555-555555555555@devops-api.ng.bluemix.net/v1/toolint/messaging/webhook/publish'
    }
  • Use the sendDeployableMessage command
  • (required) status - the completion status of the current pipeline stage: 'SUCCESS'
  • (optional) webhookUrl - the webhook obtained from the Jenkins card on your toolchain.
  • Declarative Pipeline Example:

    stage('Deploy') {
        steps {
          ...
        }
        post {
            success {
                notifyOTC stageName: "Deploy", status: "SUCCESS"
    			sendDeployableMessage status: "SUCCESS"
            }
            failure {
                notifyOTC stageName: "Deploy", status: "FAILURE"
            }
        }
    }



Change Log

Version 1.0 (May 16th, 2017)

  • First release.

Version 1.0.1 (May 17th, 2017)

  • Updated description.

Version 1.0.2 (May 25th, 2017)

  • Fixed URL encoding issue

Version 1.0.3 (June 2nd, 2017)

  • Fixed URL encoding issue for policy dropdown list
  • Minor text fix in error message

Version 1.1.0 (June 08, 2017)

  • Added Notifying toolchains section
ArchivesGet past versions
Labels
This plugin has no labels