Bitbucket

Bitbucket is a Git-based source code repository hosting service for collaborative software development, code review, and CI/CD pipelines.

Authentication Types

Bitbucket supports 3 authentication methods:

• OAuth - Create your own Bitbucket OAuth app with custom scopes. Every user connects with their Bitbucket account.

  • Pros: Full control, per-user tracking, production-ready
  • Cons: ~2 min setup

• API Key - Use your Bitbucket username and app password for authentication.

  • Pros: Easy setup
  • Cons: Single credential for all users

• API Key Per User - Each user provides their own Bitbucket username and app password.

  • Pros: Per-user tracking, better security
  • Cons: Each user needs to set up their own credentials

General Settings

Before using the connector, you need to configure:

• Bitbucket URL - Your Bitbucket instance URL (e.g., https://bitbucket.org for cloud or your self-hosted URL)
• Bitbucket Workspace - Your Bitbucket workspace slug

Setting up OAuth

1. Go to your Bitbucket workspace settings at https://bitbucket.org/{workspace}/workspace/settings/oauth-consumers

2. Click Add consumer

3. Fill in the OAuth consumer details:
   • Name: Give it a descriptive name (e.g., "Webrix Integration")
   • Callback URL: Copy the Redirect URL from Webrix and paste it here
   • URL: Your organization's website (optional)

4. Select the permissions (scopes) you need:
   • Repositories: Read and write access
   • Pull requests: Read and write access
   • Pipelines: Read and write access
   • Account: Read account information
   • Team: Read team information
   • Webhooks: Manage webhooks

5. Click Save

6. Copy the Key (Client ID) and Secret (Client Secret)

7. In Webrix, paste the Client ID and Client Secret

8. Enter your Bitbucket URL and Workspace in General Settings

9. Click Save Changes

Generating an API Key (App Password)

1. Go to https://bitbucket.org/account/settings/app-passwords/

2. Click Create app password

3. Give your app password a descriptive label (e.g., "Webrix Integration")

4. Select the permissions you need:

   • Repositories: Read and write
   • Pull requests: Read and write
   • Pipelines: Read and write
   • Account: Read
   • Workspace membership: Read

5. Click Create

6. Copy the generated password immediately (it won't be shown again)

7. In Webrix, enter the API key in the format: username:app_password
   • Example: john.doe:ATBBxxxxxxxxxxxxx
   • Note: The API key will be Base64 encoded automatically as Basic {encoded_credentials}

Available Scopes

The Bitbucket connector provides access to the following scopes:

• repository: Read repository information
• repository:write: Write access to repositories
• pullrequest: Read pull requests
• pullrequest:write: Create and update pull requests
• pipeline: Read pipeline information
• pipeline:write: Trigger and manage pipelines
• account: Read account information
• team: Read team/workspace information
• webhook: Manage webhooks for repositories

For more information about Bitbucket permissions, refer to the Bitbucket API documentation.