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: No trigger 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 → 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://www.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: No trigger access?

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 changelist description. Matching is case-insensitive and anywhere in the description:

Add :JobName to target a specific Jenkins job for one changelist - #ci:JobName, #jenkins:JobName, [build:JobName]. If the integration has a selected jobs list, the requested job must be in it, otherwise the configured default job is used.

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

Connection health and last-checked time are shown on the integration’s page in ButterStack (the Connection Status panel, refreshed by Test Connection). There is no public JSON endpoint for integration health.

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