IBM Cloud DevOps1.0.1Minimum Jenkins requirement: 2.46.2ID: ibm-cloud-devops
This plugin can be used to integrate your Jenkins pipelines and jobs with IBM DevOps Insights offering. The IBM DevOps Insights offering tracks your deployment risk based on the data that you publish to it. It provides Gates so that you can stop builds from getting deployed if the Gate policy is not met. The offering also provides analysis of your Git repo. For example, it can provide trends for large commits, error prone files, and team dynamics. Very soon, the offering will provide more trends, e.g., Deploy Frequency, Build Frequency, Unit Tests and Code Coverage and Function Verification Tests for builds that have deployed to production or other environments.
Here is a dashboard showing 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. Read about toolchains.
- Create promotion policies
- Install 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.
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.
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
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
Tip: If you are using the the scripted pipeline format, set your credentials with
withCredentials and your environment with
withEnv instead of
environment, which are used in the example below. See the Jenkins documentation for more about
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.
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:
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.
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.
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.
Communicating with toolchains
Send pipeline status to Bluemix toolchains by using the
notifyOTC command. To learn more about integrating Jenkins with toolchains, see the documentation. You can disregard steps 6d through 6f, as they only apply to freeform Jenkins projects.
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:
Examples declarative and scripted pipeline
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.
Open the configuration of any jobs that you have, such as build, test, or deployment.
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 deployment jobs, use Publish deployment information to IBM Cloud DevOps.
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:
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.
These images show example configurations:
Publish build information
Publish 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.
Version 1.0 (May 16th, 2017)
- First release.
Version 1.0.1 (May 17th, 2017)
- Updated description.