Perforce Integration

Enterprise-grade version control integration with full changelist synchronization.

Table of contents

1. Overview
2. Configuration
   1. Connection Settings
   2. Credentials
3. Setup Steps
   1. 1. Create a Service Account
   2. 2. Add the Integration
   3. 3. Configure Depot Paths
4. Webhook Configuration
   1. Option A: Change-Commit Trigger (Recommended)
   2. Option B: Polling (No Server Access)
5. Features
   1. Changelist Sync
   2. Task Linking
   3. Build Triggering
   4. Depot Browser
6. SSL/TLS Configuration
   1. Certificate Fingerprint
7. Troubleshooting
   1. Connection Failed
   2. Authentication Failed
   3. SSL Error
   4. Changelist Not Syncing
8. API Reference
   1. Webhook Endpoint
   2. Integration Status
9. Best Practices

Overview

ButterStack provides deep integration with Perforce Helix Core, including:

• Full changelist synchronization via P4Ruby
• Depot browser with path filtering
• Trigger-based webhook notifications
• Automatic task linking from commit messages
• Jenkins build triggering
• User identity mapping

Configuration

Connection Settings

Credentials

Setup Steps

1. Create a Service Account

Create a dedicated Perforce user for ButterStack:

p4 user -f butterstack-service

Grant necessary permissions:

p4 protect
# Add: read user butterstack-service * //...

2. Add the Integration

1. Go to Project Settings > Integrations
2. Click Add Integration
3. Select Perforce
4. Enter your server URL and credentials
5. Click Test Connection
6. Save the integration

3. Configure Depot Paths

Optionally restrict which depot paths are monitored:

• project_path: Only sync changelists affecting this path
• hidden_depot_paths: Hide these paths in the depot browser (e.g., spec, unload)
• selected_depots: Only show these depots in the browser

Webhook Configuration

ButterStack needs to receive notifications when changelists are submitted. You have two options:

Option A: Change-Commit Trigger (Recommended)

Add a trigger to your Perforce server:

p4 triggers

Add this line:

Triggers:
    butterstack change-commit //depot/... "/path/to/butterstack-webhook.sh %changelist%"

Create the webhook script:

#!/bin/bash
CHANGELIST=$1
WEBHOOK_URL="https://your-butterstack.com/webhooks/perforce"
WEBHOOK_TOKEN="your-webhook-token"

curl -s -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "changelist=${CHANGELIST}&token=${WEBHOOK_TOKEN}" \
  "${WEBHOOK_URL}"

Option B: Polling (No Server Access)

If you can’t add triggers, ButterStack can poll for changes:

1. Enable Polling Mode in integration settings
2. Set the poll interval (minimum 60 seconds)
3. ButterStack will check for new changelists periodically

Note: Polling has higher latency than triggers.

Features

Changelist Sync

When a changelist is submitted:

1. ButterStack receives the webhook notification
2. Fetches full changelist details via P4Ruby
3. Creates a Changelist record with:
   • Change number
   • Description
   • Author
   • File list with change types (add, edit, delete)
   • Timestamp
4. Links to tasks if task keys are found in description
5. Optionally triggers Jenkins builds

Task Linking

Include task keys in your commit message:

PROJ-123: Updated character textures

- Improved resolution on hero mesh
- Fixed UV mapping issues

ButterStack automatically links the changelist to task PROJ-123 in Jira/Linear/Trello.

Build Triggering

Include trigger tags in your commit message:

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

Example:

PROJ-456: Added new weapon models #ci

- Added assault rifle mesh
- Updated weapon materials

Depot Browser

The depot browser lets you explore your Perforce structure:

• Navigate depot folders
• View file history
• See which changelists modified each file
• Filter out administrative paths (spec, unload)

SSL/TLS Configuration

For secure connections, use the ssl: prefix:

ssl:perforce.company.com:1666

ButterStack automatically handles SSL certificate trust on first connection.

Certificate Fingerprint

If you need to manually trust a certificate:

1. Get the fingerprint: p4 -p ssl:server:1666 trust -l
2. Add to server settings in ButterStack

Troubleshooting

Connection Failed

Error: Connect to server failed

• Verify the server URL is correct
• Check network connectivity from ButterStack to Perforce
• Ensure firewall allows port 1666 (or your custom port)

Authentication Failed

Error: P4PASSWD invalid

• Verify username and password
• Check if the account requires a ticket: p4 login -s
• Ensure the service account has required permissions

SSL Error

Error: SSL receive failed

• Use ssl: prefix in server URL
• Check certificate validity
• ButterStack may need to trust the server on first connect

Changelist Not Syncing

• Verify webhook trigger is installed: p4 triggers -o
• Check webhook token matches integration settings
• Review webhook logs in ButterStack

API Reference

Webhook Endpoint

POST /webhooks/perforce?token={webhook_token}

Parameters:

• changelist (required): Changelist number
• timestamp (optional): Submission timestamp

Integration Status

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

Returns connection health and last sync time.

Best Practices

1. Use a service account - Don’t use personal credentials
2. Restrict depot paths - Only monitor relevant paths to reduce noise
3. Enable triggers - Triggers are more reliable than polling
4. Hide administrative paths - Use hidden_depot_paths for cleaner browsing
5. Regular health checks - Monitor the integration health status