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

# Bitbucket

> Connect Bitbucket so OpenSRE can correlate recent commits and code changes with incidents

OpenSRE queries Bitbucket to retrieve recent commits, file contents, and code search results — helping trace which change in a Bitbucket-hosted repository triggered an incident.

## Prerequisites

* Bitbucket Cloud account
* App password with repository read access

## Setup

### Option 1: Interactive CLI

```bash theme={null}
opensre integrations setup
```

Select **Bitbucket** when prompted and provide your workspace, username, and app password.

### Option 2: Environment variables

Add to your `.env`:

```bash theme={null}
BITBUCKET_WORKSPACE=your-workspace-slug
BITBUCKET_USERNAME=your-username
BITBUCKET_APP_PASSWORD=your-app-password
```

| Variable                 | Default | Description                            |
| ------------------------ | ------- | -------------------------------------- |
| `BITBUCKET_WORKSPACE`    | —       | **Required.** Bitbucket workspace slug |
| `BITBUCKET_USERNAME`     | —       | **Required.** Bitbucket username       |
| `BITBUCKET_APP_PASSWORD` | —       | **Required.** Bitbucket app password   |

### Option 3: Persistent store

```json theme={null}
{
  "version": 1,
  "integrations": [
    {
      "id": "bitbucket-prod",
      "service": "bitbucket",
      "status": "active",
      "credentials": {
        "workspace": "your-workspace-slug",
        "username": "your-username",
        "app_password": "your-app-password"
      }
    }
  ]
}
```

## Creating an app password

1. In Bitbucket, go to **Personal settings** → **App passwords**
2. Click **Create app password**
3. Give it a label (e.g., `opensre`)
4. Enable the following permissions: **Repositories: Read**
5. Copy the generated password

<Info>
  The workspace slug is the identifier in your Bitbucket URL: `https://bitbucket.org/<workspace>/`
</Info>

## Investigation tools

When OpenSRE investigates a Bitbucket-related alert, three tools are available:

* **Commits** — retrieves recent commits for a repository, optionally filtered by file path
* **File contents** — fetches the contents of a file at a specific revision
* **Code search** — searches code across the workspace or a specific repository

All operations are read-only.

## Verify

```bash theme={null}
opensre integrations verify bitbucket
```

Expected output:

```
Service: bitbucket
Status: passed
Detail: Authenticated as Your Name; workspace: your-workspace
```

## Troubleshooting

| Symptom                     | Fix                                                             |
| --------------------------- | --------------------------------------------------------------- |
| **401 Unauthorized**        | Check username and app password combination                     |
| **Workspace not found**     | Verify the workspace slug — it's case-sensitive                 |
| **403 Forbidden**           | Ensure the app password has **Repositories: Read** permission   |
| **Code search unavailable** | Code search requires a Bitbucket Cloud Standard or Premium plan |

## Security best practices

* Use an **app password** rather than your account password — app passwords can be revoked individually.
* Scope permissions to **Repositories: Read** only.
* Store credentials in `.env`, not in source code.