Git Integration

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

Table of contents

1. Overview
2. Prerequisites
3. Setup Instructions
   1. Step 1: Navigate to Source Control
   2. Step 2: Configure Repository
   3. Step 3: Authentication Setup
      1. Option A: SSH Key (Recommended)
      2. Option B: Personal Access Token
   4. Step 4: Webhook Configuration
4. Advanced Configuration
   1. Branch Protection
   2. Commit Message Parsing
   3. Asset Mapping
5. Troubleshooting
   1. Common Issues
6. Best Practices
7. Next Steps

Overview

ButterStack integrates with Git to track asset changes, monitor commits, and streamline your development workflow. This guide will walk you through setting up Git integration for your projects.

Prerequisites

• Git repository (GitHub, GitLab, or Bitbucket)
• Admin access to your repository
• ButterStack project created

Setup Instructions

Step 1: Navigate to Source Control

1. Open your ButterStack project
2. Go to Settings → Integrations
3. Click Add Integration
4. Select Git from the available options

Step 2: Configure Repository

Enter your repository details:

Repository URL: https://github.com/your-org/your-repo.git
Branch: main
Authentication: SSH Key or Personal Access Token

Step 3: Authentication Setup

Option A: SSH Key (Recommended)

1. Generate an SSH key for ButterStack:

   ssh-keygen -t ed25519 -C "butterstack@your-domain.com"
   

2. Add the public key to your Git provider:
   • GitHub: Settings → SSH and GPG keys
   • GitLab: Settings → SSH Keys
   • Bitbucket: Personal settings → SSH keys
3. Paste the private key in ButterStack

Copy Command

Option B: Personal Access Token

1. Generate a token with repository access:
   • GitHub: Settings → Developer settings → Personal access tokens
   • GitLab: Settings → Access Tokens
   • Bitbucket: Personal settings → App passwords
2. Enter the token in ButterStack

Step 4: Webhook Configuration

Enable real-time updates by setting up webhooks:

1. Copy the webhook URL from ButterStack:

   https://app.butterstack.com/webhooks/git/YOUR_PROJECT_ID
   

2. Add webhook in your Git provider:
   • GitHub: Repository → Settings → Webhooks → Add webhook
   • GitLab: Settings → Webhooks
   • Bitbucket: Repository settings → Webhooks
3. Configure webhook events:
   • ✅ Push events
   • ✅ Pull request events
   • ✅ Tag push events

Advanced Configuration

Branch Protection

Configure which branches trigger asset tracking:

Protected Branches:
  - main
  - develop
  - release/*
  
Ignored Paths:
  - docs/
  - tests/
  - *.md

Commit Message Parsing

Enable smart parsing to extract metadata from commits:

Pattern: \[(TASK-\d+)\] (.*)
Extract:
  - Task ID
  - Description

Asset Mapping

Map file patterns to asset types:

Textures: "**/*.{png,jpg,tga,dds}"
Models: "**/*.{fbx,obj,gltf}"
Audio: "**/*.{wav,mp3,ogg}"

Troubleshooting

Common Issues

Best Practices

Next Steps

• Configure CI/CD with Jenkins
• Set up task tracking
• Enable Slack notifications