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 plugins: "Webhook Step" or "HTTP Request" plugin

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
  • Parameterized Builds: Pass test parameters from Lathe Studio to Jenkins

Connecting Jenkins#

Step 1: Create an API Key

  1. Go to Settings > Organization > API Keys
  2. Click Create API Key
  3. Give it a name (e.g., "Jenkins CI")
  4. Select scopes:
    • builds:read - View builds
    • builds:create - Create new builds
  5. Copy the generated key (shown only once)

Step 2: Configure Jenkins Webhook

Option A: Using Jenkinsfile (Recommended)

Add to your Jenkinsfile:

pipeline {
    agent any
    
    stages {
        stage('Build') {
            steps {
                // Your build steps
            }
        }
        
        stage('Test') {
            steps {
                // Your test steps
            }
        }
    }
    
    post {
        always {
            script {
                def payload = """
                {
                    "build": {
                        "number": ${env.BUILD_NUMBER},
                        "phase": "COMPLETED",
                        "status": "${currentBuild.currentResult}",
                        "url": "${env.BUILD_URL}"
                    },
                    "project": {
                        "name": "${env.JOB_NAME}",
                        "url": "${env.JOB_URL}"
                    },
                    "scm": {
                        "branch": "${env.GIT_BRANCH ?: 'unknown'}",
                        "commit": "${env.GIT_COMMIT ?: 'unknown'}"
                    }
                }
                """
                
                httpRequest(
                    url: 'https://lathestudio.dev/api/webhooks/jenkins',
                    httpMode: 'POST',
                    contentType: 'APPLICATION_JSON',
                    requestBody: payload,
                    customHeaders: [
                        [name: 'Authorization', value: "Bearer ${env.PT_API_KEY}"]
                    ]
                )
            }
        }
    }
}

Option B: Using Job Configuration

  1. In Jenkins, go to your job
  2. Click Configure
  3. Scroll to Post-build Actions
  4. Add HTTP Request action:
    • URL: https://lathestudio.dev/api/webhooks/jenkins
    • HTTP Method: POST
    • Content Type: Application JSON
    • Request Body: Build payload (see below)
    • Custom Headers: Authorization: Bearer <your-api-key>

Step 3: Add API Key to Jenkins Credentials

  1. Go to Manage Jenkins > Manage Credentials
  2. Select the appropriate domain
  3. Click Add Credentials
  4. Choose Secret text
  5. Enter your API key as the secret
  6. ID: pt-api-key
  7. Click OK

Step 4: Test the Integration

  1. Run a Jenkins build
  2. Go to Releases page in Lathe Studio
  3. You should see the build in the Build Queue section
  4. Assign it to a release

Authentication Methods#

Method 1: API Key (Recommended)

Include the API key in the Authorization header:

Authorization: Bearer pt_live_xxxxxxxxxxxxxxxx

Method 2: Organization ID

Include your organization ID in a custom header:

X-Pt-Org-Id: your-org-uuid

How It Works#

  1. Build Completes → Jenkins sends webhook to /api/webhooks/jenkins
  2. Authentication → Webhook verifies API key or org ID
  3. Project Matching → System tries to match job name/URL to a project
  4. Queue or Create:
    • If project + active release found → Build created directly
    • If project found but no release → Queued for release assignment
    • If no project match → Queued for project + release assignment
  5. Assignment → User assigns queued builds via Releases page

Build Queue UI#

The Build Queue appears on the Releases page when there are pending builds:

  • Shows build name, source (Jenkins), project, commit/branch
  • Assign to Release: Select an active release for the project
  • Select Project: Navigate to projects if project not auto-detected
  • Reject: Remove build from queue (no build created)

Payload Format#

Jenkins webhooks should include this JSON payload:

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

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

Troubleshooting#

Builds not appearing

  1. Check Jenkins console output for HTTP request errors
  2. Verify API key is valid and not expired
  3. Ensure the webhook URL is correct
  4. Check Jenkins system logs for errors

Wrong project assigned

The system matches by:

  1. Job URL (exact match)
  2. Job name (partial match)
  3. Repository URL (if provided in payload)

You can manually assign to the correct project from the queue.

Rate limiting

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#

  • API keys are hashed using SHA-256 before storage
  • Only the first 12 characters are stored for identification
  • Keys can be revoked at any time
  • Store API keys in Jenkins Credentials, never in code
  • Use Jenkins credential masking to prevent key exposure in logs
  • 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 →