BitBucket

Bitbucket integration allows your product to connect with Bitbucket repositories to fetch project metadata, list repositories, create or manage issues, review pull requests, and analyze commits or pipelines. This integration is essential for enabling DevSecOps workflows, vulnerability scanning, CI/CD pipeline monitoring, and repository management within your platform.

Credentials Needed

To connect to Bitbucket, you can use either OAuth2 credentials or App Passwords, depending on your use case.

For Cloud Integrations (Recommended):

• Bitbucket Username (Email)
• App Password

For Multi-user Integrations via OAuth2:

• Client ID
• Client Secret
• Redirect URI (Callback URL)

Note: For self-managed Bitbucket Server (Data Center), you'll need personal access tokens generated from the admin console, which follow a similar structure.

Permissions Needed / API Scopes

Bitbucket uses scopes to define what an integration can access.

Choose scopes based on the functionality required in your product.

Functionality	Required Scopes	Description
Read repositories	repository:read	View repositories, commits, and metadata
Write to repositories	repository:write	Create or modify repo data (optional)
Manage issues	issue:read, issue:write	View or create issues
Manage pull requests	pullrequest:read, pullrequest:write	View or manage PRs
Read pipelines	pipeline:read	Access pipeline details
Read user details	account:read	Get basic user info
Admin repository webhooks	webhook	Manage repository webhooks

Minimal Scopes for Read/Write Repository and Issue Management: repository:read, issue:read, pullrequest:read, account:read

Creating Users / Access Tokens

Step 1: Generate an App Password (Recommended for Simplicity)

1. Go to Bitbucket → Personal Settings → App Passwords Direct link: https://bitbucket.org/account/settings/app-passwords/
2. Click Create App Password.
3. Enter a label (e.g., BitbucketIntegrationApp).
4. Select the following scopes:
   • repository:read
   • issue:read (if using issues)
   • pullrequest:read (if using PRs)
   • pipeline:read (optional, for CI/CD)
   • account:read
5. Click Create.
6. Copy and securely store the App Password — it will only be shown once.

Step 2 (Optional): Create an OAuth Consumer

For integrations that support multiple Bitbucket users (OAuth2-based):

1. Go to Bitbucket → Personal Settings → OAuth Consumers Direct link: https://bitbucket.org/account/settings/app-passwords/
2. Click Add Consumer.
3. Enter:
   • Name: Your product name
   • Callback URL: The redirect URI of your platform (e.g., https://yourapp.com/oauth/callback)
   • Permissions:
     • repository:read, issue:read, pullrequest:read, account:read
4. Click Save.
5. Copy the Key (Client ID) and Secret (Client Secret).

Test Connectivity

Test using curl or a REST client:

# Replace <USERNAME> and <APP_PASSWORD>
curl -u <USERNAME>:<APP_PASSWORD> https://api.bitbucket.org/2.0/user

# List repositories for the authenticated user
curl -u <USERNAME>:<APP_PASSWORD> https://api.bitbucket.org/2.0/repositories/<USERNAME>

# List issues (if available)
curl -u <USERNAME>:<APP_PASSWORD> https://api.bitbucket.org/2.0/repositories/<USERNAME>/<REPO_SLUG>/issues

If you get valid responses (status code 200 with JSON data), your integration credentials and permissions are correct.

Save the Results in the Platform and Create Connection

In your platform's integration setup, securely store:

• BITBUCKET_USERNAME
• BITBUCKET_APP_PASSWORD
• or, for OAuth2: CLIENT_ID, CLIENT_SECRET, and REDIRECT_URI

Create a new connector labeled Bitbucket Integration.

Test the connection by listing repositories or creating a test issue to validate permissions.

Best Practices

• Use App Passwords for single-user integrations and OAuth2 Consumers for multi-user setups.
• Always grant minimum scopes required for your integration — avoid repository:admin or write scopes unless necessary.
• Rotate App Passwords or OAuth tokens periodically for security.
• Store all credentials securely in your product's encrypted secret manager.
• For large organizations, prefer OAuth2 so each user can authenticate individually without sharing credentials.
• If integrating with Bitbucket Server (self-hosted), ensure your API base URL points to your instance instead of api.bitbucket.org.
• Log API rate limits and handle pagination in responses to avoid throttling issues.