Skip to main content

​
Bitbucket Repository Integration

​
Overview

The Bitbucket Repository Integration allows Engineering Metrics to connect with Bitbucket repositories and collect repository-level engineering analytics data for reporting, DORA metrics, CI/CD tracking, and repository insights. The integration supports:
  • Repository synchronization
  • Commit and code analytics
  • Pipeline and deployment data collection
  • Project mapping and reporting
  • Engineering metrics visualization
The overall integration flow is similar to GitLab, with a few Bitbucket-specific authentication and configuration differences. To access Bitbucket integrations:
  1. Open the Engineering Metrics platform.
  2. Navigate to Integration → Data Integrations Hub.
  3. Under Repository Integrations, locate Bitbucket.
  4. Click:
    • Connect if no connection exists.
    • Manage if an existing connection is already configured.

​
Creating a New Bitbucket Connection

Inside the Bitbucket Connections page:
  1. Click New Connection.
  2. The Bitbucket connection configuration modal opens.

​
Connection Configuration Fields

​
Connection Name

Field: Connection Name Purpose Defines a unique identifier for the Bitbucket integration connection.
Important: The connection name must be unique and cannot duplicate an existing connection name.
Examples
  • Bitbucket Production
  • Engineering Bitbucket
  • Internal Bitbucket Workspace

​
Endpoint URL

Field: Endpoint URL Purpose Defines the Bitbucket server or API endpoint Engineering Metrics will connect to. Usage
  • For Bitbucket Cloud, the default Bitbucket endpoint is generally used.
  • For self-hosted or enterprise environments, users may need to provide a custom endpoint URL.
Example 
https://api.bitbucket.org/

​
Credential Type

Field: Credential Type Purpose Defines the authentication method used for the Bitbucket integration. The platform supports API token-based authentication for repository access and synchronization.

​
Username

Field: Username Purpose The Username field requires the email ID or username associated with the Bitbucket account.
Important:
  • This should match the account associated with the API token or app password.
  • The account must have repository access permissions.
  • Incorrect usernames may cause authentication failure.
Example 
user@company.com

​
API Token / App Password

Field: API Token Purpose Authenticates Engineering Metrics with Bitbucket.
Important: Bitbucket previously used App Passwords, but newer implementations may use API Tokens depending on the Bitbucket environment and configuration.
The provided token must include sufficient permissions to:
  • Access repositories
  • Read repository metadata
  • Fetch commit and pipeline-related data
Important: Insufficient permissions may cause:
  • Test connection failures
  • Missing repositories
  • Incomplete synchronization

​
Minimum Required Permissions

PermissionAccess Level
RepositoriesRead
Pull RequestsRead (Recommended)

​
Proxy Configuration

Field: Proxy Purpose Allows Engineering Metrics to connect through a proxy server when required. Typical Use Cases
  • Enterprise firewall restrictions
  • Restricted network environments
  • Self-hosted deployments
Example 
http://proxy.localhost:8080
Note: This field is optional and is typically not required for standard cloud setups.

​
Custom Rate Limit

Field: Custom Rate Limit Purpose Allows users to manually configure API request limits. Default Behavior Engineering Metrics automatically manages API request throttling. When Enabled Users can define custom rate limiting behavior to:
  • Prevent API throttling
  • Reduce load on Bitbucket servers
  • Optimize synchronization performance

​
Testing the Connection

Before saving the connection:
  1. Click Test Connection.

​
Expected Result

Engineering Metrics validates:
  • Endpoint accessibility
  • Username authentication
  • API token permissions
  • Bitbucket API communication
Successful validation confirms the integration is properly configured.

​
Saving the Connection

After successful validation:
  1. Click Save Connection.

​
Result

The Bitbucket connection becomes available inside the Connections panel.

​
Data Scope Configuration

After creating the connection:
  1. Select the desired Bitbucket connection.
  2. Click Add Data Scope.
The Add Data Scope window allows users to select repositories for synchronization.

​
Repository Selection

The Data Scope page includes:
  • Search bar for repository lookup
  • Repository listing table
Displayed repository information includes:
  • Repository Name
  • Organization
  • Last Updated Time

​
Adding Repository Scopes

  1. Search for the desired repository.
  2. Select the repository using the checkbox.
  3. Click Add Scope.

​
Result

Selected repositories become part of the Engineering Metrics synchronization scope.

​
Scope Configuration

After repository scopes are added, users can associate Scope Configurations with the selected repository scopes. Scope Configurations define:
  • What data should be collected
  • Which engineering entities should be tracked
  • CI/CD deployment stage configuration
  • Metrics collection behavior

​
Common Data Entities

  • Code Management
  • Code Review
  • Issue Tracking
  • CI/CD
  • Cross Domain

​
CI/CD Deployment Configuration

Inside Scope Configuration settings, users can configure deployment stage identifiers and pipeline names. Examples
  • deploy
  • production
  • release
Purpose This helps Engineering Metrics identify deployment-related activities required for DORA metrics and CI/CD analytics.

​
Project Mapping

After configuring repository scopes:
  1. Navigate to the Projects section.
  2. Create or edit a project.
  3. Select the Bitbucket connection.
  4. Select one or more repository scopes.
  5. Configure synchronization behavior.
  6. Complete setup.

​
Sync Behavior Configuration

​
Data Collection Duration

Defines how much historical data should be collected. Examples
  • Last 30 Days
  • Last 6 Months
  • Last 1 Year

​
Sync Frequency

Defines how often synchronization occurs. Available options include:
  • Daily
  • Weekly
  • Monthly
  • Custom Intervals
Example 
Every 2 Hours
By default, scheduled synchronization runs automatically based on the configured schedule.

​
Running Policy

Option: Skip Failed Task Purpose Allows synchronization jobs to continue running even if individual subtasks fail. Benefit Prevents entire synchronization failures caused by partial task issues.

​
DORA Metrics Configuration

To enable DORA metrics:
  1. Navigate to project settings.
  2. Enable the required deployment-related settings.
  3. Save the configuration.
Important: This step is required specifically for DORA metrics collection.
It is not mandatory for:
  • Commit metrics
  • Standard CI/CD metrics
  • Repository analytics

​
Run Sync Now

Button: Run Sync Now Purpose Immediately collects the latest repository and pipeline data from Bitbucket. Behavior Only newly available data is synchronized during execution.

​
Retransform Data

Button: Retransform Data Purpose Reprocesses already collected data into standardized formats for reporting and analytics.
Important: This operation does not fetch new data. It only transforms existing synchronized data.

​
Status and Execution History

The Status section displays:
  • Synchronization history
  • Task execution duration
  • Completed tasks
  • Success and failure states
  • Execution timestamps
This helps users monitor synchronization activity and troubleshoot integration issues.

​
Best Practices

​
Use Dedicated Service Accounts

Recommended Use a dedicated Bitbucket service account for integrations instead of personal accounts. Benefits
  • Improved security
  • Easier maintenance
  • Simplified credential management

​
Verify Token Permissions

Ensure the API token or app password includes:
  • Repository read permissions
  • Metadata access permissions
  • Pipeline access permissions if CI/CD metrics are required

​
Use Descriptive Connection Names

Examples
  • Bitbucket Production
  • Bitbucket Engineering
  • Bitbucket Internal Workspace
This improves maintainability when multiple integrations exist.

​
Limit Repository Scope

Only synchronize repositories required for reporting and analytics. Benefits
  • Faster synchronization
  • Lower API usage
  • Improved platform performance

​
Troubleshooting

​
Test Connection Fails

Possible Causes
  • Invalid API token
  • Incorrect username
  • Endpoint connectivity issues
  • Missing permissions
Resolution
  • Verify token validity
  • Confirm username matches the Bitbucket account
  • Validate endpoint accessibility
  • Recheck permissions

​
Repositories Not Visible

Possible Causes
  • Insufficient repository permissions
  • Incorrect account access
  • Synchronization issues
Resolution
  • Verify repository visibility
  • Confirm token permissions
  • Retry synchronization

​
Sync Failures

Possible Causes
  • API throttling
  • Invalid deployment stage mappings
  • Partial task failures
Resolution
  • Enable custom rate limiting if required
  • Validate CI/CD stage names
  • Review task status logs

​
Expected Outcome

After successful setup:
  • Bitbucket repositories are connected to Engineering Metrics
  • Repository and pipeline data becomes available for analytics
  • CI/CD and DORA metrics can be generated
  • Repository trends and engineering insights become accessible from the dashboard