Bitbucket Provider Setup & App Passwords

Tokomono\GitSync\Services\BitbucketProvider integrates with the Bitbucket Cloud REST API v2 (https://api.bitbucket.org/2.0) using HTTP Basic Authentication (username + App Password).

Step-by-Step: Creating a Bitbucket App Password in the Bitbucket UI

1. Log in to Bitbucket.org and click the gear icon (Settings) in the top-right navigation bar.
2. Select Personal Bitbucket settings from the dropdown.
3. In the left sidebar under Access management, click App passwords.
4. Click the Create app password button.
5. Enter a descriptive Label (e.g., GitSync Staging PR Bot).
6. Under Permissions, check the following scopes:
   • Repositories: Check both Read and Write (required to inspect branch hashes, create branches, and commit files).
   • Pull requests: Check both Read and Write (required to create Pull Requests).
7. Click Create and copy the generated App Password from the modal dialog.

Important: Bitbucket BITBUCKET_USERNAME is your Bitbucket Username (found under Personal settings → Account settings), not your email address.

Add Credentials to .env

GIT_SYNC_PROVIDER=bitbucket
BITBUCKET_USERNAME=your_bitbucket_username
BITBUCKET_PASSWORD=your_generated_app_password
BITBUCKET_WORKSPACE=your_workspace_slug
BITBUCKET_REPOSITORY=your_repo_slug

Under the Hood: Bitbucket REST API v2 Calls

BitbucketProvider scopes all HTTP requests to https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}:

1. createBranch(string $sourceBranch, string $newBranch): void
   • Sends GET /refs/branches/{sourceBranch} to retrieve target.hash of the base branch.
   • Sends POST /refs/branches with {"name": "{newBranch}", "target": {"hash": "{hash}"}}.
2. commitFile(string $branch, string $filePath, string $content, string $commitMessage): void
   • Sends a multipart/form-data POST /src request containing message, branch, and the file path mapped to its raw file contents.
3. createPullRequest(string $sourceBranch, string $targetBranch, string $title, string $description): string
   • Sends POST /pullrequests with title, description, source.branch.name, and destination.branch.name.
   • Returns links.html.href (the browser URL of the created Bitbucket Pull Request).