Skip to main content
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

opensre integrations setup
Select Bitbucket when prompted and provide your workspace, username, and app password.

​
Option 2: Environment variables

Add to your .env: 
BITBUCKET_WORKSPACE=your-workspace-slug
BITBUCKET_USERNAME=your-username
BITBUCKET_APP_PASSWORD=your-app-password
VariableDefaultDescription
BITBUCKET_WORKSPACE—Required. Bitbucket workspace slug
BITBUCKET_USERNAME—Required. Bitbucket username
BITBUCKET_APP_PASSWORD—Required. Bitbucket app password

​
Option 3: Persistent store

{
  "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
The workspace slug is the identifier in your Bitbucket URL: https://bitbucket.org/<workspace>/

​
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

opensre integrations verify --service bitbucket
Expected output: 
Service: bitbucket
Status: passed
Detail: Authenticated as Your Name; workspace: your-workspace

​
Troubleshooting

SymptomFix
401 UnauthorizedCheck username and app password combination
Workspace not foundVerify the workspace slug — it’s case-sensitive
403 ForbiddenEnsure the app password has Repositories: Read permission
Code search unavailableCode 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.