GitHub Integration

Connect ButterStack with GitHub for repository access, pull request tracking, and GitHub Actions workflow monitoring.

Table of contents

1. Overview
2. Prerequisites
3. Configuration
   1. Step 1: Create a Personal Access Token
      1. Fine-grained Token Permissions (Recommended)
      2. Classic Token Scopes
   2. Step 2: Add the Integration
   3. Step 3: Configure Connection Settings
   4. Step 4: Test Connection
4. Webhook Setup
   1. Creating the Webhook
   2. Recommended Events
   3. Webhook Secret (Optional)
5. GitHub Actions Monitoring
   1. Linking Workflows to Builds
6. Features
   1. Commit Synchronization
   2. Task Linking
   3. Pull Request Tracking
   4. Build Triggering
7. API Reference
   1. Webhook Endpoint
   2. Integration Status
8. Troubleshooting
   1. Connection Failed
   2. Repository Not Found
   3. Webhooks Not Received
   4. Rate Limiting
   5. Actions Monitoring Not Working
9. Best Practices
10. Related Guides

Overview

The GitHub integration enables your team to track code changes, monitor CI/CD pipelines, and receive real-time notifications about repository activity directly in ButterStack.

Key features include:

• Repository commit synchronization
• Pull request tracking and status updates
• GitHub Actions workflow monitoring
• Automatic task linking from commit messages
• Webhook-based real-time notifications
• Branch protection status monitoring

Prerequisites

Before configuring the GitHub integration, ensure you have:

• GitHub account with repository access
• Personal Access Token (Fine-grained or Classic)
• ButterStack project created

Configuration

Step 1: Create a Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Choose Fine-grained tokens (recommended) or Tokens (classic)

Fine-grained Token Permissions (Recommended)

Classic Token Scopes

If using classic tokens, select these scopes:

• repo - Full repository access
• workflow - GitHub Actions access
• read:org - Organization membership (if applicable)

Step 2: Add the Integration

1. Go to Project Settings > Integrations
2. Click Add Integration
3. Select GitHub
4. Enter your configuration details

Step 3: Configure Connection Settings

Step 4: Test Connection

Click Test Connection to verify your credentials and repository access.

Webhook Setup

To receive real-time updates, configure webhooks in your GitHub repository:

Creating the Webhook

1. Go to your repository > Settings > Webhooks
2. Click Add webhook
3. Configure the webhook:

Recommended Events

Select these events for full integration:

• Push - Commit notifications
• Pull requests - PR opened, closed, merged
• Workflow runs - GitHub Actions status
• Check runs - CI status checks
• Deployment status - Deployment notifications

Webhook Secret (Optional)

For additional security:

1. Generate a secret: openssl rand -hex 32
2. Add to GitHub webhook configuration
3. Add to ButterStack integration settings

GitHub Actions Monitoring

When “Enable GitHub Actions monitoring” is enabled, ButterStack tracks:

Linking Workflows to Builds

ButterStack can associate GitHub Actions runs with your build pipeline:

1. Add the repository name to your ButterStack build configuration
2. GitHub Actions runs will automatically link to corresponding builds
3. View combined status in the ButterStack dashboard

Features

Commit Synchronization

When commits are pushed:

1. ButterStack receives the webhook notification
2. Fetches commit details via GitHub API
3. Creates commit records with:
   • Commit SHA and message
   • Author information
   • Changed files
   • Timestamp
4. Links to tasks if task keys are found in the message
5. Optionally triggers downstream builds

Task Linking

Include task keys in your commit messages:

PROJ-123: Updated character animations

- Improved walk cycle
- Fixed blending issues

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

Pull Request Tracking

Monitor pull request lifecycle:

• Opened - New PR created
• Updated - New commits pushed
• Reviewed - Review submitted
• Merged - PR merged to target branch
• Closed - PR closed without merge

Build Triggering

Include trigger tags in your commit message:

• #ci - Trigger default build job
• #build - Trigger default build job
• #deploy - Trigger deployment workflow

Example:

PROJ-456: Added new weapon models #ci

- Added assault rifle mesh
- Updated weapon materials

API Reference

Webhook Endpoint

POST /webhooks/github?token={webhook_token}

Headers:

• X-GitHub-Event - Event type (push, pull_request, etc.)
• X-Hub-Signature-256 - HMAC signature (if secret configured)

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.

Troubleshooting

Connection Failed

Error: Bad credentials or 401 Unauthorized

• Verify your Personal Access Token is valid
• Check the token hasn’t expired
• Ensure token has required permissions/scopes
• Verify repository owner and name are correct

Repository Not Found

Error: 404 Not Found

• Check repository owner/name spelling (case-sensitive)
• Ensure your token has access to the repository
• For private repos, verify token has repo scope

Webhooks Not Received

If webhooks aren’t being processed:

1. Check GitHub webhook delivery logs:
   • Repository > Settings > Webhooks > Recent Deliveries
2. Verify webhook URL is correct
3. Ensure webhook token matches integration settings
4. Check for SSL certificate issues

Rate Limiting

Error: 403 rate limit exceeded

• GitHub API has rate limits (5,000 requests/hour with token)
• Consider reducing polling frequency
• Use webhooks instead of polling when possible

Actions Monitoring Not Working

• Verify token has workflow scope (classic) or Actions read permission (fine-grained)
• Check repository has GitHub Actions enabled
• Ensure workflows exist in .github/workflows/

Best Practices

1. Use Fine-grained Tokens - More secure with minimal required permissions
2. Enable Webhooks - Real-time updates are more reliable than polling
3. Configure Webhook Secret - Adds security verification layer
4. Use Service Account - Don’t use personal credentials for team integrations
5. Monitor Rate Limits - Stay within GitHub API limits
6. Regular Token Rotation - Rotate tokens periodically for security

Related Guides

• Getting Started
• Webhook Configuration
• Jenkins Integration
• Task Linking