Frequently Asked Questions

Common questions about ButterStack setup, integrations, and troubleshooting.

Getting Started
Integrations
Builds & Assets
Deployment
API & Webhooks
Troubleshooting
Billing & Plans
1. What counts as a “build credit”?
2. Can I see my credit usage?
Security
1. How does ButterStack handle my credentials?
2. Can ButterStack access my source code?
Need More Help?
Related

Getting Started

What is ButterStack?

ButterStack is an asset lineage platform for game development that tracks your assets through a 5-stage pipeline: Task Assignment → Version Control → CI/CD → Game Engine → Deployment. It provides complete visibility into what assets are in which builds and when they reach players.

Which game engines does ButterStack support?

Currently supported:

Unreal Engine 4.27+ and Unreal Engine 5.x (full support)
Unity 2021.3 LTS+ (coming soon)
Custom engines (via generic webhook endpoints)

What’s the difference between the plans?

Free/Trial: Access to all integrations for evaluation
Indie: Core integrations only (Perforce, Jenkins, Jira, Steam, Unreal, Unity, Discord)
Team/Studio/Enterprise: All integrations plus advanced features

Core integrations cover the essential game development workflow.

Do I need to install anything in my game engine?

No! ButterStack uses an “observe, don’t interfere” approach. Integration happens through:

Webhook callbacks from your build scripts
Log parsing (optional)
API calls to external tools

No plugins or engine modifications required.

Integrations

Why can’t I see my Jenkins jobs after connecting?

Check these common issues:

API Token Permissions: Ensure your Jenkins API token has job read/execute permissions
Job Visibility: ButterStack only shows jobs your API user can access
Connection Test: Verify the connection test passed in integration settings
CSRF Protection: ButterStack handles CSRF automatically, but check Jenkins security settings

My Perforce integration shows “Connection Failed”

Troubleshooting steps:

Server URL Format: Use ssl:perforce.company.com:1666 for secure connections
Network Access: Ensure ButterStack can reach your Perforce server
User Permissions: Verify the service account has read access to monitored depot paths
Workspace: If using a workspace, ensure it exists and is accessible

How do I set up automatic build triggering?

Include trigger tags in your commit/changelist description:

#ci - Triggers default Jenkins job
#build - Triggers default Jenkins job
#jenkins:JobName - Triggers specific job

Example: PROJ-123: Updated character textures #ci

Can I use multiple Perforce depots?

Yes! Configure the selected_depots field in your Perforce integration to specify which depots to monitor. You can also use project_path to limit monitoring to specific paths like //depot/MyGame/...

Builds & Assets

What is an Asset Manifest?

An Asset Manifest is a detailed report of all assets processed during a build, including:

Individual asset cook times
File sizes (original vs. cooked)
Compression ratios
Success/failure status
Asset types (texture, mesh, material, etc.)

Why aren’t my builds linking to commits automatically?

Build-to-commit linking depends on:

Jenkins SCM Data: Jenkins must report which commits/changelists triggered the build
Timing: Builds should start shortly after commits are detected
Project Association: Both the integration and build must belong to the same ButterStack project

Check the Jenkins webhook configuration and SCM settings.

How long are build artifacts stored?

Build artifacts are stored for 30 days by default. You can configure retention policies in Project Settings → Build Configuration. Enterprise plans may have extended retention options.

Deployment

Does ButterStack upload builds to Steam?

No, ButterStack is read-only for deployments. You continue using your existing upload process (SteamCMD, steamworks SDK, etc.). ButterStack observes the deployment status via Steam’s Partner Web API.

How often does ButterStack check Steam for updates?

The default polling interval is 5 minutes. You can adjust this in the Steam integration settings, but Steam has API rate limits so don’t set it too low.

Can I track multiple Steam branches?

Yes, but you’ll need separate Steam integrations for each branch you want to monitor. Set the steam_branch field to the specific branch name (e.g., “public”, “beta”, “internal”).

API & Webhooks

What’s the difference between webhook tokens and API keys?

Webhook Tokens (wh_*): Used for inbound webhooks from external tools
API Keys (bsk_live_*): Used for REST API access to query/control ButterStack

They serve different purposes and have different permission scopes.

Are there rate limits on the API?

Yes:

Webhooks: 100 requests/minute
REST API: 60 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

How do I secure webhook endpoints?

All webhook endpoints require authentication:

Token-based: Include ?token=YOUR_WEBHOOK_TOKEN in the URL
HMAC Signatures: Some integrations (like Linear) use HMAC verification
HTTPS Only: All webhook traffic must use HTTPS

Never expose webhook tokens in logs or version control.

Troubleshooting

Builds are triggering but not showing in ButterStack

Check the webhook delivery:

Jenkins Notification Plugin: Verify webhook events are being sent
Webhook Logs: Check Project Settings → Logs for delivery status
Token Validity: Ensure webhook token matches integration settings
JSON Format: Verify webhook payload is valid JSON

Assets aren’t showing cooking details

Detailed asset tracking requires:

Game Engine Webhooks: Send asset_cooked events during builds
Log Parsing Setup: Additional configuration for log-based tracking
Build Integration: Link game engine builds to CI/CD builds

Start with build phase tracking (cooking_started, build_completed) first.

Integration shows “Unhealthy” status

Integration health checks run automatically:

Green (Healthy): Recent successful webhook delivery or API call
Red (Unhealthy): Connection failures, authentication errors, or no recent activity
Yellow (Testing): Initial setup or connection testing in progress

Check integration logs and test the connection to diagnose issues.

Billing & Plans

What counts as a “build credit”?

Build credits are consumed based on:

Build Duration: Longer builds use more credits
Build Complexity: Number of assets processed
Platform Count: Building for multiple platforms

Simple builds might use 1-2 credits, complex multi-platform builds could use 10-20.

Can I see my credit usage?

Yes, check your dashboard for:

Current month usage
Credit consumption by project
Historical usage trends
Remaining credits

Usage is updated in real-time as builds complete.

Security

How does ButterStack handle my credentials?

All credentials are encrypted at rest and in transit:

Database Encryption: AES-256 encryption for stored credentials
TLS: All API and webhook communication uses HTTPS
Token Rotation: Regular rotation recommended for API keys
Minimal Permissions: Service accounts should have only required permissions

Can ButterStack access my source code?

ButterStack only accesses metadata about your commits/changelists:

File paths and change types
Commit messages and author info
Timestamps and build associations

We don’t download or store your actual source code files.

Need More Help?

Email Support: support@butterstack.com
Discord Community: Join our Discord
Documentation: Browse the full documentation at butterstack.com/docs

Glossary - Key terms and definitions
Troubleshooting Guide - Detailed troubleshooting steps
Configuration Reference - Integration settings reference

← Previous Glossary