First Integration

Connect your first development tool to ButterStack

Table of contents

1. Choose Your First Integration
   1. Popular First Integrations
2. Integration Setup Process
   1. Step 1: Access Integration Settings
   2. Step 2: Authentication
      1. API Token Method
      2. OAuth Method
      3. Username/Password
   3. Step 3: Configuration
   4. Step 4: Test Connection
3. Quick Setup Guides
   1. Jenkins (Most Popular)
   2. Git Repository
   3. Slack Notifications
4. Common Integration Patterns
   1. Pattern 1: Source Control + CI/CD
   2. Pattern 2: All-in-One Git Workflow
   3. Pattern 3: Enterprise Setup
5. Verification Checklist
6. Troubleshooting Common Issues
   1. Authentication Failures
   2. Connection Timeouts
   3. Permission Denied
   4. Webhook Issues
7. Next Steps

Choose Your First Integration

Start with the tool you use most frequently. We recommend beginning with your source control or CI/CD system.

Popular First Integrations

Jenkins

Most common for teams with existing CI/CD

Setup Jenkins

Git

Great starting point for Git-based workflows

Setup Git

Perforce

Enterprise teams using Perforce

Setup Perforce

Integration Setup Process

Step 1: Access Integration Settings

1. Navigate to your Project Dashboard
2. Click Integrations in the sidebar
3. Click Add Integration
4. Select your desired tool

Step 2: Authentication

Most integrations require authentication:

API Token Method

• Generate an API token in your tool’s settings
• Copy the token to ButterStack
• Test the connection

OAuth Method

• Click Connect with [Tool Name]
• Authorize ButterStack in the popup window
• Connection will be established automatically

Username/Password

• Enter your credentials securely
• Credentials are encrypted and stored safely

Step 3: Configuration

Configure integration-specific settings:

• Repository/Project Selection - Choose which repos to monitor
• Branch Settings - Specify branches to track
• Trigger Conditions - Define when builds should start
• Notification Preferences - Set up alerts

Step 4: Test Connection

Always test your integration:

1. Click Test Connection button
2. Verify successful connection status
3. Check that ButterStack can access your data
4. Resolve any permission issues

Quick Setup Guides

Jenkins (Most Popular)

Prerequisites:

• Jenkins server access
• Admin or build permissions
• Jenkins API token

Setup Steps:

1. Generate Jenkins API token
2. Add ButterStack webhook to Jenkins
3. Configure build triggers
4. Test with sample build

Estimated Time: 10-15 minutes

Full Jenkins Guide →

Git Repository

Prerequisites:

• Git repository access
• Read permissions minimum
• Personal access token

Setup Steps:

1. Generate personal access token
2. Add repository URL to ButterStack
3. Configure branch monitoring
4. Set up commit triggers

Estimated Time: 5-10 minutes

Full Git Guide →

Slack Notifications

Prerequisites:

• Slack workspace admin access
• Channel where notifications should go

Setup Steps:

1. Install ButterStack Slack app
2. Authorize workspace access
3. Select notification channels
4. Configure message preferences

Estimated Time: 5 minutes

Full Slack Guide →

Common Integration Patterns

Pattern 1: Source Control + CI/CD

Best for: Teams with established build infrastructure

1. Git/Perforce - Monitor code changes
2. Jenkins/GitHub Actions - Trigger builds automatically
3. Slack/Discord - Notify team of results

Pattern 2: All-in-One Git Workflow

Best for: Smaller teams using GitHub/GitLab

1. GitHub - Source control and CI/CD
2. Linear/Jira - Issue tracking
3. Discord - Team communication

Pattern 3: Enterprise Setup

Best for: Large studios with complex workflows

1. Perforce - Source control for large assets
2. Jenkins - Build orchestration
3. Jira - Project management
4. Slack - Team notifications

Verification Checklist

After setting up your first integration:

• Connection Status - Shows “Connected” with green indicator
• Data Access - ButterStack can read from your tool
• Permissions - Required permissions are granted
• Test Trigger - Manual trigger works correctly
• Notifications - Alerts are received as expected

Troubleshooting Common Issues

Authentication Failures

Problem: “Invalid credentials” or “Unauthorized” errors

Solutions:

• Verify API token is correct and hasn’t expired
• Check that user has required permissions
• Ensure token has necessary scopes enabled

Connection Timeouts

Problem: “Connection timeout” or “Unable to reach server”

Solutions:

• Verify server URL is correct and accessible
• Check firewall settings allow ButterStack access
• Confirm service is running and responsive

Permission Denied

Problem: “Access denied” or “Insufficient permissions”

Solutions:

• Grant ButterStack user appropriate permissions
• Add ButterStack to required groups/teams
• Check repository/project access settings

Webhook Issues

Problem: Triggers not firing or delayed notifications

Solutions:

• Verify webhook URL is correctly configured
• Check webhook delivery logs in your tool
• Confirm payload format matches expectations

Next Steps

With your first integration working:

1. Configure Build Settings - Set up automated builds
2. Add More Integrations - Connect additional tools
3. Set Up Notifications - Configure Discord or Slack alerts

Need Help? Our integration specialists are available to help. Contact support@butterstack.com or join our Discord community.