> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket integration

> Enrich release notes with Bitbucket Cloud pull request data and links

## Overview

HelixCommit integrates with Bitbucket Cloud's API to enrich your release notes with pull request information, author details, and comparison links. This integration is optional but highly recommended for repositories hosted on Bitbucket.

<Info>
  Bitbucket integration works with Bitbucket Cloud (bitbucket.org). For private repositories, you'll need to provide an App Password or access token with appropriate permissions.
</Info>

## Benefits of Bitbucket integration

<CardGroup cols={2}>
  <Card title="Pull request links" icon="code-pull-request">
    Automatically link commits to their associated pull requests for better traceability
  </Card>

  <Card title="Author attribution" icon="user">
    Show who contributed each change, recognizing team members and external contributors
  </Card>

  <Card title="Compare URLs" icon="link">
    Generate comparison links between versions to see all changes in Bitbucket's UI
  </Card>

  <Card title="Rich metadata" icon="database">
    Include PR descriptions and reviewer information in your release notes
  </Card>
</CardGroup>

## Quick start

### Enable Bitbucket integration

Simply set your Bitbucket token and HelixCommit will automatically fetch PR data:

```bash theme={}
export BITBUCKET_TOKEN=your_app_password_here

helixcommit generate --unreleased --format markdown
```

<Check>
  That's it! HelixCommit automatically detects Bitbucket repositories and enriches the output.
</Check>

### Disable Bitbucket integration

Work offline or skip PR lookups:

```bash theme={}
helixcommit generate --unreleased --no-prs --format markdown
```

## Authentication

### Creating a Bitbucket App Password

<Steps>
  <Step title="Navigate to Bitbucket settings">
    Go to [bitbucket.org/account/settings/app-passwords](https://bitbucket.org/account/settings/app-passwords) and click **Create app password**.
  </Step>

  <Step title="Select permissions">
    <Tabs>
      <Tab title="Public repositories">
        **Minimum required permissions:**

        * Repositories: Read

        With an app password:

        * Higher rate limits
        * Better reliability
      </Tab>

      <Tab title="Private repositories">
        **Required permissions:**

        * Repositories: Read
        * Pull requests: Read

        Ensure you have at least read access to the repository.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set the token">
    <CodeGroup>
      ```bash Environment variable (recommended) theme={}
      export BITBUCKET_TOKEN=your_app_password_here

      # Add to your shell profile for persistence
      echo 'export BITBUCKET_TOKEN=your_app_password_here' >> ~/.bashrc
      ```

      ```bash Command-line flag theme={}
      helixcommit generate \
        --unreleased \
        --bitbucket-token your_app_password_here \
        --format markdown
      ```

      ```yaml CI/CD (Bitbucket Pipelines) theme={}
      pipelines:
        default:
          - step:
              name: Generate release notes
              script:
                - pip install helixcommit
                - helixcommit generate --unreleased --out RELEASE_NOTES.md
              variables:
                BITBUCKET_TOKEN: $BITBUCKET_APP_PASSWORD
      ```
    </CodeGroup>

    <Warning>
      Never commit tokens to version control. Use environment variables or repository variables.
    </Warning>
  </Step>
</Steps>

## What gets enriched

### Pull request resolution

HelixCommit automatically finds PRs associated with commits:

<Tabs>
  <Tab title="Before Bitbucket integration">
    ```markdown theme={}
    ### Features
    - Add user authentication (abc123)
    - Implement dark mode (def456)
    ```
  </Tab>

  <Tab title="After Bitbucket integration">
    ```markdown theme={}
    ### Features
    - Add user authentication (#42) - John Doe
      Implements OAuth2 authentication with JWT tokens
    - Implement dark mode (#45) - Jane Doe
      Adds system-wide theme support with user preferences
    ```
  </Tab>
</Tabs>

### Compare URLs

Automatic comparison links between versions:

```markdown theme={}
## Release v2.0.0
_Released on 2025-11-13_

### Features
- ...

[View full changelog](https://bitbucket.org/workspace/repo/branches/compare/v2.0.0%0Dv1.0.0)
```

### Commit-to-PR mapping

HelixCommit uses multiple strategies to find related PRs:

1. **PR number in commit message**: `feat: Add feature (#123)`
2. **Merged in pattern**: `Merged in feature-branch (pull request #123)`
3. **Bitbucket API lookup**: Search by commit SHA

<Info>
  Using Conventional Commits with PR numbers in messages improves accuracy and reduces API calls.
</Info>

## Rate limiting

### Understanding Bitbucket rate limits

| Authentication      | Rate limit          | Notes          |
| ------------------- | ------------------- | -------------- |
| **Unauthenticated** | 60 requests/hour    | Per IP address |
| **Authenticated**   | 1,000 requests/hour | Per user       |

### How HelixCommit handles rate limits

HelixCommit automatically manages rate limits:

<Steps>
  <Step title="Respects Retry-After headers">
    Reads `Retry-After` header and waits accordingly.
  </Step>

  <Step title="Exponential backoff">
    Retries failed requests with increasing delays.

    ```bash theme={}
    # Configure retry behavior
    export HELIXCOMMIT_BB_MAX_RETRIES=5
    export HELIXCOMMIT_BB_BACKOFF_BASE_SEC=1.0
    export HELIXCOMMIT_BB_BACKOFF_CAP_SEC=16
    ```
  </Step>

  <Step title="Smart caching">
    Caches API responses to reduce duplicate requests.

    ```bash theme={}
    # Enable persistent caching
    export HELIXCOMMIT_BB_CACHE=1
    export HELIXCOMMIT_BB_CACHE_TTL_MINUTES=30
    ```
  </Step>
</Steps>

## Caching

### Enable Bitbucket API caching

Reduce API calls and improve performance:

```bash theme={}
# Enable caching
export HELIXCOMMIT_BB_CACHE=1

# Customize cache location
export HELIXCOMMIT_BB_CACHE_DIR=.cache/bitbucket

# Set cache lifetime (default: 10 minutes)
export HELIXCOMMIT_BB_CACHE_TTL_MINUTES=30

# Generate with caching
helixcommit generate --unreleased
```

### Cache structure

Cached data is stored as JSON files:

```
.helixcommit-cache/
└── bitbucket/
    ├── pr/
    │   └── workspace/repo/
    │       ├── 123.json      # Pull request #123
    │       └── 124.json      # Pull request #124
    └── commit_prs/
        └── workspace/repo/
            └── abc123.json   # Commit lookups
```

## Configuration options

### Environment variables

<ResponseField name="BITBUCKET_TOKEN" type="string" required>
  Bitbucket App Password for API authentication.

  ```bash theme={}
  export BITBUCKET_TOKEN=...
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_BB_MAX_RETRIES" type="integer" default="3">
  Maximum number of retry attempts for failed API requests.

  ```bash theme={}
  export HELIXCOMMIT_BB_MAX_RETRIES=5
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_BB_BACKOFF_BASE_SEC" type="float" default="0.5">
  Initial delay in seconds for exponential backoff.

  ```bash theme={}
  export HELIXCOMMIT_BB_BACKOFF_BASE_SEC=1.0
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_BB_BACKOFF_CAP_SEC" type="float" default="8">
  Maximum delay in seconds between retries.

  ```bash theme={}
  export HELIXCOMMIT_BB_BACKOFF_CAP_SEC=16
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_BB_CACHE" type="boolean" default="false">
  Enable persistent caching of Bitbucket API responses.

  ```bash theme={}
  export HELIXCOMMIT_BB_CACHE=1
  ```

  Valid values: `1`, `true`, `yes`, `on`
</ResponseField>

<ResponseField name="HELIXCOMMIT_BB_CACHE_DIR" type="path" default=".helixcommit-cache/bitbucket">
  Directory for storing cached Bitbucket API responses.

  ```bash theme={}
  export HELIXCOMMIT_BB_CACHE_DIR=.cache/bb-api
  ```
</ResponseField>

<ResponseField name="HELIXCOMMIT_BB_CACHE_TTL_MINUTES" type="integer" default="10">
  Cache time-to-live in minutes.

  ```bash theme={}
  export HELIXCOMMIT_BB_CACHE_TTL_MINUTES=30
  ```
</ResponseField>

### CLI flags

<ParamField query="--bitbucket-token" type="string">
  Provide Bitbucket token via command line.

  ```bash theme={}
  helixcommit generate --bitbucket-token ...
  ```

  <Warning>
    Prefer environment variables over command-line flags to avoid exposing tokens in shell history.
  </Warning>
</ParamField>

<ParamField query="--no-prs" type="boolean">
  Disable Bitbucket PR lookups entirely.

  ```bash theme={}
  helixcommit generate --no-prs
  ```

  Useful for:

  * Offline work
  * Faster generation when PR data isn't needed
</ParamField>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API rate limit exceeded">
    If you hit rate limits:

    1. **Use authentication:**
       ```bash theme={}
       export BITBUCKET_TOKEN=...
       ```

    2. **Enable caching:**
       ```bash theme={}
       export HELIXCOMMIT_BB_CACHE=1
       ```

    3. **Reduce API calls:**
       ```bash theme={}
       # Use --no-prs for testing
       helixcommit generate --no-prs
       ```
  </Accordion>

  <Accordion title="Permission denied errors">
    Verify your App Password has correct permissions:

    1. Go to [bitbucket.org/account/settings/app-passwords](https://bitbucket.org/account/settings/app-passwords)
    2. Check the App Password has `Repositories: Read` and `Pull requests: Read`
    3. Test authentication:
       ```bash theme={}
       curl -u "username:$BITBUCKET_TOKEN" \
         "https://api.bitbucket.org/2.0/user"
       ```
  </Accordion>

  <Accordion title="Pull requests not found">
    If PRs aren't being linked:

    1. **Check commit messages:**
       ```bash theme={}
       git log --oneline -10
       ```
       Ensure PR numbers are mentioned: `feat: Add feature (#123)`

    2. **Verify Bitbucket token:**
       ```bash theme={}
       echo $BITBUCKET_TOKEN | cut -c1-10
       ```

    3. **Test without caching:**
       ```bash theme={}
       rm -rf .helixcommit-cache/
       helixcommit generate --unreleased
       ```

    4. **Check repository remote:**
       ```bash theme={}
       git remote get-url origin
       ```
  </Accordion>

  <Accordion title="Repository not detected as Bitbucket">
    Ensure your remote URL contains "bitbucket.org":

    ```bash theme={}
    # Works
    git@bitbucket.org:workspace/repo.git
    https://bitbucket.org/workspace/repo.git

    # Won't work (different host)
    git@code.example.com:workspace/repo.git
    ```
  </Accordion>
</AccordionGroup>

## Bitbucket Pipelines integration

### Using repository variables

Store your App Password securely in repository variables:

```yaml theme={}
# bitbucket-pipelines.yml
pipelines:
  default:
    - step:
        name: Generate release notes
        script:
          - pip install helixcommit
          - helixcommit generate --unreleased --out RELEASE_NOTES.md
        artifacts:
          - RELEASE_NOTES.md

definitions:
  variables:
    - name: BITBUCKET_TOKEN
      value: $BITBUCKET_APP_PASSWORD
```

### With caching

```yaml theme={}
pipelines:
  default:
    - step:
        name: Generate release notes
        caches:
          - helixcommit
        script:
          - export HELIXCOMMIT_BB_CACHE=1
          - pip install helixcommit
          - helixcommit generate --unreleased --out RELEASE_NOTES.md

definitions:
  caches:
    helixcommit: .helixcommit-cache
```

<Tip>
  Store the App Password in **Repository settings > Repository variables** as a secured variable.
</Tip>

## Best practices

<AccordionGroup>
  <Accordion title="Use consistent commit message format">
    Include PR numbers in commit messages:

    ```bash theme={}
    # Good
    git commit -m "feat: Add authentication (#123)"
    git commit -m "fix: Resolve rate limiting (#124)"

    # Avoid (PR won't be auto-linked)
    git commit -m "Add authentication"
    ```
  </Accordion>

  <Accordion title="Enable caching in CI/CD">
    ```yaml theme={}
    # Bitbucket Pipelines example
    pipelines:
      default:
        - step:
            caches:
              - helixcommit
            script:
              - export HELIXCOMMIT_BB_CACHE=1
              - helixcommit generate --unreleased --out RELEASE_NOTES.md

    definitions:
      caches:
        helixcommit: .helixcommit-cache
    ```
  </Accordion>

  <Accordion title="Test without Bitbucket first">
    Verify basic functionality before enabling Bitbucket integration:

    ```bash theme={}
    # Test offline
    helixcommit generate --unreleased --no-prs

    # Then enable Bitbucket
    export BITBUCKET_TOKEN=...
    helixcommit generate --unreleased
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration" color="#F6A02D">
    Configure Bitbucket integration settings
  </Card>

  <Card title="Examples" icon="code" href="/examples" color="#0A6ACB">
    See Bitbucket integration in action
  </Card>

  <Card title="CI/CD integration" icon="rotate" href="/cicd-integration" color="#F26419">
    Automate release notes in Bitbucket Pipelines
  </Card>

  <Card title="Conventional Commits" icon="code-commit" href="/conventional-commits" color="#0A6ACB">
    Learn about commit message format
  </Card>
</CardGroup>