# BitBucket

### Integration Setup

To configure the BitBucket integration, follow these steps (either during the onboarding wizard, or once you have access to the Gomboc platform):

1. Go to Settings > Integrations > BitBucket

<div align="left" data-full-width="false"><figure><img src="/files/ZrZgqkdaJTZRUSDptj78" alt="" width="375"><figcaption></figcaption></figure></div>

2. Click on your profile drop down in the top right corner and access your Gomboc settings and create a personal or workspace token.

<figure><img src="/files/0jYoAi4m83RV29vQScJ5" alt="" width="375"><figcaption></figcaption></figure>

3. Once the Gomboc token is created copy the generated token.
4. Click on the BitBucket integration button to open the form for creating the integration
5. Paste in the generated Gomboc token under the input **Gomboc Access Token**
6. In BitBucket, go to your workspace settings to create an access token [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-workspace-access-token/) that has **Repositories (Read & Write)**, **Pull requests (Read & Write)**, and **Webhooks (Read & Write)** permissions. Once generated, copy the workspace access token. Also keep in mind the workspace ID, which can be found within your workspace settings as well.
7. You can now complete the integration form by inputting your Workspace ID and copied workspace access token from BitBucket

<div align="left"><figure><img src="/files/OeF6AVF5mOuKvXzHzGWC" alt="" width="375"><figcaption></figcaption></figure></div>

3\. Click "Integrate" to complete the initial SCM integration.

Review the status notification to ensure that all steps of the integration completed successfully. If the webhook setup failed to automatically complete, follow the steps below to create the webhook.

#### Integration without Webhook Setup

Please note that we do create a workspace webhook to complete the integration and keep track of PR's that we have opened. In the event that setup cannot execute properly due to errors creating the webhook, follow these steps.

1. Follow Step 1 above to navigate to the Integration setup page for Bitbucket
2. Follow Step 4 to open the integration settings
3. Follow Step 6 to create the BitBucket Workspace Access Token
4. Follow Step 7 to complete the integration form, but only specify the Workspace ID and the BitBucket access token. Leave the Gomboc Access Token blank

After you complete the integration, you should see a message that the integration was created successfully, but that the webhook for receiving change request status is not created or active.

### Troubleshooting

#### BitBucket Access Token Issues

If you see the following message, then the access token that you created does not have all of the required scopes. Go back to the BitBucket admin page and create a new token being sure to give **Repositories (Read & Write)**, **Pull requests (Read & Write)**, and **Webhooks (Read & Write)** permissions.

<figure><img src="/files/5aHoOXVp4G682Q0VrqkS" alt=""><figcaption></figcaption></figure>

#### Integration Creation Failures

If the integration fails to create properly, it's possible there are some issues where there are repositories in the workspace which cannot be managed by the admin. This will present as a failure to create the webhook during integration setup. In the logs for the error, Gomboc will be able to find "You cannot administer personal accounts of other users." The workaround for this issue is to create the integration following [these instructions](#integration-without-webhook-setup).

***

## CI/CD

See [BitBucket Pipelines](/integrations/continuous-integration-ci-build-systems/bitbucket-pipelines.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gomboc.ai/integrations/source-code-management-scm/bitbucket.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.