Jenkins

Integrating Jenkins with Hivel allows you to gain data-driven insights into your development workflow. Follow these steps to set up the integration correctly.

System Requirements

Before proceeding, ensure the following: ✅ You have Admin access to Jenkins. (Preferably, a DevOps engineer should handle this)

Check if the below plugins are installed on Jenkins. If not, install them.

Plugin Name	Description	Link	Status
HTTP Request Plugin	Enables making HTTP requests within Jenkins pipelines.	HTTP Request | Jenkins plugin	Need to install
Timestamper Plugin	Adds timestamps to Jenkins build logs for better debugging.	Timestamper | Jenkins plugin	Need to install
Pipeline (Workflow Aggregator)	Provides the essential pipeline functionality in Jenkins.	Pipeline | Jenkins plugin	Mostly Already installed
Git Plugin	Enables Jenkins to fetch and manage source code from Git repositories.	Git | Jenkins plugin	Mostly Already installed
Credentials Binding Plugin	Allows securely storing and using credentials in Jenkins pipelines.	Credentials Binding | Jenkins plugin	Mostly Already installed
Groovy Plugin	Allows running Groovy scripts within Jenkins.	Groovy | Jenkins plugin	Mostly Already installed

How to Install These Plugins:

1. Go to Manage Jenkins → Manage Plugins → Available Plugins.

2. Search for the plugins listed above and install them.

3. Restart Jenkins after installation (if prompted).

Required Credentials for Integration

During the integration, you'll need:

• Organization ID (Generated in the Hivel application)

• API Key (Generated in the Hivel application)

Retrieving Your Organization ID and API Key

1. Open the Hivel application and navigate to Integrations under the Settings.

2. Locate the Jenkins Integration card and click Connect.

   
3. Follow the given steps to start your integration.

   
4. By clicking on generate your Organization ID and API Key will be generated.

   
5. Use these fields while integrating with Jenkins. The steps for where to apply them are provided on the following page.

6. If you find it difficult, don’t worry! You can always reach out to us for assistance at [e-mail].

Configuring Credentials in Jenkins

1. Log in to your Jenkins application.

2. From the side navigation, select Manage Jenkins.

   
3. Click on Credentials.

   
4. Click on global under Stores scoped to Jenkins

   
5. Choose Add Credentials - you will need to do this twice (once for the Organization ID and once for the API Key).

   
6. From the dropdown, select Secret text.

   
7. After selecting Secret text from the dropdown, fill in the details twice as follows:

   1. Adding the API Key

      1. ID: hivel-jenkins-api-key

      2. Secret: {your API key} (copied from Hivel)

      3. Description: This is the Jenkins API key from Hivel

      4. Click Save

   2. Repeat the process again for Adding the Organization ID

      1. ID: hivel-org-id

      2. Secret: {your Organization ID} (copied from Hivel)

      3. Description: This is the Jenkins Organization ID from Hivel

      4. Click Save

8. Once you have completed the above steps, your Jenkins Global Credentials should display the following entries:

   

Changes to pipeline script

1. Go to Dashboard

2. Select any pipeline->Configure->Edit Pipeline

In the pipeline script, add the following:

environment {
    WEBHOOK_URL = 'https://app.hivel.ai/insightlyapi/webhook/jenkins'
    ORG_ID = credentials('hivel-org-id')        // Organization ID from Hivel
    API_KEY = credentials('hivel-jenkins-api-key')  // API Key from Hivel
}

And this to your pipeline initialization code:

stage('Initialize') {
    steps {
        script {
            // For build duration tracking
            env.BUILD_START_TIME = System.currentTimeMillis()
            
            // For stage metrics collection
            stageData = []
        }
    }
}

How to Wrap Your Stage Code for Metrics Collection

For each additional stage you add, ensure you wrap your existing commands with the following snippet. This wrapping captures the start time, end time, duration, and status of the stage:

def stageStart = System.currentTimeMillis()
try {
    // Your stage commands here.
    def stageEnd = System.currentTimeMillis()
    stageData.add([
        stage_name: "Your Stage Name",
        start_time: new Date(stageStart).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
        end_time:   new Date(stageEnd).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
        duration:   ((stageEnd - stageStart) / 1000) as int,
        status:     "SUCCESS"
    ])
} catch (Exception e) {
    def stageEnd = System.currentTimeMillis()
    stageData.add([
        stage_name: "Your Stage Name",
        start_time: new Date(stageStart).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
        end_time:   new Date(stageEnd).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
        duration:   ((stageEnd - stageStart) / 1000) as int,
        status:     "FAILED",
        error_message: e.getMessage()
    ])
    throw e
}

• Insert your stage commands where indicated.

• This snippet ensures that each stage’s metrics are captured and included in the final payload sent to Hivel.

API call from Jenkins

Add the below code after each stage:

post {
        always {
            script {
                // Capture overall build end time and calculate total build duration
                def buildEndTime = System.currentTimeMillis()
                def buildStartTime = env.BUILD_START_TIME.toLong()
                
                // Retrieve Git information from scmVarsData if available; fallback to shell commands if not.
                def branchName = scmVarsData?.GIT_BRANCH ?: sh(script: "git rev-parse --abbrev-ref HEAD", returnStdout: true).trim()
                def commitID   = scmVarsData?.GIT_COMMIT ?: sh(script: "git rev-parse HEAD", returnStdout: true).trim()
                
                // Construct the payload with build metrics and stage data for Hivel integration
                def payload = [
                    org_id      : env.ORG_ID.toInteger(),
                    job_name    : env.JOB_NAME,
                    build_number: env.BUILD_NUMBER.toInteger(),
                    status      : currentBuild.result ?: 'SUCCESS',
                    build_url   : env.BUILD_URL,
                    start_time  : new Date(buildStartTime).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
                    end_time    : new Date(buildEndTime).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
                    duration    : ((buildEndTime - buildStartTime) / 1000) as int,
                    git         : [
                        commit         : commitID,
                        branch         : branchName,
                        author         : sh(script: "git log -1 --pretty=format:'%an'", returnStdout: true).trim(),
                        author_email   : sh(script: "git log -1 --pretty=format:'%ae'", returnStdout: true).trim(),
                        commit_message : sh(script: "git log -1 --pretty=format:'%s'", returnStdout: true).trim(),
                        repository     : sh(script: "git config --get remote.origin.url", returnStdout: true).trim()
                    ],
                    triggered_by: sh(script: "git log -1 --pretty=format:'%ae'", returnStdout: true).trim(),
                    node        : env.NODE_NAME,
                    jenkins_version: sh(script: "jenkins --version || echo 'Unknown'", returnStdout: true).trim(),
                    stages      : stageData
                ]
                
                // Convert the payload to JSON format
                def payloadJson = groovy.json.JsonOutput.toJson(payload)
                echo "Payload: ${payloadJson}"
                
                // Send the payload to the Hivel endpoint using the httpRequest step
                httpRequest(
                    url: env.WEBHOOK_URL,
                    httpMode: 'POST',
                    contentType: 'APPLICATION_JSON',
                    customHeaders: [[name: 'X-API-Key', value: env.API_KEY]],
                    requestBody: payloadJson,
                    ignoreSslErrors: true
                )
            }
        }
    }

Sample Script

Once the code wrapping is done, your code will look similar to the sample script in the next tab.

Sample Script

pipeline {
    agent any

    environment {
        // Hivel Integration configuration
        WEBHOOK_URL = 'https://app.hivel.ai/insightlyapi/webhook/jenkins'
        ORG_ID      = credentials('hivel-org-id')        // Your Hivel Organization ID
        API_KEY     = credentials('hivel-jenkins-api-key') // Your Hivel API Key
    }

    stages {
        // -------------------------------
        // Stage: Initialize
        // -------------------------------
        stage('Initialize') {
            steps {
                script {
                    // Capture overall build start time and initialize a list for stage metrics
                    env.BUILD_START_TIME = System.currentTimeMillis()
                    stageData = []
                }
            }
        }

        // -------------------------------
        // Stage: Checkout Code
        // -------------------------------
        stage('Checkout Code') {
            steps {
                script {
                    // Capture the start time for the Checkout stage
                    def stageStart = System.currentTimeMillis()
                    try {
                    
                        // Checkout the repository using Git; credentials and branch are specified here.
                        // The returned data (e.g., branch and commit information) is stored in 'scmVarsData'
                        scmVarsData = checkout([
                            $class: 'GitSCM',
                            branches: [[name: 'dev']],
                            userRemoteConfigs: [[
                                url: 'https://gitlab.com/my-org/hello-world.git', 
                                credentialsId: 'gitlab-token'
                            ]]
                        ])
                        
                        def stageEnd = System.currentTimeMillis()
                        // Record stage metrics as SUCCESS
                        stageData.add([
                            stage_name: "Checkout Code",
                            start_time: new Date(stageStart).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
                            end_time:   new Date(stageEnd).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
                            duration:   ((stageEnd - stageStart) / 1000) as int,
                            status:     "SUCCESS"
                        ])
                    } catch (Exception e) {
                        def stageEnd = System.currentTimeMillis()
                        // Record stage metrics as FAILED and capture the error message
                        stageData.add([
                            stage_name: "Checkout Code",
                            start_time: new Date(stageStart).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
                            end_time:   new Date(stageEnd).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
                            duration:   ((stageEnd - stageStart) / 1000) as int,
                            status:     "FAILED",
                            error_message: e.getMessage()
                        ])
                        // Rethrow the exception to mark the build as failed
                        throw e
                    }
                }
            }
        }

        // -------------------------------
        // Add additional stages below as required for your pipeline...
        // For example, you might add stages for building, testing, or deploying:
        // stage('Build') { ... }
        // stage('Test') { ... }
        // stage('Deploy') { ... }
    }

    post {
        always {
            script {
                // Capture overall build end time and calculate total build duration
                def buildEndTime = System.currentTimeMillis()
                def buildStartTime = env.BUILD_START_TIME.toLong()
                
                // Retrieve Git information from scmVarsData if available; fallback to shell commands if not.
                def branchName = scmVarsData?.GIT_BRANCH ?: sh(script: "git rev-parse --abbrev-ref HEAD", returnStdout: true).trim()
                def commitID   = scmVarsData?.GIT_COMMIT ?: sh(script: "git rev-parse HEAD", returnStdout: true).trim()
                
                // Construct the payload with build metrics and stage data for Hivel integration
                def payload = [
                    org_id      : env.ORG_ID.toInteger(),
                    job_name    : env.JOB_NAME,
                    build_number: env.BUILD_NUMBER.toInteger(),
                    status      : currentBuild.result ?: 'SUCCESS',
                    build_url   : env.BUILD_URL,
                    start_time  : new Date(buildStartTime).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
                    end_time    : new Date(buildEndTime).format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")),
                    duration    : ((buildEndTime - buildStartTime) / 1000) as int,
                    git         : [
                        commit         : commitID,
                        branch         : branchName,
                        author         : sh(script: "git log -1 --pretty=format:'%an'", returnStdout: true).trim(),
                        author_email   : sh(script: "git log -1 --pretty=format:'%ae'", returnStdout: true).trim(),
                        commit_message : sh(script: "git log -1 --pretty=format:'%s'", returnStdout: true).trim(),
                        repository     : sh(script: "git config --get remote.origin.url", returnStdout: true).trim()
                    ],
                    triggered_by: sh(script: "git log -1 --pretty=format:'%ae'", returnStdout: true).trim(),
                    node        : env.NODE_NAME,
                    jenkins_version: sh(script: "jenkins --version || echo 'Unknown'", returnStdout: true).trim(),
                    stages      : stageData
                ]
                
                // Convert the payload to JSON format
                def payloadJson = groovy.json.JsonOutput.toJson(payload)
                echo "Payload: ${payloadJson}"
                
                // Send the payload to the Hivel endpoint using the httpRequest step
                httpRequest(
                    url: env.WEBHOOK_URL,
                    httpMode: 'POST',
                    contentType: 'APPLICATION_JSON',
                    customHeaders: [[name: 'X-API-Key', value: env.API_KEY]],
                    requestBody: payloadJson,
                    ignoreSslErrors: true
                )
            }
        }
    }
}

• Once the changes are done, click on Apply -> Save.

• Repeat the steps for each stage of your pipeline script. Please check the indentation while wrapping the code.

• Run the build once changes are made to all the stages.

These are the details we will be receiving from Jenkins upon successful integration:

API Details

Base URL: https://app.hivel.ai/insightlyapi/webhook/jenkins
Method: POST
Headers:
    Content-Type: application/json
    X-API-Key: [API key from credentials]

Curl Request

curl --location \
--request POST 'https://app.hivel.ai/insightlyapi/webhook/jenkins' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data-raw '{
    "org_id": 123,
    "job_name": "pipeline-job-name",
    "build_number": 45,
    "status": "SUCCESS",
    "build_url": "http://jenkins-url/job/pipeline-job-name/45",
    "start_time": "2024-02-06T10:00:00Z",
    "end_time": "2024-02-06T10:15:00Z",
    "duration": 900,
    "git": {
        "commit": "abc123def456",
        "branch": "dev",
        "author": "John Doe",
        "author_email": "[e-mail]",
        "commit_message": "Feature update",
        "repository": "https://gitlab.com/myorganization/hello-world.git"
    },
    "triggered_by": "[e-mail]",
    "node": "jenkins-node-1",
    "jenkins_version": "2.426.1",
    "stages": [
        {
            "stage_name": "Stage 1",
            "start_time": "2024-02-06T10:00:00Z",
            "end_time": "2024-02-06T10:05:00Z",
            "duration": 300,
            "status": "SUCCESS"
        },
        "...",
        {
            "stage_name": "Stage N",
            "start_time": "2024-02-06T10:10:00Z",
            "end_time": "2024-02-06T10:15:00Z",
            "duration": 300,
            "status": "SUCCESS"
        }
    ]
}'

Payload

Payload Fields Explanation

• org_id: Organization identifier (Integer)

• job_name: Name of the Jenkins job

• build_number: Jenkins build number

• status: Build status (e.g., "SUCCESS", "FAILED")

• build_url: URL to access build details

• start_time: Timestamp when the build started

• end_time: Timestamp when the build completed

• duration: Build duration in seconds

• git: Git metadata object

  • commit: Latest commit hash

  • branch: Git branch name

  • author: Commit author name

  • author_email: Commit author email

  • commit_message: Commit message

  • repository: Git repository URL

• triggered_by: Email of build trigger user

• node: Jenkins node name

• jenkins_version: Jenkins server version

• stages: Array of stage objects

  • stage_name: Name of pipeline stage

  • start_time: Stage start timestamp

  • end_time: Stage end timestamp

  • duration: Stage duration in seconds

  • status: Stage status

  • error_message: Optional error description

The integration is considered complete once the build is run, successfully processed, and the integration card updates to "Connected".

If you need any support at any point, please feel free to reach out to us at [e-mail]. We’re happy to assist you!