> For the complete documentation index, see [llms.txt](https://docs.firefly.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firefly.ai/integrations/version-control/bitbucket.md).

# Bitbucket

Firefly integrates with Bitbucket to connect your infrastructure code repositories with your cloud resources. This integration enables powerful features like tracing cloud resources back to their defining code ("Jump to Code") and automatically creating Pull Requests for newly codified resources and drift remediation.

## Prerequisites

* A Bitbucket account with access to your infrastructure repositories.
* Appropriate permissions to create an OAuth consumer or an Atlassian API token (depending on the authentication method you choose).
* Repositories containing Terraform, CloudFormation, or other IaC files you want to connect to Firefly.

## Setup Procedures

Firefly supports two authentication methods for Bitbucket Cloud. Choose the one that best fits your needs:

* [**OAuth**](#oauth) — authorize Firefly through a Bitbucket OAuth consumer.
* [**API Token**](#api-token) — authenticate with a scoped Atlassian API token.

### OAuth

> **Prerequisite:** To successfully integrate Firefly with your Bitbucket account, you must be the workspace admin.

1. Log in to your Bitbucket account.
2. Click on your Avatar on the top right panel, then click on **All workspaces**.
3. Select the workspace Firefly will be integrated with.
4. Click on the Settings icon on the top right panel (to the left of your Avatar) and select **Workspace settings**.
5. Please scroll down in the left panel and click on **OAuth clients**.
6. Click on **Create OAuth client** to create a new integration with Firefly.

   * Select a name for the application.
   * Add a description (optional).
   * In the **Callback URL**, please paste the following URL: `https://app.firefly.ai/integrations/bitbucket-integration`
   * In the **Permission** section, please select the following:
     * Account: read

     * Repositories: write and admin

     * Pull requests: write

     * Webhooks: read and write

   > **Note:** All the permissions must be selected for the integration to be successful.
7. Scroll to the bottom of the page and click **Save**. You will be directed to the OAuth clients where you can see the newly created client.
8. Click on the new client to see its details:
   * Please copy the **Client ID** and paste it in Firefly's Bitbucket Integration page in the **Client ID** field.
   * Please copy the **Secret** and paste it in Firefly's Bitbucket Integration page in the **Secret** field.
9. After filling in the information, please click the **Authorize** button in Firefly's Bitbucket Integration page.
10. In the new page that opens, please press **Grant Access**.

    > **Note:** You must authorize for the integration to be successful.
11. After authorizing the new application, you will be redirected back to Firefly's application.
12. After the integration is completed, please enter your Bitbucket account email in the **Bitbucket Email** field and the workspace ID in the **Workspace ID** field. Click **Create Integration** to check if the workspace exists.
13. When the validation is complete, click on the **Next** button for webhooks to be installed.

### API Token

> **Prerequisite:** Create a scoped Atlassian API token (not an app password). Bitbucket Cloud app passwords are being retired. Follow [Create an API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).

1. Select your profile in the upper-right corner of Bitbucket, then open **Account settings**.
2. On the Atlassian Account page, open the **Security** tab.
3. Select **Create and manage API tokens**, then **Create API token with scopes**.
4. Give the token a name and an expiry date, then select **Next**.
5. Select **Bitbucket** as the app, then select **Next**.
6. Select the following scopes (see API token permissions), then select **Next**:

   * **Account: read**
     * `read:account`
     * `read:workspace:bitbucket`
   * **Repositories: write and admin**
     * `read:repository:bitbucket`
     * `write:repository:bitbucket`
     * `admin:repository:bitbucket`
   * **Pull requests: write**
     * `read:pullrequest:bitbucket`
     * `write:pullrequest:bitbucket`
   * **Webhooks: read and write**
     * `read:webhook:bitbucket`

     * `write:webhook:bitbucket`

   > **Note:** In the granular token model, `write` does not imply `read` — select the `read:*` scopes explicitly. An unscoped API token will fail with `401`.
7. Review and select **Create token**. Copy the token immediately — it is shown only once.
8. In Firefly, enter your Atlassian account email, paste the API token, and enter the **Workspace ID**. Click **Create Integration**.
9. When validation completes, click **Next** for webhooks to be installed.

### Integrate Bitbucket Data Center

1. Enter the domain for your Bitbucket Data Center instance and paste the app password into the **App Password** box.

## Features Enabled

* **Jump to Code**: Trace resources in your cloud inventory back to the Bitbucket file and specific line that defines them.
* **Automated Pull Requests**: When Firefly codifies an unmanaged resource, it can commit the new infrastructure code as a Pull Request.
* **IaC Tracking**: Firefly maintains awareness of which resources are defined in code and which are not.
* **Drift Remediation**: Firefly can detect drift between the code and the actual resources and create a Pull Request to fix it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.firefly.ai/integrations/version-control/bitbucket.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.