Diversion Integration

Cloud-native version control designed for game development assets.

Coming Soon — Diversion integration is currently in development. Contact us to be notified when it’s available.

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. Configure Monitoring
4. Features
   1. Asset Sync
   2. Conflict Detection
   3. File Monitoring
   4. Path Filtering
5. Webhook Configuration
   1. Webhook Payload
6. Integration with Pipeline
   1. Task Linking
   2. Build Triggering
7. API Reference
   1. Webhook Endpoint
   2. List Changes
8. Troubleshooting
   1. Connection Failed
   2. Webhooks Not Received
   3. Files Not Tracking
9. Comparison with Perforce
10. Best Practices

Overview

Diversion is a modern version control system built specifically for game development. ButterStack integrates with Diversion to provide:

• Asset commit tracking
• Conflict detection and notifications
• File change monitoring
• Branch and workspace awareness
• Integration with the asset lineage pipeline

Configuration

Connection Settings

Credentials

Setup Steps

1. Generate API Token

1. Log into your Diversion account
2. Go to Settings > API Tokens
3. Click Generate Token
4. Copy the token

2. Add the Integration

1. Go to Project Settings > Integrations
2. Click Add Integration
3. Select Diversion
4. Enter your API token and repository URL
5. Click Test Connection
6. Save the integration

3. Configure Monitoring

Optionally filter what ButterStack tracks:

• watch_paths: Only track changes in these directories
• file_types: Only track these file extensions
• branch: Specific branch to monitor

Features

Asset Sync

When commits are made in Diversion:

1. Webhook notification sent to ButterStack
2. Commit details fetched via API
3. Change record created
4. Assets linked to the commit
5. Task references extracted from commit message

Conflict Detection

Diversion excels at handling large binary files. ButterStack can notify your team when:

• A file is locked by another user
• A merge conflict is detected
• Multiple users are editing the same asset

File Monitoring

Track specific file types relevant to your project:

file_types:
  - .uasset
  - .umap
  - .fbx
  - .png
  - .wav

Path Filtering

Focus on specific directories:

watch_paths:
  - Content/Characters/
  - Content/Environments/
  - Content/UI/

Webhook Configuration

Configure Diversion to send webhooks to ButterStack:

1. In Diversion, go to Repository Settings > Webhooks
2. Add a new webhook:
   • URL: https://your-butterstack.com/webhooks/diversion?token={webhook_token}
   • Events: Push, Merge, Lock
3. Save the webhook

Webhook Payload

{
  "event": "push",
  "repository": "org/repo",
  "branch": "main",
  "commit": {
    "id": "abc123",
    "message": "PROJ-456: Updated hero textures",
    "author": "jane.smith",
    "timestamp": "2026-12-15T10:30:00Z",
    "files": [
      {
        "path": "Content/Characters/Hero/T_Hero_Diffuse.uasset",
        "action": "modified"
      }
    ]
  }
}

Integration with Pipeline

Diversion serves as Stage 2 (Version Control) in the asset lineage:

Task (Jira) → Diversion → Jenkins → Unreal → Steam
              ^^^^^^^^
              Stage 2

Task Linking

Include task keys in commit messages:

PROJ-123: Added new character models

- Hero base mesh
- Hero texture set
- Updated materials

ButterStack automatically links to PROJ-123.

Build Triggering

Include tags to trigger builds:

PROJ-456: Environment art update #ci

API Reference

Webhook Endpoint

POST /webhooks/diversion?token={webhook_token}

List Changes

GET /api/v1/projects/{project_id}/changes?source=diversion

Troubleshooting

Connection Failed

• Verify API token is valid
• Check repository URL format
• Ensure account has repository access

Webhooks Not Received

• Verify webhook URL in Diversion settings
• Check webhook token matches
• Review Diversion webhook logs

Files Not Tracking

• Check watch_paths includes your directories
• Verify file_types includes your extensions
• Ensure branch name matches

Comparison with Perforce

Choose based on your team’s needs and existing infrastructure.

Best Practices

1. Use meaningful commit messages - Include task keys
2. Configure path filters - Reduce noise from irrelevant changes
3. Enable notifications - Alert team to conflicts early
4. Regular syncs - Keep ButterStack data current