Jenkins Freestyle Integration with Ansible and Hivel Webhook

This guide walks you through integrating Jenkins Freestyle pipelines with Hivel using an Ansible playbook and webhook reporting. You’ll learn how to trigger a playbook, capture build and stage metadata, and send it to Hivel’s API endpoint for monitoring and analytics.

🧰 Prerequisites

Make sure the following are set up on your Jenkins server (typically an EC2 instance):

• ✅ Jenkins installed and accessible

• ✅ Admin access to Jenkins UI

• ✅ Ansible installed and available in PATH

• ✅ Git configured (for Git metadata collection)

📦 Required Plugin

Install the following plugin:

Plugin Name	Description
Groovy Postbuild Plugin	Allows running Groovy scripts after a build

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:

   

Step 2: Bind Secrets in Job Configuration

1. Open your Freestyle job(pipeline in your dashboards)

2. Go to the Environment section

3. Check Use secret text(s) or file(s)

4. Click Add and bind the credentials like this:

Variable Name	Credentials ID
HIVEL_ORG_ID	hivel-org-id
HIVEL_JENKINS_API_KEY	hivel-jenkins-api-key

Step 3: Install Ansible on Jenkins Server

Ensure Ansible is installed on the EC2/server where Jenkins is hosted.

For Amazon Linux 2:

sudo amazon-linux-extras enable ansible2
sudo yum install -y ansible

Run ansible --version on the Jenkins server to confirm installation.

Step 4: Add Build Step – Execute Ansible Playbook

Under Build Steps → Execute shell, add:

# Run Ansible playbook with JSON output
ANSIBLE_STDOUT_CALLBACK=json \
ansible-playbook ansible/dummy-stages.yml \
-i "localhost," --connection=local \
> ansible-output.json 2>&1 || true

This ensures that:

• The playbook runs locally

• Output is saved in JSON format to ansible-output.json

• Even on errors, the script doesn’t fail the job

Note : replace the path of your ansible file with “ansible/dummy-stages.yml”. Invoking ansible like this will only help us to get insights from ansible playbook.

Step 5: Add Groovy Postbuild Script for Webhook Reporting

Under Post-build Actions:

1. Add → Groovy Postbuild

2. Paste the Groovy webhook script (Full Version) (provided below)
3. Uncheck the box labeled Use Groovy Sandbox

4. Approve script (open will appear once you enter script in groovy text box)

5. Save the job

if you check “use groovy sandbox” you might require to allow all script to be executed from settings section : go to Manage Jenkins → In-process Script Approval and approve the pending script.

Add groovy postbuild

Sample Webhook Payload Sent

{
  "org_id": 12345,
  "job_name": "freestyle-ansible-job",
  "build_number": 12,
  "status": "SUCCESS",
  "build_url": "https://jenkins.example.com/job/freestyle-ansible-job/12/",
  "start_time": "2025-04-08T10:12:00Z",
  "end_time": "2025-04-08T10:12:45Z",
  "duration": 45.25,
  "git": {
    "commit": "abc123...",
    "branch": "main",
    "author": "John Doe",
    "author_email": "[e-mail]",
    "commit_message": "Add API integration",
    "repository": "[e-mail]:project/repo.git"
  },
  "triggered_by": "john.doe",
  "stages": [
    {
      "stage_name": "Ensure packages installed",
      "start_time": "2025-04-08T10:12:05.000000Z",
      "end_time": "2025-04-08T10:12:10.000000Z",
      "duration": 5.0,
      "status": "SUCCESS",
      "message": "All packages present"
    }
  ]
}

Groovy Postbuild Script

/**
* JenkinsBuildData class handles all build data collection and processing
* for Jenkins freestyle jobs. It collects build metadata, Git information,
* and stage execution details, then sends them to a webhook endpoint.
*
* This script is designed to work with Jenkins freestyle jobs and expects:
* 1. A workspace directory with Git repository
* 2. Ansible output file (ansible-output.json) in the workspace
* 3. Environment variables for configuration
*/
import hudson.model.Cause
import groovy.json.JsonOutput
import groovy.json.JsonSlurper
import java.text.SimpleDateFormat
import java.util.TimeZone

class JenkinsBuildData {

   def env
   def manager
   def workspace
   def logger

   // API endpoint configuration
   static final String API_ENDPOINT = 'https://app.hivel.ai/insightlyapi/webhook/jenkins'
   static final int HTTP_TIMEOUT = 5000
   static final String DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"
   static final String DATE_FORMAT_SIMPLE = "yyyy-MM-dd'T'HH:mm:ss'Z'"

   /**
    * Constructor initializes the build data collector with Jenkins environment
    * @param manager Jenkins build manager instance
    * @throws IllegalArgumentException if manager is null
    */
   JenkinsBuildData(manager) {
       if (!manager) {
           throw new IllegalArgumentException('Manager cannot be null')
       }
       this.manager = manager
       this.env = manager.build.environment
       this.workspace = new File(this.env.WORKSPACE)
       this.logger = manager.listener.logger
   }

   /**
    * Validates the workspace and required environment variables
    * @return boolean indicating if all required conditions are met
    */
   private boolean validateEnvironment() {
       if (!workspace.exists()) {
           logger.println "Error: Workspace directory does not exist: ${workspace.absolutePath}"
           return false
       }

       if (!env.JOB_NAME) {
           logger.println 'Error: JOB_NAME environment variable is not set'
           return false
       }

       if (!env.BUILD_NUMBER) {
           logger.println 'Error: BUILD_NUMBER environment variable is not set'
           return false
       }

       return true
   }

   /**
    * Calculates duration between two timestamps in seconds with 2 decimal precision
    * @param start Start timestamp
    * @param end End timestamp
    * @return Duration in seconds
    */
   private double calculateDuration(String start, String end) {
       if (!start || !end) return 0
       try {
           def sdf = new SimpleDateFormat(DATE_FORMAT)
           sdf.setTimeZone(TimeZone.getTimeZone('UTC'))
           def startDate = sdf.parse(start)
           def endDate = sdf.parse(end)
           def durationMs = endDate.time - startDate.time
           // Convert milliseconds to seconds and round to 2 decimal places
           return (durationMs / 1000.0).round(2)
       } catch (Exception e) {
           return 0
       }
   }

   /**
    * Parses build stages from ansible-output.json file
    * @return List of stage objects containing execution details
    */
   def parseAnsibleStages() {
       def stages = []
       try {
           def ansibleOutputFile = new File(workspace.toString() + '/ansible-output.json')
           if (!ansibleOutputFile.exists() || !ansibleOutputFile.text?.trim()) {
               return stages
           }

           def jsonContent = ansibleOutputFile.text.substring(
               ansibleOutputFile.text.indexOf('{'),
               ansibleOutputFile.text.lastIndexOf('}') + 1
           )
           def ansibleOutput = new JsonSlurper().parseText(jsonContent)

           if (!ansibleOutput.plays || !ansibleOutput.plays[0]?.tasks) {
               return stages
           }

           ansibleOutput.plays[0].tasks.each { task ->
               def hostInfo = task.hosts?.localhost
               if (!hostInfo || !(hostInfo.action in ['debug', 'fail'])) return

               def durationMs = calculateDuration(task.task.duration?.start, task.task.duration?.end)
               stages << [
                   stage_name : task.task.name ?: 'Unnamed Task',
                   start_time : task.task.duration?.start ?: '',
                   end_time   : task.task.duration?.end ?: '',
                   duration   : durationMs,
                   status     : determineTaskStatus(hostInfo),
                   message    : hostInfo.msg ?: hostInfo.message ?: 'No message provided'
               ]
           }
       } catch (Exception e) { }
       return stages
   }

   /**
    * Determines the status of a task based on its execution result
    * @param hostInfo Task execution information
    * @return Status string (FAILED, SKIPPED, CHANGED, SUCCESS, or UNKNOWN)
    */
   private String determineTaskStatus(hostInfo) {
       if (hostInfo.failed == true) return 'FAILED'
       if (hostInfo.skipped == true) return 'SKIPPED'
       if (hostInfo.changed == true) return 'CHANGED'
       if (hostInfo.failed != true && hostInfo.skipped != true) return 'SUCCESS'
       return 'UNKNOWN'
   }

   /**
    * Calculates build timing information
    * @return Map containing start_time, end_time (ISO8601 format), and duration (in seconds)
    */
   def getBuildTiming() {
       def startTime = manager.build.getStartTimeInMillis()
       def duration = manager.build.getDuration()
       def endTime = startTime + duration

       // If duration is 0, calculate from start time to current time
       if (duration == 0) {
           endTime = System.currentTimeMillis()
           duration = endTime - startTime
       }

       // Calculate duration in seconds and round to 2 decimal places
       def durationSec = Math.round(duration / 1000.0 * 100) / 100.0

       def dateFormat = new SimpleDateFormat(DATE_FORMAT_SIMPLE)
       dateFormat.setTimeZone(TimeZone.getTimeZone('UTC'))

       return [
           start_time: dateFormat.format(new Date(startTime)),
           end_time  : dateFormat.format(new Date(endTime)),
           duration  : durationSec
       ]
   }

   /**
    * Collects Git repository information
    * @return Map containing Git metadata (commit, branch, author, etc.)
    */
   def getGitInfo() {
       def gitCommit = env.GIT_COMMIT ?: executeCommand('git rev-parse HEAD')
       def gitBranch = (env.GIT_BRANCH ?: executeCommand('git rev-parse --abbrev-ref HEAD'))?.replaceAll('^origin/', '')
       def gitRepo = env.GIT_URL ?: executeCommand('git config --get remote.origin.url')

       def commitDetails = executeCommand("git log -1 --pretty=format:'%an|%ae|%s'").split('\\|', 3)

       return [
           commit        : gitCommit,
           branch        : gitBranch,
           author        : commitDetails.size() > 0 ? commitDetails[0].trim() : '',
           author_email  : commitDetails.size() > 1 ? commitDetails[1].trim() : '',
           commit_message: commitDetails.size() > 2 ? commitDetails[2].trim() : '',
           repository    : gitRepo
       ]
   }

   /**
    * Executes a shell command in the workspace directory
    * @param command Shell command to execute
    * @return Command output as string
    */
   def executeCommand(command) {
       try {
           def process = command.execute(null, workspace)
           process.waitFor()
           return process.text.trim()
       } catch (Exception e) {
           return ''
       }
   }

   /**
    * Determines who triggered the build
    * @return Username of the build triggerer
    */
   def getBuildTrigger() {
       def cause = manager.build.getCause(Cause.UserIdCause)
       return cause?.userName ?: 'Unknown'
   }

   /**
    * Builds the complete payload for the webhook
    * @param stages List of build stages
    * @return Complete payload map ready for JSON conversion
    */
   def buildPayload(stages) {
       def timing = getBuildTiming()
       def gitInfo = getGitInfo()

       return [
           org_id       : (env.HIVEL_ORG_ID ?: '0') as int,
           job_name     : env.JOB_NAME,
           build_number : env.BUILD_NUMBER as int,
           status       : manager.build.result.toString(),
           build_url    : env.BUILD_URL,
           start_time   : timing.start_time,
           end_time     : timing.end_time,
           duration     : timing.duration,
           git          : gitInfo,
           triggered_by : getBuildTrigger(),
           stages       : stages
       ]
   }

   /**
    * Sends the payload to the configured webhook endpoint
    * @param jsonPayload JSON string to send
    * @return boolean indicating if the request was successful
    */
   def sendHttpRequest(jsonPayload) {
       if (!jsonPayload) {
           logger.println 'Error: Cannot send empty payload'
           return false
       }

       def url = new URL(API_ENDPOINT)
       def conn = url.openConnection()

       try {
           conn.setRequestMethod('POST')
           conn.doOutput = true
           conn.setRequestProperty('Content-Type', 'application/json')

           def apiKey = env.HIVEL_JENKINS_API_KEY
           if (apiKey) {
               conn.setRequestProperty('API_KEY', apiKey)
           } else {
               logger.println 'Warning: HIVEL_JENKINS_API_KEY is not set'
           }

           conn.setConnectTimeout(HTTP_TIMEOUT)
           conn.setReadTimeout(HTTP_TIMEOUT)

           conn.outputStream.withWriter('UTF-8') { writer ->
               writer.write(jsonPayload)
           }

           def responseCode = conn.responseCode
           def responseText = conn.inputStream.text
           logger.println "Webhook response code: $responseCode"
           logger.println "Webhook response: $responseText"

           return responseCode >= 200 && responseCode < 300
       } catch (Exception e) {
           logger.println "Error sending request: ${e.message}"
           logger.println "Stack trace: ${e.stackTrace}"
           return false
       }
   }

}

// Main execution block
try {
   def buildData = new JenkinsBuildData(manager)

   // Validate environment before proceeding
   if (!buildData.validateEnvironment()) {
       throw new IllegalStateException('Environment validation failed')
   }

   def stages = buildData.parseAnsibleStages()
   def payload = buildData.buildPayload(stages)
   def jsonPayload = JsonOutput.toJson(payload)

   if (!buildData.sendHttpRequest(jsonPayload)) {
       throw new IllegalStateException('Failed to send build data to webhook')
   }

   manager.listener.logger.println 'Successfully processed and sent build data'
} catch (Exception e) {
   manager.listener.logger.println "Error: ${e.message}"
   manager.listener.logger.println "Stack trace: ${e.stackTrace}"
   throw e
}