Skip to main content

Bitbucket Integration

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

info

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

Configure it under Admin > Settings > Git Integration, which also supports GitHub.

What Gets Synced​

The Bitbucket integration syncs the following entity types:

Entity TypeDirectoryFormatNotes
Toolkitstoolkits/JSON filesOne file per toolkit
Commandscommands/JSON filesOne file per command
MCP Serversmcp-servers/JSON filesAuth credentials excluded for security
MCP Clientsmcp-clients/JSON filesOne file per client
Skillsskills/Directory per skillContains 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.

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

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}/

What to do next​

Additional Resources​

On this page