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.

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.

Benefits of Bitbucket integration

Pull request links

Automatically link commits to their associated pull requests for better traceability

Author attribution

Show who contributed each change, recognizing team members and external contributors

Compare URLs

Generate comparison links between versions to see all changes in Bitbucket’s UI

Rich metadata

Include PR descriptions and reviewer information in your release notes

Quick start

Enable Bitbucket integration

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

export BITBUCKET_TOKEN=your_app_password_here

helixcommit generate --unreleased --format markdown

That’s it! HelixCommit automatically detects Bitbucket repositories and enriches the output.

Disable Bitbucket integration

Work offline or skip PR lookups:

helixcommit generate --unreleased --no-prs --format markdown

Authentication

Creating a Bitbucket App Password

1. Navigate to Bitbucket settings

   Go to bitbucket.org/account/settings/app-passwords and click Create app password.

2. Select permissions

   Public repositories

   Minimum required permissions:

   • Repositories: Read

   With an app password:

   • Higher rate limits
   • Better reliability

   Private repositories

   Required permissions:

   • Repositories: Read
   • Pull requests: Read

   Ensure you have at least read access to the repository.

3. Set the token

   Environment variable (recommended)

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

   Never commit tokens to version control. Use environment variables or repository variables.

What gets enriched

Pull request resolution

HelixCommit automatically finds PRs associated with commits:

Before Bitbucket integration

### Features
- Add user authentication (abc123)
- Implement dark mode (def456)

After Bitbucket integration

### 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

Compare URLs

Automatic comparison links between versions:

## 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

Using Conventional Commits with PR numbers in messages improves accuracy and reduces API calls.

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:

1. Respects Retry-After headers

   Reads Retry-After header and waits accordingly.

2. Exponential backoff

   Retries failed requests with increasing delays.

   # Configure retry behavior
   export HELIXCOMMIT_BB_MAX_RETRIES=5
   export HELIXCOMMIT_BB_BACKOFF_BASE_SEC=1.0
   export HELIXCOMMIT_BB_BACKOFF_CAP_SEC=16
   
3. Smart caching

   Caches API responses to reduce duplicate requests.

   # Enable persistent caching
   export HELIXCOMMIT_BB_CACHE=1
   export HELIXCOMMIT_BB_CACHE_TTL_MINUTES=30
   

Caching

Enable Bitbucket API caching

Reduce API calls and improve performance:

# 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

BITBUCKET_TOKEN · string · required

Bitbucket App Password for API authentication.

export BITBUCKET_TOKEN=...

HELIXCOMMIT_BB_MAX_RETRIES · integer · default: "3"

Maximum number of retry attempts for failed API requests.

export HELIXCOMMIT_BB_MAX_RETRIES=5

HELIXCOMMIT_BB_BACKOFF_BASE_SEC · float · default: "0.5"

Initial delay in seconds for exponential backoff.

export HELIXCOMMIT_BB_BACKOFF_BASE_SEC=1.0

HELIXCOMMIT_BB_BACKOFF_CAP_SEC · float · default: "8"

Maximum delay in seconds between retries.

export HELIXCOMMIT_BB_BACKOFF_CAP_SEC=16

HELIXCOMMIT_BB_CACHE · boolean · default: "false"

Enable persistent caching of Bitbucket API responses.

export HELIXCOMMIT_BB_CACHE=1

Valid values: 1, true, yes, on

HELIXCOMMIT_BB_CACHE_DIR · path · default: ".helixcommit-cache/bitbucket"

Directory for storing cached Bitbucket API responses.

export HELIXCOMMIT_BB_CACHE_DIR=.cache/bb-api

HELIXCOMMIT_BB_CACHE_TTL_MINUTES · integer · default: "10"

Cache time-to-live in minutes.

export HELIXCOMMIT_BB_CACHE_TTL_MINUTES=30

CLI flags

--bitbucket-token · string

Provide Bitbucket token via command line.

helixcommit generate --bitbucket-token ...

Prefer environment variables over command-line flags to avoid exposing tokens in shell history.

--no-prs · boolean

Disable Bitbucket PR lookups entirely.

helixcommit generate --no-prs

Useful for:

• Offline work
• Faster generation when PR data isn’t needed

Troubleshooting

API rate limit exceeded

If you hit rate limits:

1. Use authentication:

   export BITBUCKET_TOKEN=...
   

2. Enable caching:

   export HELIXCOMMIT_BB_CACHE=1
   

3. Reduce API calls:

   # Use --no-prs for testing
   helixcommit generate --no-prs
   

Permission denied errors

Verify your App Password has correct permissions:

1. Go to bitbucket.org/account/settings/app-passwords
2. Check the App Password has Repositories: Read and Pull requests: Read
3. Test authentication:
   curl -u "username:$BITBUCKET_TOKEN" \
     "https://api.bitbucket.org/2.0/user"
   

Pull requests not found

If PRs aren’t being linked:

1. Check commit messages:

   git log --oneline -10
   

   Ensure PR numbers are mentioned: feat: Add feature (#123)

2. Verify Bitbucket token:

   echo $BITBUCKET_TOKEN | cut -c1-10
   

3. Test without caching:

   rm -rf .helixcommit-cache/
   helixcommit generate --unreleased
   

4. Check repository remote:

   git remote get-url origin
   

Repository not detected as Bitbucket

Ensure your remote URL contains “bitbucket.org”:

# Works
[e-mail]:workspace/repo.git
https://bitbucket.org/workspace/repo.git

# Won't work (different host)
[e-mail]:workspace/repo.git

Bitbucket Pipelines integration

Using repository variables

Store your App Password securely in repository variables:

# 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

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

Store the App Password in Repository settings > Repository variables as a secured variable.

Best practices

Use consistent commit message format

Include PR numbers in commit messages:

# 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"

Enable caching in CI/CD

# 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

Test without Bitbucket first

Verify basic functionality before enabling Bitbucket integration:

# Test offline
helixcommit generate --unreleased --no-prs

# Then enable Bitbucket
export BITBUCKET_TOKEN=...
helixcommit generate --unreleased

Next steps

Configuration

Configure Bitbucket integration settings

Examples

See Bitbucket integration in action

CI/CD integration

Automate release notes in Bitbucket Pipelines

Conventional Commits

Learn about commit message format