> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygarth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket

***

# 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.

## Navigation

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**

```text theme={null}
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**

```text theme={null}
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

| Permission    | Access Level       |
| ------------- | ------------------ |
| Repositories  | Read               |
| Pull Requests | Read (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**

```text theme={null}
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**

```text theme={null}
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