GitLab Integration

Connect your GitLab repositories for commit tracking and build triggering.

Table of contents

1. Overview
2. Configuration
   1. Connection Settings
   2. Credentials
3. Setup Steps
   1. 1. Generate Access Token
   2. 2. Add the Integration
   3. 3. Configure Webhook (Optional)
4. Features
   1. Commit Tracking
   2. Task Linking
   3. Build Triggering
   4. Merge Request Integration
5. Self-Hosted GitLab
6. API Endpoints Used
7. Webhook Payload
   1. Push Event
   2. Merge Request Event
8. Troubleshooting
   1. Connection Failed
   2. Access Token Invalid
   3. Webhook Not Delivering
   4. Missing Commits
9. Security Best Practices
10. Best Practices
11. Related

Overview

ButterStack integrates with GitLab to provide Stage 2 visibility in the asset pipeline:

• Commit and merge request tracking
• Automatic task linking from commit messages
• Build triggering via commit tags
• Author identification and change history
• Branch and merge monitoring

This integration works with GitLab.com (SaaS) and self-hosted GitLab instances.

Configuration

Connection Settings

Credentials

Setup Steps

1. Generate Access Token

1. Log into your GitLab account
2. Go to User Settings → Access Tokens
3. Create a new token with these scopes:
   • api - Full API access
   • read_repository - Read repository content
   • read_api - Read API access
4. Copy the token (you won’t see it again)

2. Add the Integration

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

3. Configure Webhook (Optional)

For real-time updates, add a webhook in GitLab:

1. In your GitLab project, go to Settings → Webhooks
2. Add webhook URL: https://app.butterstack.com/webhooks/github?token={webhook_token}
3. Select events:
   • ✅ Push events
   • ✅ Merge request events
   • ✅ Tag push events
4. Click Add webhook

Features

Commit Tracking

ButterStack monitors commits and captures:

• Commit SHA and message
• Author information
• Changed files and paths
• Timestamp
• Branch information

Task Linking

Include task references in commit messages to automatically link to project management tools:

PROJ-123: Add new weapon models

- Created assault rifle mesh
- Updated material instances
- Fixed UV mapping issues

ButterStack will link this commit to task PROJ-123 in Jira, Linear, or Trello.

Build Triggering

Include trigger tags in commit messages to automatically start builds:

• #ci - Trigger default Jenkins job
• #build - Trigger default Jenkins job
• #jenkins - Trigger default Jenkins job
• #jenkins:JobName - Trigger specific job

Example:

PROJ-456: Updated character textures #ci

Improved resolution and fixed normal maps

Merge Request Integration

Track merge requests and their associated commits:

• MR status and approval state
• Target branch information
• Linked commits and file changes
• Author and reviewer information

Self-Hosted GitLab

For self-hosted GitLab instances:

1. Set the gitlab_url field to your instance URL
2. Ensure ButterStack can reach your GitLab server
3. Configure webhook URL to point to ButterStack
4. Verify SSL certificates are valid

API Endpoints Used

ButterStack uses these GitLab API endpoints:

Webhook Payload

When configured, GitLab sends webhook events to ButterStack:

Push Event

{
  "object_kind": "push",
  "ref": "refs/heads/main",
  "commits": [
    {
      "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
      "message": "PROJ-123: Add new textures #ci",
      "author": {
        "name": "Jane Developer",
        "email": "jane@company.com"
      },
      "added": ["Assets/Textures/hero_diffuse.png"],
      "modified": ["Assets/Materials/HeroMaterial.mat"],
      "removed": []
    }
  ]
}

Merge Request Event

{
  "object_kind": "merge_request",
  "object_attributes": {
    "id": 456,
    "title": "Add new weapon system",
    "state": "merged",
    "target_branch": "main",
    "source_branch": "feature/weapons"
  }
}

Troubleshooting

Connection Failed

Error: Failed to connect to GitLab

• Verify repository URL is accessible
• Check access token permissions and expiration
• For self-hosted: ensure ButterStack can reach your GitLab instance
• Test manually: curl -H "PRIVATE-TOKEN: your_token" "https://gitlab.com/api/v4/user"

Access Token Invalid

Error: 401 Unauthorized

• Regenerate access token with correct scopes
• Verify token hasn’t expired
• Check token belongs to user with repository access

Webhook Not Delivering

• Check webhook delivery logs in GitLab project settings
• Verify webhook URL and token are correct
• Ensure webhook events are properly configured
• Review ButterStack webhook logs in project settings

Missing Commits

• Check if commits are on monitored branch
• Verify webhook is sending push events
• For older commits, ButterStack syncs recent history on initial setup

Security Best Practices

1. Minimal Token Permissions: Only grant required scopes
2. Token Rotation: Regularly regenerate access tokens
3. Webhook Security: Use HTTPS and verify webhook signatures
4. Repository Access: Limit service account to necessary repositories
5. Network Security: Whitelist ButterStack IPs if using self-hosted GitLab

Best Practices

1. Consistent Commit Messages: Use clear, descriptive commit messages
2. Task References: Always include task IDs for traceability
3. Trigger Tags: Use build triggers consistently across your team
4. Branch Strategy: Define clear branching strategy for your project
5. Merge Request Reviews: Maintain code quality through MR workflows

Related

• GitHub Integration - Similar Git-based integration
• Jenkins Integration - CI/CD build triggering
• Jira Integration - Task management linking
• Core Concepts: 5-Stage Pipeline - Understanding asset lineage