Jenkins Integration

Automate your build pipeline with full job management and artifact tracking.

Table of contents

1. Overview
2. Configuration
   1. Connection Settings
   2. Credentials
3. Setup Steps
   1. 1. Generate API Token
   2. 2. Add the Integration
   3. 3. Select Jobs
4. Webhook Configuration
   1. Option A: Notification Plugin (Not Recommended)
   2. Option B: Post-Build Script (HTTP Request plugin or curl)
   3. Option C: Pipeline Step
5. Features
   1. Build Triggering
   2. Build Status Tracking
   3. SCM Correlation
   4. Artifact Access
   5. Console Output
6. Job Templates
   1. Unreal Engine Template
   2. Unity Template
   3. Creating a Job from Template
7. Webhook Payload Format
   1. Build Started
   2. Build Completed
8. Troubleshooting
   1. Connection Failed
   2. Authentication Failed
   3. CSRF Token Error
   4. Build Not Triggering
   5. Build Status Not Updating
9. API Reference
   1. Trigger Build
   2. Build Notification
   3. List Jobs
10. Best Practices

Overview

ButterStack provides comprehensive Jenkins integration:

• Build triggering from commits
• Job creation from templates
• Build status tracking
• Artifact and console output access
• SCM correlation (link builds to changelists)
• Multi-job support

Configuration

Connection Settings

Credentials

Setup Steps

1. Generate API Token

1. Log into Jenkins as your service account
2. Click your username > Configure
3. In API Token section, click Add new Token
4. Name it butterstack and click Generate
5. Copy the token (it won’t be shown again)

2. Add the Integration

1. Go to Project Settings > Integrations
2. Click Add Integration
3. Select Jenkins
4. Enter server URL, username, and API token
5. Click Test Connection
6. Save the integration

3. Select Jobs

After connecting, ButterStack fetches your available jobs. Select which jobs can be triggered:

1. Click Configure Jobs
2. Check the jobs you want to allow
3. Set a default job for automatic triggers
4. Save

Webhook Configuration

Jenkins needs to notify ButterStack when builds start and complete.

Never put the webhook token in the URL as a ?token= query string, and never store it as a plain Jenkins job parameter. Jenkins returns job parameters in cleartext to anyone with read access via its own REST API (GET .../api/json?tree=actions[parameters[name,value]]), and a token in a URL also lands in request/proxy/access logs. Store the token as a masked Jenkins “Secret text” credential and deliver it to ButterStack as the X-Webhook-Token header (or in the JSON body as webhook_token) instead.

Option A: Notification Plugin (Not Recommended)

The built-in Jenkins Notification Plugin has no way to attach a custom header or a value from the credential store to its endpoint config - the token would have to go in the URL, which exposes it as described above. Prefer Option B or C.

Option B: Post-Build Script (HTTP Request plugin or curl)

1. Add a masked Jenkins “Secret text” credential (Manage Jenkins > Credentials) named butterstack-webhook-secret holding this integration’s webhook token.
2. Add a post-build shell step that reads it via withCredentials and sends it as a header:

post {
    always {
        withCredentials([string(credentialsId: 'butterstack-webhook-secret', variable: 'BUTTERSTACK_TOKEN')]) {
            sh '''
                curl -X POST \
                  -H "Content-Type: application/json" \
                  -H "X-Webhook-Token: ${BUTTERSTACK_TOKEN}" \
                  -d '{
                    "job_name": "'"${JOB_NAME}"'",
                    "build_number": '"${BUILD_NUMBER}"',
                    "status": "'"${BUILD_STATUS}"'",
                    "build_url": "'"${BUILD_URL}"'"
                  }' \
                  "https://your-butterstack.com/webhooks/jenkins"
            '''
        }
    }
}

Option C: Pipeline Step

In your Jenkinsfile:

pipeline {
    // ...
    environment {
        BUTTERSTACK_TOKEN = credentials('butterstack-webhook-secret')
    }
    post {
        always {
            script {
                def status = currentBuild.result ?: 'SUCCESS'
                httpRequest(
                    url: "https://your-butterstack.com/webhooks/jenkins",
                    httpMode: 'POST',
                    contentType: 'APPLICATION_JSON',
                    customHeaders: [[name: 'X-Webhook-Token', value: env.BUTTERSTACK_TOKEN]],
                    requestBody: """
                        {
                            "job_name": "${env.JOB_NAME}",
                            "build_number": ${env.BUILD_NUMBER},
                            "status": "${status}",
                            "build_url": "${env.BUILD_URL}"
                        }
                    """
                )
            }
        }
    }
}

Features

Build Triggering

Trigger builds programmatically or automatically:

From ButterStack UI:

1. Go to Builds
2. Click Trigger Build
3. Select job and parameters
4. Click Start Build

From Commit Tags: Include in your commit message:

• #ci - Trigger default job
• #build - Trigger default job
• #jenkins - Trigger default job
• #jenkins:JobName - Trigger specific job

Via API:

POST /api/v1/projects/{project_id}/builds/trigger
{
  "job_name": "MyGame-Build",
  "parameters": {
    "platform": "Win64",
    "configuration": "Shipping"
  }
}

Build Status Tracking

ButterStack tracks build lifecycle:

pending → in_progress → completed
                      → failed
                      → aborted

Each build record includes:

• Job name and build number
• Start and end times
• Duration
• Status and result
• Triggering changelist(s)
• Build URL

SCM Correlation

ButterStack links builds to their source changes:

1. Jenkins reports SCM data (changelist numbers, commits)
2. ButterStack matches to existing Changelist/Change records
3. Full lineage: Task → Commit → Build

Artifact Access

View and download build artifacts:

GET /api/v1/builds/{build_id}/artifacts

Console Output

Access build logs:

GET /api/v1/builds/{build_id}/console

Job Templates

ButterStack can create Jenkins jobs from templates:

Unreal Engine Template

Creates a job configured for:

• Perforce checkout
• UAT BuildCookRun
• Platform selection (Win64, Linux, etc.)
• Configuration selection (Development, Shipping)
• Artifact archiving

Unity Template

Creates a job configured for:

• Git/Perforce checkout
• Unity batch mode build
• Platform selection
• Build target selection

Creating a Job from Template

1. Go to Integrations > Jenkins
2. Click Create Job
3. Select template and configure options
4. Click Create
5. Job is created in Jenkins with your settings

Webhook Payload Format

Build Started

{
  "event": "build_started",
  "job_name": "MyGame-Build",
  "build_number": 123,
  "timestamp": "2026-12-15T10:30:00Z"
}

Build Completed

{
  "event": "build_completed",
  "job_name": "MyGame-Build",
  "build_number": 123,
  "status": "SUCCESS",
  "duration": 1234567,
  "build_url": "https://jenkins.company.com/job/MyGame-Build/123",
  "scm": {
    "changelist": 12345,
    "branch": "main"
  }
}

Troubleshooting

Connection Failed

Error: Failed to connect to Jenkins

• Verify server URL includes protocol (https://)
• Check network connectivity
• Verify firewall allows access

Authentication Failed

Error: 401 Unauthorized

• Regenerate API token
• Verify username is correct
• Check token hasn’t expired

CSRF Token Error

Error: No valid crumb was included

ButterStack handles CSRF automatically. If you see this:

• Ensure you’re using the latest ButterStack version
• Check Jenkins CSRF settings

Build Not Triggering

• Verify job name matches exactly (case-sensitive)
• Check job is in selected_jobs list
• Ensure job accepts remote triggers
• Review Jenkins security settings

Build Status Not Updating

• Verify webhook URL is correct
• Check webhook token matches
• Ensure notification plugin is installed
• Review Jenkins logs for webhook errors

API Reference

Trigger Build

POST /webhooks/jenkins/commit_trigger

Build Notification

POST /webhooks/jenkins/build_notification

Headers:

• X-Jenkins-Signature - HMAC signature for verification

List Jobs

GET /api/v1/integrations/{integration_id}/jenkins_jobs

Best Practices

1. Use API tokens - Don’t use passwords
2. Service account - Create dedicated Jenkins user for ButterStack
3. Webhook notifications - More reliable than polling
4. Selective job access - Only allow necessary jobs in selected_jobs
5. Parameter validation - Define allowed parameters to prevent injection
6. Never expose the webhook token as a job parameter or URL query string - store it as a masked Jenkins “Secret text” credential and deliver it via the X-Webhook-Token header. A plain job parameter is readable in cleartext by anyone with Jenkins read access via api/json.