Skip to main content

Set Up the Bitbucket Integration

This guide takes you through creating an OAuth consumer and connecting it so your organization's configuration syncs to a repository.

For what gets synced and how sync behaves, see Bitbucket Integration.

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 On-Premise deployments, enter your app URLFor SaaS, enter your organization: https://{your-org}.mcp-s.com

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/willow-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., "Willow 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., "Willow 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

What to do next​

On this page