Connecting Perforce to Jenkins

This guide shows you how to set up automatic build triggering when code is committed to Perforce, creating a seamless integration between your version control and CI/CD pipeline.

Overview

When properly configured, this integration will:

Automatically trigger Jenkins builds when code is committed to Perforce
Pass changelist information to Jenkins for build tracking
Work with ButterStack’s existing Perforce integration for complete visibility
Support multiple Jenkins jobs and depot paths

Prerequisites

Perforce server with admin access
Jenkins server with P4 plugin installed
Network connectivity between Perforce and Jenkins
(Optional) ButterStack with Perforce integration set up

Step 1: Configure Jenkins with Perforce Plugin

Install the P4 Plugin

In Jenkins, go to Manage Jenkins → Manage Plugins
Search for “P4 Plugin” and install it
Restart Jenkins if required

Set Up Perforce Connection

Go to Manage Jenkins → Configure System
Find the Perforce section
Click Add Perforce Server
Configure your server:
- Server: your-perforce-server:1666
- Username: Your Perforce username
- Password: Your Perforce password or ticket
- Workspace: Create or select a workspace

Test the Connection

Click Test Connection to verify Jenkins can connect to Perforce
Save the configuration

Step 2: Create a Jenkins Job

Create a New Job

Click New Item in Jenkins
Enter a name (e.g., “ButterStack-Build”)
Select Freestyle project
Click OK

Configure Source Code Management

In the job configuration, go to Source Code Management
Select Perforce
Choose your Perforce server from the dropdown
Configure the workspace:
- Workspace: Use the same workspace configured in Step 1
- View: Set your depot path (e.g., //depot/... //workspace/...)

Configure Build Triggers

Go to Build Triggers
Check “Trigger builds remotely”
Set an Authentication Token (optional but recommended)
Note: The P4 plugin will automatically handle changelist-based triggers

Add Build Steps

Add your build steps (compile, test, package, etc.) based on your project needs.

Step 3: Set Up Perforce Triggers

Option A: Using ButterStack Docker Environment

If you’re using ButterStack’s Docker development environment, the trigger is already configured. The Jenkins trigger script is located at:

/Users/ryan/dev/butter_stack/docker/perforce/jenkins-trigger.sh

Option B: Manual Perforce Trigger Setup

1. Create the Trigger Script

Create a script on your Perforce server (e.g., /p4/common/bin/triggers/jenkins.sh):

#!/bin/bash

# Jenkins trigger script for Perforce
CHANGELIST=$1
JENKINS_URL="${JENKINS_URL:-http://your-jenkins-server:8080}"

# Trigger Jenkins build
curl -s -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "change=${CHANGELIST}" \
  "${JENKINS_URL}/p4/change"

echo "Triggered Jenkins build for changelist ${CHANGELIST}"
exit 0

2. Make the Script Executable

chmod +x /p4/common/bin/triggers/jenkins.sh

3. Configure the Trigger

Edit Perforce triggers:
```
p4 triggers
```

Add the Jenkins trigger:

Triggers:
    jenkins-build change-commit //depot/... "/p4/common/bin/triggers/jenkins.sh %changelist%"

Save and exit

Step 4: Environment Configuration

Set Environment Variables

On your Perforce server, set these environment variables:

# Required: Jenkins server URL
export JENKINS_URL="http://your-jenkins-server:8080"

# Optional: Specific job name (defaults to auto-detection)
export JENKINS_JOB="ButterStack-Build"

Network Configuration

Ensure your Perforce server can reach Jenkins:

# Test connectivity
curl -I http://your-jenkins-server:8080/p4/change

Step 5: Test the Integration

Manual Test

Make a change to your Perforce depot
Submit the changelist
Check Jenkins for a new build trigger
Verify the build includes the correct changelist number

Verify Logs

Check Perforce logs for trigger execution:

tail -f $P4ROOT/logs/log

Check Jenkins logs for incoming triggers:

tail -f $JENKINS_HOME/logs/jenkins.log

Advanced Configuration

Multiple Depot Paths

Configure different triggers for different depot paths:

Triggers:
    jenkins-main change-commit //depot/main/... "/p4/common/bin/triggers/jenkins-main.sh %changelist%"
    jenkins-dev change-commit //depot/dev/... "/p4/common/bin/triggers/jenkins-dev.sh %changelist%"

Conditional Builds

Modify the trigger script to check commit messages or file paths:

# Only trigger for specific file types
if p4 describe -s $CHANGELIST | grep -q "\.cpp\|\.h\|\.cs"; then
    # Trigger build
    curl -s -X POST -d "change=${CHANGELIST}" "${JENKINS_URL}/p4/change"
fi

Authentication

If Jenkins requires authentication, modify the trigger script:

# With authentication token
curl -s -X POST \
  -H "Authorization: Bearer ${JENKINS_TOKEN}" \
  -d "change=${CHANGELIST}" \
  "${JENKINS_URL}/p4/change"

Integration with ButterStack

When using ButterStack alongside this integration:

ButterStack webhook tracks changes and creates Change records
Jenkins trigger starts builds automatically
Jenkins webhook (configured in ButterStack) reports build status back
Complete visibility of changes → builds → results in ButterStack

This creates a complete CI/CD pipeline with full tracking and visibility.

Troubleshooting

Common Issues

Jenkins builds not triggering:

Check Perforce trigger logs: p4 triggers -o
Verify network connectivity: curl -I $JENKINS_URL/p4/change
Check Jenkins P4 plugin configuration

Wrong changelist in builds:

Verify the %changelist% parameter is passed correctly
Check Jenkins job workspace configuration

Permission errors:

Ensure the trigger script has execute permissions
Verify Perforce service user has necessary permissions

Debug Mode

Enable debug logging in the trigger script:

# Add to beginning of trigger script
set -x  # Enable debug mode
exec 2>>/tmp/jenkins-trigger.log  # Log to file

Security Considerations

Use service accounts with minimal required permissions
Consider using authentication tokens for Jenkins API calls
Restrict trigger execution to specific depot paths
Monitor trigger logs for unusual activity

Performance Tips

Use lightweight trigger scripts to avoid blocking submits
Consider asynchronous build triggering for large changesets
Monitor Jenkins queue capacity
Use workspace caching to speed up builds

This integration provides a robust, automated CI/CD pipeline that scales with your development workflow while maintaining complete visibility through ButterStack.

← Previous Steam Next → Trello