Quick Info
Description
With this Jenkins plugin, you can run Jenkins jobs as a part of a deployment plan in HCL Accelerate. You can run jobs that trigger the creation of a version in an HCL Accelerate pipeline and persist properties on that version that can be used as input properties in other Jenkins builds. This plugin passes the required data from Git to the HCL Accelerate pipeline.Quick Info
Summary
The HCL Accelerate plugin for Jenkins allows you to perform the following functions:
- Post job metadata to your HCL Accelerate instance.
- Invoke jobs from HCL Accelerate to trigger jobs and pipelines without a special firewall configuration.
- Updates status of running jobs with links to the execution.
- Job executions create versions in an HCL Accelerate pipeline.
- Detects quality data provided by IBM Deployment Risk Analytics.
Compatibility
Must be running HCL Accelerate version 2.0 or later to use the plugin.
Installation
Process steps for the Jenkins plugin includes the following:
- Generate an Integration ID and Integration token.
- Install the plugin on your Jenkins instance.
- Populate the Jenkins configuration with Integration ID, Integration token, and Jenkins credentials.
- On the HCL Accelerate home page, click Settings > Integrations > Plugins and locate the Jenkins plugin in the table.
- Click the Add integration button to display the Add Jenkins Integration window.
- In the Enter a name to identify this integration from others field, enter a logical name representing the Jenkins instance you are connecting to HCL Accelerate.
- Click Create to generate an Integration ID and Integration token under Generated credentials.
- In a text editor, copy and paste both the Integration ID and Integration token by clicking the copy to clipboard icon on the right side of each value.
- Click Save.
- In Jenkins on the left navigation pane, click Up > Manage Jenkins > Manage Plugins. Note: Manage Plugins is located in the System Configuration section of the page.
- Navigate to hcl-accelerate.hpi and click the Download button to save the file.
- In Jenkins on the Manage Plugins page, click the Advanced tab and in the Upload Plugin section, upload the file downloaded in the previous step.
- On the Manage Jenkins page in the System Configuration section, click Configure System and locate the HCL Accelerate section and perform the following:
-
- Copy and paste the Integration ID and Integration token from your text editor into the respective fields.
- In the Jenkins credentials drop-down, select and Add the required credentials.
- If you are configuring Jenkins integrations on Kubernetes or Openshift instances, click the Advanced button, and in the Rabbit MQ Port field, enter the port number.
Note: Typically, the port number is 31672 instead of the default value of 5672 that does not work. - Click the Save button.
- Click the Test Connection button to validate your connection with HCL Accelerate. Note: Upon successful connection, your data is accessible in HCL Accelerate.
Manual build
To perform a manual build for the plugin directly from the GitHub repository, clone the repository from https://github.com/UrbanCode/hcl-accelerate-plugin
From the root directory, run either of the following commands:
mvn install
mvn clean package -DskipTests
with the-DskipTests
flag enabled to expedite the build without running tests
Note: The plugin requires Java 8 or later. To avoid potential errors, delete the target
directory.
License
Copyright© HCL Technologies Ltd. 2018, 2019, 2020, 2021. All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Usage
- Posting job metadata to your HCL Accelerate instance – As you create and edit jobs, the metadata for the jobs is uploaded including the job names and parameter names so jobs can be invoked from HCL Accelerate within the HCL Accelerate security model.
- Invoke jobs from HCL Accelerate – An authenticated, encrypted persistent connection is established with HCL Accelerate so that you can trigger jobs and pipelines with no special firewall configuration.
- Updates status of running jobs – You will receive instant feedback in HCL Accelerate with links to the execution.
- Job executions can create versions in the HCL Accelerate pipeline – You will have the option to select Jenkins jobs as “input jobs” that create a version with special properties that you can specify.
Configuration properties
- Check gate in HCL Accelerat
- Upload Build to HCL Accelerate
- Upload Deployment to HCL Accelerate
- Upload JUnit Results to HCL Accelerate
- Upload JUnit Metrics File to HCL Accelerate
Check gate in HCL Accelerate
The CheckGate class is used to check gates applied on a particular stage of the HCL Accelerate pipeline for a particular versionId of an application.
step($class: 'CheckGate',
pipelineId: "63a4591b-4d0d-4b8d-a6fb-4e9e7d79e754",
stageName: "DEV",
versionId: "NWZkOWUyZjYtOGE3Yy00NmJhLTlmZD-#48",
)
Pipeline script
Check gate input properties
Name | Type | Description | Required | Property name |
---|---|---|---|---|
Pipeline ID | String | Pipeline ID from HCL Accelerate. | Yes | pipelineId |
Stage Name | String | Stage name of HCL Accelerate pipeline. | Yes | stageName |
Version ID | String | Version Id for particular application. | Yes | versionId |
Upload build to HCL Accelerate
The UploadBuild class is used to upload build data to HCL Accelerate. The revision parameter is important for linking the build to the work item via GitHub data (GIT_COMMIT in this case). The versionName is important for linking forward to deployments. The appName corresponds to the HCL Accelerate pipeline application name.
step($class: 'UploadBuild',
tenantId: "5ade13625558f2c6688d15ce",
revision: "${GIT_COMMIT}",
appName: "${ACCELERATE_APP_NAME}",
versionName:"${currentBuild.displayName}",
requestor: "admin",
id: "${currentBuild.displayName}"
)
Pipeline script
Upload build input properties
Name | Type | Description | Required | Property name |
---|---|---|---|---|
Tenant Id | String | Tenant Id from HCL Accelerate. | Yes | tenantId |
Build Name | String | Build Name to display in HCL Accelerate. | No | name |
Version Name | String | For linking forward to deployments. | No | versionName |
Requestor | String | Requestor Name to display in HCL Accelerate. | No | requestor |
Revision | String | For linking the build to the work item via GitHub data. | No | revision |
Status | String | One of start, in_progress, success, or failure. | No | status |
Start Time | String | Start time for this step (Default: CurrentTime). | No | startTime |
End Time | String | EndTime for this step (Default: CurrentTime). | No | endTime |
App Name (one of three required) | String | HCL Accelerate pipeline application name. | No | appName |
App Id (one of three required) | String | HCL Accelerate pipeline application Id. | No | appId |
App External Id (one of three required) | String | HCL Accelerate pipeline application External Id. | No | appExtId |
Debug | Boolean | For Getting debug logs. | No | debug |
Fatal | Boolean | Fail build on failed upload, rather than just making build unstable. | No | fatal |
Upload deployment to HCL Accelerate
The UploadDeployment class is used to upload deployment data to HCL Accelerate. The versionName parameter is critical for linking to build data. The appName corresponds to the HCL Accelerate pipeline application name, while environmentName and environmentId are used to identify the deployment environment.
step([$class:
'UploadDeployment',
tenantId: "5ade13625558f2c6688d15ce",
versionName: "${currentBuild.displayName}",
versionExtId: "${currentBuild.displayName}",
type: 'Jenkins',
environmentId: "${ACCELERATE_ENV_ID_DEV}",
environmentName: 'DEV',
appName: "${ACCELERATE_APP_NAME}",
description: '[Description ex: Terraform Deployment]',
initiator: "admin",
result: 'true'
])
Pipeline script
Upload deployment input properties
Name | Type | Description | Required | Property name |
---|---|---|---|---|
Tenant Id | String | Tenant Id from HCL Accelerate. | Yes | tenantId |
Name | String | Name to display in HCL Accelerate. | No | name |
Result | String | One of start, in_progress, success, or failure. | No | result |
Initiator | String | Initiator Name to display in HCL Accelerate | No | initiator |
Version Name | String | For linking to build data. | No | versionName |
Version External ID | String | For linking to build data. | No | versionExtId |
Type | String | Type of deployment job. | Yes | type |
Environment Name | String | To identify the deployment environment. | No | environmentName |
Environment ID | String | To identify the deployment environment. | No | environmentId |
ID | String | Unique Id for step. | No | id |
Description | String | Description of this step. | No | description |
Start Time | String | Start time for this step (Deafault: CurrentTime). | No | startTime |
End Time | String | EndTime for this step (Deafault: CurrentTime). | No | endTime |
App Name (one of three required) | String | HCL Accelerate pipeline application name. | No | appName |
App Id (one of three required) | String | HCL Accelerate pipeline application ID. | No | appId |
App External Id (one of three required) | String | HCL Accelerate pipeline application External ID. | No | appExtId |
Debug | Boolean | For Getting debug logs. | No | debug |
Fatal | Boolean | Fail build on failed upload, rather than just making build unstable. | No | fatal |
Upload JUnit results to HCL Accelerate
Type | Description | Required | Property name |
---|---|---|---|
java.util.Map<java.lang.String, java.lang.String> | Upload JUnit Results to HCL Accelerate. | Yes | properties |
Upload metrics file to HCL Accelerate
The UploadMetricsFile class is used to upload metrics file into HCL Accelerate. The uploaded metrics file will be available in Insights in graphical form.
step($class: 'UploadMetricsFile',
tenantId: "5ade13625558f2c6688d15ce",
filePath: "junit.xml",
appName: "${ACCELERATE_APP_NAME}",
name:"Junit",
dataFormat: "junitXML",
pluginType: "junitXML",
testSetName: "Junit",
metricsRecordUrl: "${env.BUILD_URL}",
buildUrl: "${env.BUILD_URL}",
)
Pipeline script
Upload metrics file input properties
Name | Type | Description | Required | Property name |
---|---|---|---|---|
Tenant Id | String | Tenant Id from HCL Accelerate. | Yes | tenantId |
Name | String | Name to display in HCL Accelerate. | No | name |
File Path | String | Path to metrics file. | No | filePath |
Test Set Name | String | Name to test set. | No | testSetName |
Environment | String | Environment name to display in HCL Accelerate | Yes | environment |
Combine Test Suites | Boolean | No | combineTestSuites | |
Fatal | Boolean | Fail build on failed upload, rather than just making build unstable. | No | fatal |
Plugin Type | String | Plugin type for metrics file. | No | pluginType |
Data Format | String | Data format of metrics file. | Yes | dataFormat |
Record Name | String | Record Name to display in HCL Accelerate. | No | recordName |
Metric Definition ID | String | Metric Definition ID from HCL Accelerate. | No | metricDefinitionId |
Description | String | Description of this step. | No | description |
Execution Date | String | Time of execution that produced test results. Should be in Epoch milliseconds. Defaults to current time. | No | executionDate |
Build ID | String | Build ID to display in HCL Accelerate | No | buildId |
App Name (one of three required) | String | HCL Accelerate pipeline application name. | No | appName |
App Id (one of three required) | String | HCL Accelerate pipeline application Id. | No | appId |
App External Id (one of three required) | String | HCL Accelerate pipeline application External Id. | No | appExtId |