Link Search Menu Expand
ButterStack Documentation
⌘K

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 (Recommended)
    2. Option B: Post-Build Script
    3. Option B: 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

FieldDescriptionRequiredExample
server_urlJenkins server URLYeshttps://jenkins.company.com
job_nameDefault job to triggerNoMyGame-Build
selected_jobsJobs available for triggeringNoBuild-Win64,Build-Linux
build_parametersDefault parameters for buildsNo{"platform": "Win64"}

Credentials

FieldDescriptionRequired
usernameJenkins usernameYes
api_tokenJenkins API tokenYes

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.

  1. Install the Notification Plugin in Jenkins
  2. In your job configuration, add a Notification Endpoint:
    • URL: https://your-butterstack.com/webhooks/jenkins?token={webhook_token}
    • Format: JSON
    • Events: Job Started, Job Completed, Job Finalized

Option B: Post-Build Script

Add a post-build shell step:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "job_name": "'${JOB_NAME}'",
    "build_number": '${BUILD_NUMBER}',
    "status": "'${BUILD_STATUS}'",
    "build_url": "'${BUILD_URL}'"
  }' \
  "https://your-butterstack.com/webhooks/jenkins?token=${BUTTERSTACK_TOKEN}"

Option B: Pipeline Step

In your Jenkinsfile:

post {
    always {
        script {
            def status = currentBuild.result ?: 'SUCCESS'
            httpRequest(
                url: "https://your-butterstack.com/webhooks/jenkins?token=${BUTTERSTACK_TOKEN}",
                httpMode: 'POST',
                contentType: 'APPLICATION_JSON',
                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

Back to top

Copyright © 2026 ButterStack. All rights reserved.