Bitbucket Integration

Connect a Bitbucket repository to automatically sync your organization's configuration. When enabled, your toolkits, skills, commands, MCP servers, and MCP clients will be stored as code in your repository, allowing you to version control and track changes.

info

Only organization-level entities are synced to Bitbucket. User-specific or private entities remain in the database only.

What Gets Synced

The Bitbucket integration syncs the following entity types:

Entity Type	Directory	Format	Notes
Toolkits	toolkits/	JSON files	One file per toolkit
Commands	commands/	JSON files	One file per command
MCP Servers	mcp-servers/	JSON files	Auth credentials excluded for security
MCP Clients	mcp-clients/	JSON files	One file per client
Skills	skills/	Directory per skill	Contains SKILL.md, scripts, references

Sensitive Data

Authentication settings for MCP servers (API keys, secrets, OAuth credentials) are never synced to Bitbucket for security reasons. Only the configuration structure is synced.

Prerequisites

Before setting up Bitbucket integration, ensure you have:

• A Bitbucket workspace with admin permissions
• A repository (public or private) where you want to sync your configuration
• Permission to create OAuth consumers in your workspace

Customize:Workspace slugRepository slugFor SaaS deployments, enter your app URLFor SaaS deployments, https://{your-org}.mcp-s.com

Overview

The Bitbucket integration uses an OAuth 2.0 Consumer for authentication, which provides:

• Client credentials flow: Authenticates as the OAuth consumer rather than a specific user
• API access: Read and write access to repository contents
• Webhook support: Automatic bidirectional sync when changes are pushed to Bitbucket

Step-by-Step Setup Guide

Step 1: Create the Repository

Create a new repository in your Bitbucket workspace where you want to sync your configuration. Note the repository name in workspace/repo-slug format (e.g., acme-corp/webrix-sync).

Step 2: Navigate to OAuth Consumers Settings

Go to your workspace's OAuth consumers settings page:

https://bitbucket.org/{bitbucket-workspace}/workspace/settings/api

Step 3: Add a New OAuth Consumer

Click the "Add consumer" button.

Step 4: Configure the OAuth Consumer

Fill in the basic information:

• Name: Give your consumer a descriptive name (e.g., "Webrix Sync")
• Description: Optional, but helpful for team members
• Callback URL: Set this to your app URL (e.g., https://your-app.com) — Bitbucket requires a callback URL to be set even for client credentials flow. The exact value doesn't matter.

Check "This is a private consumer" — this enables the client_credentials grant type, which is required for the integration to authenticate without a user login.

Under "Permissions", enable:

• Repositories: Read and Write
• Pull requests: Read and Write

This allows the consumer to read, write files, and open pull requests in your repository.

Click Save

Step 5: Configure Webhook Settings

In the "Callback URL" or consumer details, you will need to register a webhook separately on your repository. To do this:

1. Go to your repository settings:

   https://bitbucket.org/{bitbucket-workspace}/{sync-repo}/admin/webhooks

2. Click "Add webhook"

3. In the "Title" field, enter a descriptive name (e.g., "Webrix Sync")

4. In the "URL" field, enter your webhook endpoint:

   • For SaaS deployments: https://{your-org}.mcp-s.com/api/bitbucket/webhook
   • For On-Premise deployments: {Admin dashboard URL}/api/bitbucket/webhook
   tip

   You can copy this URL from the Bitbucket Integration settings page in your admin panel.

5. (Recommended) Add a Secret for security:

   • Generate a secure random string (e.g., using openssl rand -hex 32)
   • Save this secret — you'll need to enter it in your admin settings
   • This ensures webhook requests are authentic

6. Under "Triggers", select Repository → Push

7. Click Save

Security Best Practice

Always use a webhook secret in production environments to prevent unauthorized webhook calls.

Step 6: Copy Your Credentials

After saving, Bitbucket will display your credentials:

• Key — this is your Client ID
• Secret — this is your Client Secret

caution

Store these credentials securely. You'll need to paste them into your admin settings. Never commit them to version control.

Step 7: Configure in Admin Settings

Go to settings → Bitbucket Integration:

1. Click "Connect Bitbucket"
2. Fill in the form with:
   • Workspace: Your Bitbucket workspace slug (e.g., acme-corp)
   • Client ID: The Key from Step 6
   • Client Secret: The Secret from Step 6
   • Webhook Secret: The secret you created in Step 5 (if any)
3. Click "Connect"

The system will automatically:

• Save your settings
• Test the connection

Step 8: Verify the Setup

Go to your Bitbucket repository and check that after the first sync:

• Directories were created (toolkits/, commands/, skills/, etc.)
• Your entities appear as files in their respective directories
• Each file has a meaningful commit message

How It Works

Automatic Sync (Database → Bitbucket)

When you create or update any entity in your admin panel:

1. The entity is saved to the database
2. A background job pushes the change to Bitbucket
3. A commit is created with a descriptive message

Supported operations:

• Toolkits: Synced as toolkits/{slug}.json
• Commands: Synced as commands/{slug}.json
• Skills: Synced as directory skills/{slug}/ with SKILL.md, scripts, references, and assets
• MCP Servers: Synced as mcp-servers/{slug}.json (auth credentials excluded)
• MCP Clients: Synced as mcp-clients/{slug}.json

Webhook Sync (Bitbucket → Database)

When you push changes directly to Bitbucket:

1. Bitbucket sends a webhook notification
2. Your application validates the webhook signature (if a secret is configured)
3. Modified files are detected and classified by type
4. Files are parsed and entities are updated in the database
5. Invalid files are tracked with error details in the entity record

File detection:

• JSON files (*.json) in respective directories are parsed directly
• Skill directories are reconstructed from all files in skills/{slug}/

Error Tracking

When syncing entities from Bitbucket fails, the system tracks errors in the entity's git_integration field and displays them in the UI with a warning icon. Hovering over the icon shows the specific error details.

Error Types

The following error codes may be displayed:

Error Code	HTTP Code	Description	Resolution
INVALID_JSON	400	The JSON file contains invalid syntax	Fix JSON syntax errors in the file
VALIDATION_FAILED	400	Required fields (name or slug) are missing	Add missing required fields to the entity
EMPTY_DIRECTORY	400	Skill directory is empty or missing SKILL.md	Add SKILL.md file to the skill directory
MISSING_INTEGRATION	400	Referenced integration doesn't exist in your organization	Add the integration or update the toolkit to use existing integrations
MISSING_TOOL	400	Referenced tool doesn't exist in the integration	Check tool slugs match available tools in the integration
FETCH_FAILED	500	Failed to fetch the file from Bitbucket	Check OAuth consumer permissions and repository access

Error Resolution

Errors are automatically cleared when:

• The same entity file is successfully synced from Bitbucket
• You manually edit the entity in the admin panel (which triggers a new sync)

To view errors, look for the warning icon (⚠️) next to the entity name in the list view. Hover over it to see the error code and message.

Troubleshooting

Connection Test Fails

Error: "Connection test failed. Please verify your Workspace, Client ID, and Client Secret are correct."

• Verify the workspace slug matches exactly (case-sensitive)
• Ensure the OAuth consumer credentials (Key and Secret) are correct
• Check that the OAuth consumer has the required repository permissions

Webhook Not Working

Entities not syncing from Bitbucket to database

1. Check webhook deliveries in your repository's webhook settings
2. Look for failed webhook requests
3. Verify the webhook URL is correct and accessible
4. Check your application logs for webhook processing errors
5. Ensure files are in the correct directories (toolkits/, commands/, skills/, etc.)

Webhook signature validation fails

• Ensure the webhook secret matches exactly in both places
• Don't include extra spaces or newlines in the secret

Sync Failures

"Repository is empty" or "Branch not found"

• The repository might not have a default branch yet
• Create an initial commit (e.g., a README file) to initialize the repo
• Ensure you're using the default branch name (usually main or master)

"Permission denied"

• Verify the OAuth consumer has Repositories: Read and write permission
• Re-create the consumer and update your admin settings if permissions were changed

Entity shows error indicator

• Check for a warning icon (⚠️) next to the entity name in the list view
• Hover over the icon to see the specific error message
• See the Error Tracking section above for resolution steps
• Fix the issue in Bitbucket or the admin panel, then push/save to clear the error

"Sync successfully 0 entities" or nothing syncing

If the sync completes without errors but 0 entities are synced to Bitbucket, check:

1. Branch Protection Rules

   • Bitbucket branch restrictions may be blocking commits
   • Check your repository's branch restrictions settings
   • Ensure the OAuth consumer is permitted to push, or disable restrictions temporarily

2. Network/Firewall Issues

   • Your server may be unable to reach Bitbucket's API
   • Check outbound network connectivity to api.bitbucket.org
   • Verify firewall rules allow HTTPS traffic to Bitbucket
   • Test with: curl -I https://api.bitbucket.org

3. Repository State

   • Ensure the repository has an initialized default branch
   • Check that the branch name in your configuration matches the actual default branch

4. Entity Eligibility

   • Only organization-level entities are synced to Bitbucket
   • Check if you have any organization-level entities in your database
   • User-specific or private entities are intentionally excluded from sync
   • MCP Clients do not have an owner_id field and are always synced

Security Best Practices

1. OAuth Consumer Credentials

   • Never commit the Client Secret to version control
   • Store it securely (encrypted environment variables or secrets manager)
   • Rotate credentials if they are ever exposed

2. Webhook Secrets

   • Always use webhook secrets in production
   • Use a cryptographically secure random string
   • Rotate secrets if they're ever exposed

3. Repository Permissions

   • Grant the OAuth consumer access only to the configuration repository
   • Review consumer permissions regularly

4. Sensitive Data Handling

   • MCP Server auth credentials (API keys, secrets, OAuth) are automatically excluded from sync
   • Never manually add sensitive data to your Bitbucket repository
   • Use your database/admin panel for managing authentication settings

5. Monitor Access

   • Regularly review OAuth consumer usage in your workspace settings
   • Check webhook delivery logs for suspicious activity
   • Audit configuration changes through Git history

Additional Resources

• Bitbucket OAuth Consumers
• Bitbucket Webhooks
• Bitbucket REST API