Skip to main content

Bitbucket Integration

Connect Bitbucket Cloud to enable the AI agent to access code repositories, pull requests, and CI/CD pipeline information during investigations.

Capabilities​

Once connected, the AI agent can:

CapabilityDescription
Browse CodeView repository files and contents
Search CodeSearch across workspace repositories
Pull RequestsReview PRs, diffs, and changes
CommitsView commit history and details
BranchesList and inspect branches
PipelinesCheck CI/CD pipeline status and logs

Prerequisites​

  • A Bitbucket Cloud account
  • An Atlassian API Token with scopes, or a Workspace/Repository Access Token
  • Read access to relevant repositories

Setup​

1
Create an API Token with Scopes
  1. Go to Atlassian API Tokens
  2. Click Create API token with scopes
  3. Enter a name (e.g., "Autoheal Integration")
  4. Set an expiration date
  5. Select Bitbucket as the application
  6. Filter permissions by "read" and grant the following scopes:
    • read:repository:bitbucket
    • read:pipeline:bitbucket
    • read:workspace:bitbucket
    • read:pullrequest:bitbucket
    • read:project:bitbucket
    • read:user:bitbucket
    • read:account
    • read:me
  7. Click Create and copy the token
warning

Bitbucket App Passwords are deprecated. Use API token with scopes (not the plain "API token" option).

2
Find Your Workspace Slug

Your workspace slug is in your Bitbucket URL: bitbucket.org/{workspace}

You can also find it in Bitbucket Settings → Workspace settings.

3
Add Integration in Autoheal
  1. Go to Integrations in Autoheal
  2. Click Bitbucket
  3. Enter a name (e.g., "Production Bitbucket")
4
Configure Credentials

Choose an authentication method:

API Token (recommended):

  • Email: Your Atlassian account email
  • API Token: The token you created in step 1
  • Workspace: Your Bitbucket workspace slug

Access Token (alternative):

  • Access Token: A Workspace or Repository Access Token
  • Workspace: Your Bitbucket workspace slug
5
Test and Save

Click Test Connection to verify, then Save.

Required Scopes​

When creating the API token with scopes, grant these read permissions:

ScopeWhy It's Needed
read:repository:bitbucketAccess repository contents and metadata
read:pipeline:bitbucketView CI/CD pipeline status and logs
read:workspace:bitbucketAccess workspace information
read:pullrequest:bitbucketView pull request details and diffs
read:project:bitbucketAccess project information
read:user:bitbucketView user information
read:accountAccess account details
read:meIdentify the authenticated user
tip

Filter the permissions list by "read" to quickly find and select all required scopes.

Authentication Methods​

API Token with Scopes (Recommended)

Uses your Atlassian account email and an API token with scopes created at id.atlassian.com. Select "Create API token with scopes" (not the plain "Create API token" option). Access is scoped to the permissions you grant.

Access Token

Uses a Workspace Access Token or Repository Access Token. Created in Bitbucket Workspace settings → Access Tokens or Repository settings → Access Tokens. Scoped to a specific workspace or repository.

Example Queries​

What pipelines failed in the last 24 hours?
Show me recent pull requests for the backend service
What commits were merged to main yesterday?
What changed in the last deployment pipeline?

Troubleshooting​

401 Unauthorized / Token not supported
  • Ensure you created an API token with scopes (not a plain "API token")
  • Verify the token has the required read scopes (see Required Scopes)
  • For API Token auth, ensure you're using your Atlassian account email (not Bitbucket username)
  • Check that the token has not expired or been revoked
403 Forbidden
  • Verify your account has access to the workspace
  • For Access Tokens, check that the required permissions are granted
  • Ensure the workspace slug is correct
404 Not Found
  • Verify the workspace slug is correct (check your Bitbucket URL)
  • Ensure the repository exists and your account has access
Rate Limited
  • Bitbucket has API rate limits (1,000 requests/hour)
  • Wait for the rate limit window to reset