All Docs
Jenkins Integration Setup Guide

Jenkins Integration Setup Guide

This guide walks you through connecting Lathe Studio to Jenkins for CI/CD pipeline integration.

Prerequisites#

  • Jenkins instance (2.0+)
  • Jenkins job/build pipeline configured
  • Project admin access in Lathe Studio
  • Jenkins plugin: "Notification Webhook"

Overview#

The Jenkins integration enables:

  • CI/CD Webhooks: Automatically create builds when Jenkins jobs complete
  • Build Status Sync: Track Jenkins build status in Lathe Studio

Connecting Jenkins#

Step 1: Create a Jenkins Connection in Lathe Studio

  1. In Lathe Studio, open your project and go to Project Settings → Integrations
  2. Find Jenkins and click Connect
  3. Lathe Studio generates a webhook URL containing a unique token and a webhook secret — copy both

Step 2: Configure the Jenkins Plugin

Option A: Using the Job Configuration (Recommended)

  1. Install the Notification Webhook plugin in Jenkins (Manage Jenkins > Plugins)
  2. Go to your job configuration
  3. Add a Post-build action → Webhook Notification
  4. Set the URL to the webhook URL from Lathe Studio (includes ?token=...)
  5. Select the JSON payload format
  6. Save the job configuration

Option B: Using a Jenkinsfile

If you configure pipelines in code, add the webhook notification in a post-build step using the Notification Webhook plugin.

Step 3: Test the Integration

  1. Run a Jenkins build
  2. Open the Jenkins connection panel in Lathe Studio to see recent events
  3. If the job matches a pipeline config with auto-create enabled, a build appears on the Releases page

Authentication#

Jenkins webhooks are authenticated by the unique token in the webhook URL (?token=...), which identifies your project's connection. When a webhook secret is configured on the connection, requests must also carry a valid X-Jenkins-Signature HMAC-SHA256 signature of the payload.

How It Works#

  1. Build event fires → The Notification Webhook plugin posts to your webhook URL (/api/webhooks/jenkins?token=...)
  2. Authentication → The token identifies your project's connection; if a secret is configured, the X-Jenkins-Signature signature must also be valid
  3. Pipeline Matching → The Jenkins job name is matched against the pipeline configs on the connection
  4. Build Creation → When the matching pipeline has auto-create enabled (the default), a build is created when the job completes (COMPLETED phase)
  5. Review → Every event is recorded in the connection's recent events list, so you can confirm delivery and troubleshoot

Build Queue UI#

The Build Queue on the Releases page holds builds that arrived without a project or release assignment (for example, from the Bitbucket webhook). From the queue you can:

  • Assign to Release: Select an active release for the project
  • Select Project: Navigate to projects if the project was not auto-detected
  • Reject: Remove the build from the queue (no build created)

Payload Format#

The Notification Webhook plugin sends this JSON payload automatically:

{
  "name": "MyJob",
  "url": "https://jenkins.example.com/job/MyJob/",
  "build": {
    "number": 123,
    "phase": "COMPLETED",
    "status": "SUCCESS",
    "url": "https://jenkins.example.com/job/MyJob/123/",
    "scm": {
      "url": "https://jenkins.example.com/job/MyJob/",
      "branch": "main",
      "commit": "abc123def456"
    }
  }
}

Phase values: STARTED, COMPLETED, FINALIZED Status values: SUCCESS, FAILURE, UNSTABLE, ABORTED

Troubleshooting#

Builds not appearing

  1. Check the Jenkins system log for webhook delivery errors
  2. Verify the webhook URL includes the ?token= query parameter
  3. Ensure the job name matches a pipeline config on the connection
  4. Check the connection's recent events in Lathe Studio

Rate limiting

Results-ingest API keys are limited to 60 requests per minute by default. Contact support to increase limits.

SSL/TLS errors

If your Jenkins instance uses self-signed certificates:

  1. Use valid SSL certificates in production
  2. Or configure Jenkins to ignore SSL errors (not recommended)

Security#

  • The webhook URL token identifies your project's connection — treat it as a secret
  • Webhook secrets are stored encrypted and used for HMAC-SHA256 signature verification
  • All webhook communications use HTTPS

Unlinking Jenkins#

To disconnect:

  1. Go to your Jenkins job configuration
  2. Remove the HTTP Request post-build action
  3. Or remove the webhook code from your Jenkinsfile

Note: Previously created builds remain in Lathe Studio. New builds will not be created until reconnected.

Advanced Configuration#

Multi-Branch Pipelines

For multi-branch pipeline jobs:

pipeline {
    agent any
    
    post {
        always {
            script {
                def branchName = env.BRANCH_NAME
                def shouldNotify = branchName in ['main', 'develop', 'release/*']
                
                if (shouldNotify) {
                    // Send webhook
                }
            }
        }
    }
}

Blue Ocean Support

The integration works with both classic Jenkins and Blue Ocean pipelines.

For additional help, contact support.

← All DocsSettings →