Publishing a build record

You can publish a build record by using Jenkins to integrate your projects with IBM Cloud® DevOps Insights. Build records notify DevOps Insights when a build is complete. This record contains the application name, branch, build ID, reference to Git repo, and other fields. You must publish build records to view any test records, deployment records, or evaluate policies in DevOps Insights.

IBM Cloud® DevOps Insights tracks deployment risk based on published test data. When you integrate Jenkins with DevOps Insights, you are instrumenting DevOps Insights to gather information from your Jenkins project. Information that is gathered is presented in the DevOps Insights dashboard to provide visibility into your DevOps process.

Before you begin

You must have a toolchain. For more information, see Creating toolchains.

Add the Jenkins tool to your app's toolchain. For more information, see Configure Jenkins.

Publishing build records with Jenkins

These variables are required for the pipeline to integrate with DevOps Insights.

Table 1. Jenkins environment variables and definitions
Environment variable	Definition
`IBM_CLOUD_DEVOPS_API_KEY`	A unique code that is passed in to an application programming interface (API) to identify the calling application or user. Store the API key as Jenkins credentials. (secret text type).
`IBM_CLOUD_DEVOPS_APP_NAME`	The name of the application that your toolchain deploys. If applicationName parameter is passed to the step job, then this value is ignored for that step.
`IBM_CLOUD_DEVOPS_TOOLCHAIN_ID`	The ID of your toolchain.

For each command, you need to specify the toolchain ID to export the environment variable. These environment variables and credentials are used by the IBM Cloud® DevOps Insights plug-in to interact with DevOps Insights. Here is an example of setting them in the declarative pipeline format.

environment {
        IBM_CLOUD_DEVOPS_API_KEY = credentials('BM_API_KEY')
        IBM_CLOUD_DEVOPS_APP_NAME = 'Weather-App'
        IBM_CLOUD_DEVOPS_TOOLCHAIN_ID = '1111111-aaaa-2222-bbbb-333333333'
    }

For more information about creating an API key, see Managing user API keys.

For more information about your toolchain ID, see Identifying your toolchain ID.

Publish build records with the publishBuildRecord step. This step requires four parameters. It can also accept one optional parameter.

Table 2. Publishing build records parameters and definitions
Parameter	Definition
`gitBranch`	The name of the Git Branch that the build uses.
`gitCommit`	The Git commit's ID that the build uses.
`gitRepo`	The URL of the Git repository.
`result`	The result of the build stage. The value is SUCCESS or FAIL.
`buildNumber`	Optional: The set value to any string that represents version number.
`applicationName`	Optional: Set the application name. If this value is set the environment variable, `IBM_CLOUD_DEVOPS_APP_NAME` is ignored.

Here are the parameters in an example command:

stages {
    Stage(`Build) {
        environmnet {
            // get git commit from Jenkins
            GIT_COMMIT = sh(returnStdout: true, script: 'git rev-parse HEAD').trim()
            GIT_BRANCH = 'master'
            GIT_REPO = 'https:github.com/xunronli-ibm/DemoDRA/'
        }
        steps {
            echo "building"
        }
        // post build section to use "publishBuildRecord" method to publish build record
        post {
            success {
                publishBuildRecord gitBranch: "${GIT_BRANCH}", gitCommit: "${GIT_COMMIT}", gitRepo: "${GIT_REPO}", result:"SUCCESS"
            }
            failure {
                publishBuildRecord gitBranch: "${GIT_BRANCH}", gitCommit: "${GIT_COMMIT}", gitRepo: "${GIT_REPO}", result:"FAIL"
            }
        }
    }
}

The Jenkins Pipeline doesn't show 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().

DevOps Insights steps

The Cloud DevOps plug-in adds four steps to Jenkins pipelines for you to use. Use these steps in your pipelines to interact with DevOps Insights. Add these steps to your pipeline definition wherever you need them to run. For example, you might upload test results after you run a test, and then evaluate those results at a gate after they are uploaded.

Table 3. DevOps Insights steps and uses
Step	Use
`publishBuildRecord`	Publishes build information
`publishTestResult`	Publishes test results
`publishDeployRecord`	Publishes deployment records
`evaluateGate`	Enforces policies

By default, the version number is set to be {pipeline name}:{build number}, you can also set the custom version number in each step

Sample pipeline and code

Here are two complete pipeline examples that are defined as declarative Jenkins file and a scripted Jenkins file.

The Git repo contains a sample nodejs application code, tests, and Jenkins file that you can experiment with. Fork the repo and modify the Jenkins file with your actual information.

If you didn't install NodeJS in your Jenkins environment, you might have to install the node.js Jenkins plug-in. If you installed NodeJS, you can comment out the "tools" section in the Jenkins file.

Viewing Build Frequency

When this build job completes, the pipeline publishes a message to DevOps Insights that a build is complete. You can view the build record on the Build Frequency page. To view the Build Frequency page, use the following steps.

From the IBM Cloud console, click the menu icon , and select DevOps.
Select your toolchain.
From your toolchain's Overview page, on the IBM Cloud tools card, click DevOps Insights.
Click Build Frequency.

Next steps

Learn how to publish a deployment record by using Jenkins.