---
title: "Bitbucket Integration"
source: https://docs.autohand.ai/integrations/bitbucket
---

# Bitbucket

Integrate Autohand with Bitbucket for automated code reviews, PR management, and CI/CD pipeline automation using Bitbucket Pipelines.

## Overview

Autohand integrates with Bitbucket Cloud and Bitbucket Data Center to provide:

-   Automated code reviews on pull requests
-   Intelligent PR descriptions and summaries
-   CI/CD automation with Bitbucket Pipelines
-   Branch management and merge conflict resolution
-   Repository insights and documentation generation

## Authentication

Configure Bitbucket authentication in your Autohand settings:

### App password

For personal use or small teams, create a Bitbucket App Password:

1.  Go to **Personal settings > App passwords** in Bitbucket
2.  Click **Create app password**
3.  Name it "Autohand" and select the required permissions
4.  Copy the generated password

``` bash
# Set your Bitbucket credentials
export BITBUCKET_USERNAME="your-username"
export BITBUCKET_APP_PASSWORD="your-app-password"

# Or configure in settings.json
autohand config set bitbucket.username "your-username"
autohand config set bitbucket.appPassword "your-app-password"
```

### OAuth consumer

For workspace-wide access, create an OAuth consumer:

1.  Go to **Workspace settings > OAuth consumers**
2.  Click **Add consumer**
3.  Set the callback URL to your Autohand instance
4.  Select the required permissions
5.  Save and copy the Key and Secret

### Required permissions

| Permission | Access | Purpose |
|---|---|---|
| Repositories | Read & Write | Read code and push changes |
| Pull requests | Read & Write | Create and review PRs |
| Pipelines | Read & Write | Trigger and manage builds |
| Webhooks | Read & Write | Receive repository events |
| Account | Read | Access user information |

## CLI configuration

Configure Bitbucket integration in your `~/.autohand/settings.json`:

``` json
{
  "bitbucket": {
    "enabled": true,
    "username": "${BITBUCKET_USERNAME}",
    "appPassword": "${BITBUCKET_APP_PASSWORD}",
    "workspace": "your-workspace",
    "defaultBranch": "main",
    "autoCreatePR": true,
    "reviewers": ["@team/reviewers"],
    "defaultReviewers": true
  }
}
```

### Configuration options

| Option | Description | Default |
|---|---|---|
| enabled | Enable Bitbucket integration | true |
| username | Bitbucket username | - |
| appPassword | App password for authentication | - |
| workspace | Default workspace slug | - |
| defaultBranch | Default target branch for PRs | main |
| autoCreatePR | Automatically create PRs for changes | false |
| reviewers | Default reviewers for PRs | [] |
| defaultReviewers | Use repository default reviewers | true |

## Bitbucket Pipelines

Run Autohand in your CI/CD pipelines for automated code analysis and fixes.

### Basic pipeline

Create or update `bitbucket-pipelines.yml`:

``` yaml
image: node:20

pipelines:
  pull-requests:
    '**':
      - step:
          name: Autohand Code Review
          script:
            - npm i -g autohand-cli
            - autohand --prompt "Review this PR for bugs and best practices" --restricted --output markdown > review.md
            - cat review.md
          artifacts:
            - review.md

  custom:
    autohand-fix:
      - step:
          name: Autohand Auto-Fix
          script:
            - npm i -g autohand-cli
            - autohand --prompt "$AUTOHAND_TASK" --yes
            - git add -A
            - git commit -m "fix: automated fix by Autohand" || echo "No changes"
            - git push origin HEAD
```

### Code review pipeline

Automatically review pull requests:

``` yaml
image: node:20

definitions:
  steps:
    - step: &autohand-review
        name: Autohand Review
        script:
          - npm i -g autohand-cli
          - |
            CHANGED_FILES=$(git diff --name-only origin/$BITBUCKET_PR_DESTINATION_BRANCH...HEAD)
            autohand --prompt "Review these files for issues: $CHANGED_FILES" \
              --restricted \
              --output json > review.json
          - cat review.json
        artifacts:
          - review.json

pipelines:
  pull-requests:
    '**':
      - step: *autohand-review
      - step:
          name: Post Review Comment
          script:
            - |
              curl -X POST \
                -u "$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD" \
                -H "Content-Type: application/json" \
                -d "{\"content\": {\"raw\": \"$(cat review.json | jq -r '.summary')\"}}" \
                "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_FULL_NAME/pullrequests/$BITBUCKET_PR_ID/comments"
```

### Scheduled maintenance

Run automated maintenance tasks:

``` yaml
pipelines:
  custom:
    weekly-maintenance:
      - step:
          name: Dependency Updates
          script:
            - npm i -g autohand-cli
            - git checkout -b autohand/maintenance-$(date +%Y%m%d)
            - autohand --prompt "Update dependencies and fix deprecations" --yes
            - git add -A
            - git commit -m "chore: weekly maintenance" || exit 0
            - git push origin HEAD
            - |
              curl -X POST \
                -u "$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD" \
                -H "Content-Type: application/json" \
                -d '{"title": "Weekly Maintenance", "source": {"branch": {"name": "autohand/maintenance-'$(date +%Y%m%d)'"}}}' \
                "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_FULL_NAME/pullrequests"
```

## Repository variables

Configure these variables in **Repository settings > Pipelines > Repository variables**:

| Variable | Description | Secured |
|---|---|---|
| AUTOHAND_API_KEY | Your Autohand API key | Yes |
| BITBUCKET_USERNAME | Bitbucket username for API calls | No |
| BITBUCKET_APP_PASSWORD | App password for authentication | Yes |
| OPENROUTER_API_KEY | OpenRouter key (if using custom models) | Yes |

## Webhooks

Configure webhooks to trigger Autohand on repository events:

1.  Go to **Repository settings > Webhooks**
2.  Click **Add webhook**
3.  Set the URL to your Autohand webhook endpoint
4.  Select triggers: Pull request created, Pull request updated, Push
5.  Save the webhook

### Supported events

| Event | Autohand action |
|---|---|
| Pull request created | Automatic code review |
| Pull request updated | Incremental review of changes |
| Push to branch | Code analysis and suggestions |
| Pipeline failed | Failure analysis and fix suggestions |

## Bitbucket Data Center

For self-hosted Bitbucket Data Center installations:

``` json
{
  "bitbucket": {
    "type": "datacenter",
    "baseUrl": "https://bitbucket.yourcompany.com",
    "username": "${BITBUCKET_USERNAME}",
    "token": "${BITBUCKET_TOKEN}",
    "verifySsl": true
  }
}
```

### Personal access token

For Data Center, use a personal access token instead of app passwords:

1.  Go to **Account settings > Personal access tokens**
2.  Click **Create token**
3.  Set permissions: Repository read/write, Pull request read/write
4.  Copy the generated token

## Troubleshooting

### Authentication errors

-   Verify your app password has not expired
-   Check that required permissions are enabled
-   Ensure the username matches your Bitbucket account

### Pipeline failures

-   Check that `AUTOHAND_API_KEY` is set in repository variables
-   Verify the pipeline has internet access for npm install
-   Review pipeline logs for specific error messages

### Webhook issues

-   Verify the webhook URL is accessible from Bitbucket
-   Check webhook delivery history in repository settings
-   Ensure the webhook secret matches your configuration