Bitbucket Integration

Connect your Bitbucket repositories for commit tracking and automated build triggers.

Table of contents

1. Overview
2. Configuration
   1. Connection Settings
   2. Credentials
3. Setup Steps
   1. 1. Generate App Password
      1. For Bitbucket Cloud
      2. For Bitbucket Server
   2. 2. Add the Integration
   3. 3. Configure Webhook (Optional)
      1. Bitbucket Cloud
      2. Bitbucket Server
4. Features
   1. Commit Monitoring
   2. Task Integration
   3. Automated Build Triggering
   4. Pull Request Tracking
5. Bitbucket Server Configuration
   1. Additional Settings
   2. Network Requirements
6. API Usage
   1. Bitbucket Cloud
   2. Bitbucket Server
7. Webhook Events
   1. Repository Push (Bitbucket Cloud)
   2. Pull Request Event
8. Troubleshooting
   1. Authentication Failed
   2. Repository Not Found
   3. Webhook Delivery Issues
   4. Bitbucket Server SSL Issues
9. Security Considerations
   1. App Password Security
   2. Webhook Security
10. Best Practices
11. Migration from Other Git Providers
    1. From GitHub
    2. From GitLab
12. Related

Overview

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

• Commit and pull request monitoring
• Automatic build triggering via commit tags
• Task linking from commit messages
• Branch and merge tracking
• Team member identification

This integration supports both Bitbucket Cloud (bitbucket.org) and Bitbucket Server (on-premises).

Configuration

Connection Settings

Credentials

Setup Steps

1. Generate App Password

For Bitbucket Cloud

1. Go to Personal Settings → App passwords
2. Click Create app password
3. Give it a descriptive name: “ButterStack Integration”
4. Select permissions:
   • Repositories: Read
   • Pull requests: Read
   • Webhooks: Read and write (for webhook setup)
5. Copy the generated password

For Bitbucket Server

1. Go to Personal Settings → HTTP access tokens
2. Create new token with:
   • Name: ButterStack Integration
   • Permissions: REPO_READ, PROJECT_READ
3. Copy the token

2. Add the Integration

1. Go to Project Settings > Integrations
2. Click Add Integration
3. Select Bitbucket
4. Enter repository URL, username, and app password
5. Click Test Connection
6. Save the integration

3. Configure Webhook (Optional)

For real-time updates:

Bitbucket Cloud

1. In your repository, go to Settings → Webhooks
2. Add webhook:
   • URL: https://app.butterstack.com/webhooks/github?token={webhook_token}
   • Events:
     • ✅ Repository push
     • ✅ Pull request created
     • ✅ Pull request updated
     • ✅ Pull request merged

Bitbucket Server

1. Go to Repository settings → Hooks
2. Enable Post-Receive WebHooks
3. Add webhook URL with ButterStack token

Features

Commit Monitoring

ButterStack tracks all commits and captures:

• Commit hash and message
• Author details
• Modified files and paths
• Branch information
• Parent commit relationships

Task Integration

Link commits to project management tasks by including task references:

GAME-789: Implement new particle effects

- Added smoke particle system
- Created explosion effects
- Updated material parameters

This automatically links to task GAME-789 in your connected task management tool.

Automated Build Triggering

Use trigger tags in commit messages to start builds:

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

Example:

GAME-456: New character animations #ci

Added idle and walk cycles for hero character

Pull Request Tracking

Monitor pull request lifecycle:

• PR creation and updates
• Review status and approvals
• Merge/decline events
• Associated commits and file changes

Bitbucket Server Configuration

For on-premises Bitbucket Server instances:

Additional Settings

Network Requirements

• Ensure ButterStack can reach your Bitbucket Server
• Configure firewall to allow webhook delivery
• Verify SSL certificates are valid (or disable verification for testing)

API Usage

ButterStack uses these Bitbucket API endpoints:

Bitbucket Cloud

Bitbucket Server

Webhook Events

Repository Push (Bitbucket Cloud)

{
  "push": {
    "changes": [
      {
        "new": {
          "name": "main",
          "target": {
            "hash": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
            "message": "GAME-123: Add new textures #ci",
            "author": {
              "display_name": "Jane Developer",
              "nickname": "jdeveloper"
            }
          }
        },
        "commits": [
          {
            "hash": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
            "message": "GAME-123: Add new textures #ci",
            "author": {
              "user": {
                "display_name": "Jane Developer"
              }
            }
          }
        ]
      }
    ]
  }
}

Pull Request Event

{
  "pullrequest": {
    "id": 456,
    "title": "Add weapon system",
    "state": "MERGED",
    "destination": {
      "branch": {
        "name": "main"
      }
    },
    "source": {
      "branch": {
        "name": "feature/weapons"
      }
    }
  }
}

Troubleshooting

Authentication Failed

Symptoms: “401 Unauthorized” or connection failures

Solutions:

1. Verify username and app password are correct
2. Check app password hasn’t expired
3. Ensure account has repository access
4. For Bitbucket Server, verify token permissions

Repository Not Found

Symptoms: “404 Not Found” during connection

Solutions:

1. Check repository URL format
2. Verify repository exists and is accessible
3. Ensure account has read access
4. For private repos, confirm app password has appropriate scopes

Webhook Delivery Issues

Symptoms: Changes not appearing in ButterStack

Solutions:

1. Check webhook delivery logs in Bitbucket
2. Verify webhook URL and token
3. Ensure webhook events are properly configured
4. Review ButterStack webhook logs

Bitbucket Server SSL Issues

Symptoms: SSL certificate errors

Solutions:

1. Verify SSL certificate is valid
2. Check certificate chain completeness
3. Temporarily disable SSL verification for testing
4. Update certificate if expired

Security Considerations

App Password Security

1. Minimal Permissions: Only grant required scopes
2. Regular Rotation: Rotate app passwords periodically
3. Unique Passwords: Use dedicated passwords for ButterStack
4. Secure Storage: Never commit passwords to version control

Webhook Security

1. HTTPS Only: Always use HTTPS for webhook URLs
2. Token Authentication: Verify webhook tokens on delivery
3. IP Restrictions: Consider IP allowlisting if available
4. Payload Validation: Verify webhook signatures when possible

Best Practices

1. Clear Commit Messages: Write descriptive, consistent commit messages
2. Task References: Always include task IDs for traceability
3. Build Triggers: Use trigger tags consistently across your team
4. Branch Management: Maintain clear branching and merging strategies
5. Code Reviews: Use pull requests for all significant changes

Migration from Other Git Providers

From GitHub

• Repository URLs remain similar format
• Webhook configuration differs slightly
• App passwords replace personal access tokens
• API endpoints use different versioning

From GitLab

• Update repository URL format
• Configure app passwords instead of personal access tokens
• Adjust webhook configuration for Bitbucket events
• Review API rate limits (different from GitLab)

Related

• GitHub Integration - GitHub-specific integration
• GitLab Integration - GitLab-specific integration
• Jenkins Integration - Build automation
• Core Concepts: 5-Stage Pipeline - Asset lineage overview