Bitbucket

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

# Set your Bitbucket credentials
export BITBUCKET_USERNAME="your-username"
export BITBUCKET_APP_PASSWORD="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

CLI configuration

The Autohand Code CLI has no separate Bitbucket settings block. The agent works with Bitbucket through git and the Bitbucket REST API, using the credentials in its environment. Put branch, pull request, and reviewer conventions in your project AGENTS.md so the agent follows them.

Configuration options

Bitbucket Pipelines

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

Basic pipeline

Every pipeline on this page runs Autohand with --bare and exports the Autohand provider variables first. Pipeline containers have no stored sign-in, and without --bare the CLI waits for a browser sign-in and the step hangs. Bare mode also skips automatic AGENTS.md loading, so name AGENTS.md in the prompt when the task depends on it. See Authenticate in CI and containers.

Create or update bitbucket-pipelines.yml:

image: node:20

pipelines:
  pull-requests:
    '**':
      - step:
          name: Autohand Code Review
          script:
            - npm i -g autohand-cli
            - export AUTOHAND_PROVIDER=autohandai AUTOHAND_AI_API_KEY="$AUTOHAND_API_KEY"
            - autohand --bare --prompt "Review this PR for bugs and best practices" --restricted > review.md
            - cat review.md
          artifacts:
            - review.md

  custom:
    autohand-fix:
      - step:
          name: Autohand Auto-Fix
          script:
            - npm i -g autohand-cli
            - export AUTOHAND_PROVIDER=autohandai AUTOHAND_AI_API_KEY="$AUTOHAND_API_KEY"
            - autohand --bare --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:

image: node:20

definitions:
  steps:
    - step: &autohand-review
        name: Autohand Review
        script:
          - npm i -g autohand-cli
          - export AUTOHAND_PROVIDER=autohandai AUTOHAND_AI_API_KEY="$AUTOHAND_API_KEY"
          - |
            CHANGED_FILES=$(git diff --name-only origin/$BITBUCKET_PR_DESTINATION_BRANCH...HEAD)
            autohand --bare --prompt "Review these files for issues: $CHANGED_FILES" \
              --restricted \
              --json local > 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 "$(jq '{content: {raw: .content}}' review.json)" \
                "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_FULL_NAME/pullrequests/$BITBUCKET_PR_ID/comments"

Scheduled maintenance

Run automated maintenance tasks:

pipelines:
  custom:
    weekly-maintenance:
      - step:
          name: Dependency Updates
          script:
            - npm i -g autohand-cli
            - export AUTOHAND_PROVIDER=autohandai AUTOHAND_AI_API_KEY="$AUTOHAND_API_KEY"
            - git checkout -b autohand/maintenance-$(date +%Y%m%d)
            - autohand --bare --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:

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

Bitbucket Data Center

For self-hosted Bitbucket Data Center installations, point git and your API calls at your server and pass a personal access token through the environment:

export BITBUCKET_BASE_URL="https://bitbucket.yourcompany.com"
export BITBUCKET_TOKEN="your-personal-access-token"

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