New Integration: Bitbucket

Description

Add Bitbucket integration to sync repositories, pull requests, commits, issues, and pipelines into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - Directly comparable Git hosting platform
• integrations/linear/ - For issue tracking patterns
• integrations/slack/ - For reference

Required Files Structure

integrations/bitbucket/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Bitbucket API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Bitbucket API Integration

OAuth Setup

• Use OAuth 2.0 (Authorization Code Grant)
• API Version: 2.0
• Base URL: https://api.bitbucket.org/2.0/
• Authorization URL: https://bitbucket.org/site/oauth2/authorize
• Token URL: https://bitbucket.org/site/oauth2/access_token
• Required scopes:
  • repository - Read access to repositories
  • repository:write - Write access to repositories
  • pullrequest - Read access to pull requests
  • pullrequest:write - Write access to pull requests
  • issue - Read access to issues
  • issue:write - Write access to issues
  • pipeline - Read access to pipelines
  • account - Read access to account information
  • webhook - Manage webhooks

Key Endpoints

• GET /2.0/repositories/{workspace}/{repo_slug} - Get repository
• GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests - List pull requests
• GET /2.0/repositories/{workspace}/{repo_slug}/commits - List commits
• GET /2.0/repositories/{workspace}/{repo_slug}/issues - List issues
• GET /2.0/repositories/{workspace}/{repo_slug}/pipelines - List pipelines
• GET /2.0/repositories/{workspace}/{repo_slug}/src - Browse source
• GET /2.0/repositories/{workspace} - List workspace repositories
• GET /2.0/workspaces - List workspaces
• GET /2.0/repositories/{workspace}/{repo_slug}/refs/branches - List branches
• GET /2.0/repositories/{workspace}/{repo_slug}/deploy-keys - List deploy keys

Events to Track

1. Pull Requests

   • PR created, updated, merged, declined
   • PR comments and approvals
   • PR build status changes
   • Code review activity

2. Commits & Code

   • New commits pushed
   • Branch created/deleted
   • Tag created
   • Repository forked

3. Issues & Pipelines

   • Issue created, updated, resolved
   • Pipeline started, completed, failed
   • Deployment events

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create Bitbucket API utilities in utils.ts
• Implement sync logic in schedule.ts
• Convert Bitbucket events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Bitbucket Cloud REST API v1.0 is deprecated. Always use v2.0.
• Rate limiting: 1,000 requests per hour for authenticated requests.
• Pagination uses page and pagelen parameters with next/previous links in response.
• Webhooks support over 30 event types for real-time notifications.
• Bitbucket is owned by Atlassian; OAuth consumers are created in workspace settings.
• Access tokens expire after 2 hours; refresh tokens should be used for renewal.
• The API supports workspace-level and repository-level resources.

Resources

• Bitbucket Cloud REST API
• About Bitbucket Cloud REST API
• Bitbucket Cloud REST API Scopes
• Bitbucket OAuth
• Bitbucket Webhooks

Labels

enhancement, integration, new-feature