lightdash · sdolidze · Sep 9, 2026 · Sep 9, 2026
diff --git a/agents/ai-writeback.mdx b/agents/ai-writeback.mdx
@@ -30,10 +30,11 @@ For other kinds of changes, the agent will pick a different tool:
 
 ## Prerequisites
 
-- Your project's dbt connection must be a **GitHub** or **GitLab** repository. Bitbucket, Azure DevOps, dbt Cloud, and local dbt projects are not supported.
-- The matching Lightdash app must be installed for the repository so the agent can open requests:
+- Your project's dbt connection must be a **GitHub**, **GitLab**, or **Bitbucket Cloud** repository. Azure DevOps, dbt Cloud, and local dbt connections are not supported by this workflow.
+- Configure access for your Git provider:
   - **GitHub** — install the Lightdash GitHub App on the repository.
   - **GitLab** — connect the Lightdash GitLab App for your organization. Writeback works against GitLab.com; self-hosted GitLab domains aren't reachable from the writeback sandbox yet.
+  - **Bitbucket Cloud** — configure the [project API token and writeback permissions](/get-started/quickstart/connect-project#bitbucket-cloud-api-token).
 - You need at least [project Developer](/workspace-admin/roles) permissions on the project.
 
 ## How it works
@@ -42,7 +43,7 @@ When you ask the agent for a change that belongs in the repo, it calls a tool ca
 
 1. Generates a self-contained instruction from your request and starts a sandboxed environment with no memory of your chat. A follow-up to the same change resumes that environment; an unrelated request gets a fresh one.
 2. Edits the relevant files and runs `lightdash compile` to validate the result.
-3. Pushes a new branch and opens a pull request (GitHub) or merge request (GitLab) against your repository's default branch.
+3. Pushes a new branch and opens a pull request (GitHub or Bitbucket) or merge request (GitLab) against the branch configured in your project connection.
 4. Returns the pull request URL to you in chat.
 
 The tool call can take a few minutes. The agent tells you a pull request is being prepared, and the chat card auto-updates in place with the pull request URL as soon as the run finishes — you don't need to send another message or refresh the thread.
@@ -58,6 +59,12 @@ If you're driving writeback from an external client via MCP rather than the in-p
   GitLab commits are pushed over OAuth and are unsigned.
 </Note>
 
+### Bitbucket Cloud behavior
+
+Bitbucket AI writeback edits the connected dbt repository. Follow-up requests can add commits to the same open pull request. If that request has been merged or declined, a follow-up starts a fresh pull request.
+
+Review and merge Bitbucket pull requests in Bitbucket, then sync the project in Lightdash. The integration does not provide automatic preview projects, Bitbucket Pipelines status, or merging from the chat card. Repository browsing and file mentions have separate provider requirements, described below. Standalone Lightdash YAML projects, Bitbucket Server/Data Center, and general-purpose coding-agent access are outside this Bitbucket integration.
+
 ## Using it in chat
 
 Phrase your request as a direct change to the repo and, where possible, name the file, model, or field you want touched. The more specific you are, the more reliably the agent finds the right place to edit.
@@ -112,10 +119,10 @@ The writeback PR card has two action groups:
 
 - **View ▾** — a dropdown with up to three entries:
   - **Preview** — opens the Lightdash preview environment for the PR's branch, so you can click around the change before merging. Hidden if no preview is available (for example, on non-GitHub runs or when preview deploys aren't set up for the project).
-  - **Pull request** — opens the PR on GitHub or GitLab in a new tab.
+  - **Pull request** — opens the PR on GitHub, GitLab, or Bitbucket in a new tab.
   - **Diff** — opens a diff viewer inside Lightdash with a file-list sidebar (file name and per-file `+/−` counts) and a unified diff for the selected file.
 - **Close PR** / **Merge PR** — a button group for finishing the review in place:
-  - **Merge PR** stays disabled until the host reports the PR as mergeable (required checks passing, no conflicts, branch not blocked by branch protection). The card pins the commit SHA it was opened against, so you can't accidentally merge a newer commit that was pushed after the agent posted the card.
+  - **Merge PR** is available for GitHub and stays disabled until the host reports the PR as mergeable (required checks passing, no conflicts, branch not blocked by branch protection). The card pins the commit SHA it was opened against, so you can't accidentally merge a newer commit that was pushed after the agent posted the card.
   - **Close PR** closes the PR without merging.
   - Both actions ask you to confirm before sending the request.
   - Once the PR reaches a terminal state, the button group collapses to a **Merged** or **Closed** marker and the card stops polling.
@@ -182,7 +189,7 @@ When you follow up on a change whose pull request is already open — either ear
 - **Paste a link.** Paste the GitHub pull request URL alongside your request — in this thread or a new one — and the agent checks out that PR's branch and commits your edits onto it.
 
 <Note>
-If the pull request behind a change has already been merged or closed — from the chat card or directly on GitHub/GitLab — the agent can't push more commits to its branch. Rather than blocking, it opens a fresh pull request for your follow-up in the same thread, so there's no need to start a new one.
+If the pull request behind a change has already been merged or closed — from the chat card or directly on GitHub, GitLab, or Bitbucket — the agent can't push more commits to its branch. Rather than blocking, it opens a fresh pull request for your follow-up in the same thread, so there's no need to start a new one.
 </Note>
 
 ```text
@@ -202,12 +209,13 @@ If any of those checks fail, the agent stops and tells you why instead of silent
 
 | Situation | Result |
 | --- | --- |
-| Project's dbt connection isn't GitHub or GitLab | The agent tells you the project must be connected to a supported git host for writeback. |
+| Project's dbt connection isn't GitHub, GitLab, or Bitbucket Cloud | The agent tells you the project must be connected to a supported git host for writeback. |
 | GitHub App isn't installed on the repo | The agent surfaces a setup error. Install the Lightdash GitHub App on the repository (from your project's dbt connection settings) and try again. |
 | Writeback agent makes no file changes | No pull request or merge request is opened. The agent reports back that nothing needed to change. |
 | Pasted PR link is in a different repo, merged, closed, or from a fork | The agent rejects the link with an explanation and does not open a new pull request. |
 | The pull request behind a change has been merged or closed | The agent can't add to that pull request, so a follow-up opens a fresh one in the same thread. |
 | GitLab App isn't connected for the organization | The agent surfaces a `GitLab App is not installed` error. Connect the Lightdash GitLab App for your organization and try again. |
+| Bitbucket token is missing, expired, revoked, or lacks permissions | Update the [project API token](/get-started/quickstart/connect-project#bitbucket-cloud-api-token) and confirm the owner can write to the repository. |
 
 ## Related
 

diff --git a/agents/lightdash-mcp.mdx b/agents/lightdash-mcp.mdx
@@ -446,9 +446,9 @@ These tools reuse the same permissions, validation, and project context as the [
 
 #### Editing the dbt project
 
-MCP exposes [AI writeback](/agents/ai-writeback) — editing the dbt project that backs the active Lightdash project and opening a pull request with the change — to any MCP client. Ask the assistant to rename a metric, add a dimension, edit a model's SQL, or fix a YAML description; the assistant calls the tools below and hands back a pull request URL when the run finishes. The [AI writeback prerequisites](/agents/ai-writeback#prerequisites) — supported git host, app installation, project Developer permission — apply to the MCP surface too.
+MCP exposes [AI writeback](/agents/ai-writeback) — editing the dbt project that backs the active Lightdash project and opening a pull request with the change — to any MCP client. Ask the assistant to rename a metric, add a dimension, edit a model's SQL, or fix a YAML description; the assistant calls the tools below and hands back a pull request URL when the run finishes. The [AI writeback prerequisites](/agents/ai-writeback#prerequisites) — supported git host, provider access, and project Developer permission — apply to the MCP surface too.
 
-- **Run AI writeback** (`run_ai_writeback`) - Start a writeback run against the active project's dbt repository from a natural-language prompt. The target GitHub or GitLab repository and dbt sub-folder are resolved server-side from the project's dbt connection — you don't specify them. Returns immediately with an `aiWritebackRunUuid`.
+- **Run AI writeback** (`run_ai_writeback`) - Start a writeback run against the active project's dbt repository from a natural-language prompt. The target GitHub, GitLab, or Bitbucket Cloud repository and dbt sub-folder are resolved server-side from the project's dbt connection — you don't specify them. Returns immediately with an `aiWritebackRunUuid`.
 - **Get AI writeback status** (`get_ai_writeback_status`) - Poll a writeback run by id. Returns the current pipeline stage while the run is in flight, and the pull request URL (or an error message) once it reaches a terminal state.
 
 ##### How the async flow works

diff --git a/get-started/quickstart/connect-project.mdx b/get-started/quickstart/connect-project.mdx
@@ -1481,52 +1481,52 @@ If your dbt project is in a sub-folder in your repo (e.g. `lightdash/lightdash-a
 
 ### Bitbucket
 
-##### Username
+Connect a dbt repository on Bitbucket using the project's **API Token** field. Choose **Bitbucket** in your project's connection settings.
 
-This is the login name for your Bitbucket user. This is usually the same username you use to login to Bitbucket. You can find your username in Bitbucket by:
+#### Bitbucket Cloud API token
 
-1. Going to your avatar in the bottom left and click **Personal settings**.
+For repositories on `bitbucket.org`, use a personal API token with scopes. Follow [Atlassian's token creation instructions](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/):
 
-2. From the **Account settings** page, check the value next to the **Username**
+1. Open your Atlassian account's **Security** settings, then **Create and manage API tokens**.
+2. Select **Create API token with scopes**, name the token, and choose its expiry date.
+3. Select **Bitbucket** as the app, then choose the permissions below.
+4. Create the token and copy it into Lightdash's **API Token** field. Atlassian displays the token only once.
 
-Alternatively, you can [create a new user through the Bitbucket console](https://confluence.atlassian.com/bitbucketserver/users-and-groups-776640439.html)with a username and password specifically for Lightdash to use.
+| Permission | Scope | When needed |
+| --- | --- | --- |
+| Repositories: Read | `read:repository:bitbucket` | Connecting and syncing the dbt project |
+| Repositories: Write | `write:repository:bitbucket` | Writeback |
+| Pull requests: Read | `read:pullrequest:bitbucket` | Writeback |
+| Pull requests: Write | `write:pullrequest:bitbucket` | Writeback |
 
-##### Http access token
+Select all four permissions for writeback. Write scopes do not include read scopes; see [Atlassian's API token permissions](https://support.atlassian.com/bitbucket-cloud/docs/api-token-permissions/). A connection used only to read and sync the repository needs only Repositories: Read.
 
-Getting a token depends on whether you use Bitbucket Cloud or Bitbucket server:
+The token's owner must have access to the repository and permission to push branches and create pull requests. Bitbucket writeback uses that person's identity. Lightdash users still need [source-code write permissions](/workspace-admin/roles) on the project to use the stored token. No Bitbucket OAuth connection or Lightdash GitHub App installation is required.
 
-* Bitbucket Cloud users should [follow instructions for creating an App Password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/)
+#### Connection fields
 
-* Bitbucket Server users should [follow instructions for creating a HTTP Access Token](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html)
+- **Username:** your Bitbucket username, with the exact capitalization shown in your Bitbucket personal settings. Use the username, not your email address.
+- **API Token:** the token created above.
+- **Repository:** the workspace and repository slug, such as `my-workspace/analytics`. Do not enter the full URL.
+- **Branch:** the branch Lightdash syncs from, such as `main`. Writeback opens a separate change branch and targets this configured branch.
+- **Project directory path:** `/` if `dbt_project.yml` is at the repository root, or a subfolder such as `/dbt` if it lives at `dbt/dbt_project.yml`.
+- **Host domain:** leave blank for Bitbucket Cloud, or use `bitbucket.org`.
 
-Select `Project read` and `Repository read` scope when you're creating the token.
-
-##### Repository
-
-This should be in the format `my-org/my-repo`. e.g. `lightdash/lightdash-analytics`
-
-##### Branch
-
-This is the branch in your Bitbucket repo that Lightdash should sync to. e.g. `main`, `master` or `dev`
-
-By default, we've set this to `main` but you can change it to whatever you'd like.
-
-##### Project directory path
+<Frame>
+  <img src="/images/get-started/quickstart/connect-project/bitbucket-connection.png" alt="Bitbucket connection fields showing the username, required API token permissions, and repository slug" />
+</Frame>
 
-This is the folder where your `dbt_project.yml` file is found in the Bitbucket repository you entered above.
+Save the connection and complete the [dbt project settings](/integrations/dbt/projects#dbt-project-settings). For the available writeback actions, see [dbt write-back](/integrations/dbt/write-back) and [AI writeback](/agents/ai-writeback).
 
-* Put `/` if your `dbt_project.yml` file is in the main folder of your repo (e.g. lightdash/lightdash-analytics/dbt\_project.yml)
+#### Updating credentials
 
-* Include the path to the sub-folder where your dbt project is if your dbt project is in a sub-folder in your repo. For example, if my project was in lightdash/lightdash-analytics/dbt/dbt\_project.yml, I'd write `/dbt` in this field.
+If the token expires or is revoked, create a replacement with the required permissions and update **API Token** in the project's connection settings. A token that can sync but cannot write back may be missing writeback scopes or repository permissions.
 
-##### Host domain
-
-If you've [customized the domain for your Bitbucket server](https://confluence.atlassian.com/bitbucketserver/specify-the-bitbucket-base-url-776640392.html), you can add the custom domain for your project in here.
+When changing the repository, host, or username, provide credentials for the new destination. Lightdash does not carry the stored token over to a different credential destination.
 
+#### Bitbucket Server and Data Center
 
-<Check>
-  After adding your Bitbucket information, fill out the [dbt project details](/integrations/dbt/projects#dbt-project-settings) and you're all set!
-</Check>
+For a company-hosted Bitbucket instance, use an [HTTP access token](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) with **Project read** and **Repository read**, and enter your instance's **Host domain**. These connections support reading the dbt project; Bitbucket writeback supports Cloud only. Here, “Cloud” means the Git host is `bitbucket.org`, not that Lightdash must be hosted on Lightdash Cloud.
 
 ***
 

diff --git a/images/get-started/quickstart/connect-project/bitbucket-connection.png b/images/get-started/quickstart/connect-project/bitbucket-connection.png
diff --git a/images/integrations/dbt/write-back/bitbucket-sql-model.png b/images/integrations/dbt/write-back/bitbucket-sql-model.png
diff --git a/integrations/dbt/write-back.mdx b/integrations/dbt/write-back.mdx
@@ -4,10 +4,16 @@ description: "Develop models and metrics in Lightdash and open a pull request ag
 ---
 
 <Info>
-  - dbt Write-Back is currently only available for dbt projects hosted in GitHub and GitLab.
+  - dbt write-back supports dbt projects hosted in GitHub, GitLab, and Bitbucket Cloud.
   - You need to be at least a [`project Developer`](/workspace-admin/roles) to use dbt Write-Back.
 </Info>
 
+## Bitbucket Cloud setup
+
+Connect your project using the [Bitbucket token setup instructions](/get-started/quickstart/connect-project#bitbucket-cloud-api-token). All three workflows below use that stored project token and the configured repository, branch, and dbt directory.
+
+Bitbucket support covers dbt projects on `bitbucket.org`. Standalone Lightdash YAML projects and Bitbucket Server/Data Center are not supported by this Bitbucket writeback integration. Review and merge the pull request in Bitbucket, then sync the project in Lightdash. Writeback does not run your dbt models, display Bitbucket Pipelines status, or create an automatic preview project.
+
 ## Write back Metrics from Custom Metrics
 
 You can build Custom Metrics in Lightdash and write these back to your dbt project so they are promoted to permanent Metrics in your YAML.
@@ -94,12 +100,20 @@ To get started, build and run a query in the SQL runner, then select the `Write
   ![The SQL runner Save dropdown open, with Write back to dbt below Save chart and Create virtual view](/images/integrations/dbt/write-back/dbt-write-back-3774e219cdb58ad09a5e290b28e8b427.jpg)
 </Frame>
 
-You'll be asked to enter a name that will be used as the model name and file names in your dbt project. Clicking `Open pull request` will open a pull request created by Lightdash against your dbt project in GitHub or GitLab.
+You'll be asked to enter a name that will be used as the model name and file names in your dbt project. Clicking `Open pull request` will open a pull request created by Lightdash against your dbt project in GitHub, GitLab, or Bitbucket Cloud.
 
 <Frame>
   ![A GitHub pull request opened by Lightdash adding a SQL file and matching .yml config for a new model](/images/integrations/dbt/write-back/write-back-pull-request-5c36c33617a258728a644d1e76896725.jpg)
 </Frame>
 
+For Bitbucket Cloud, the dialog previews the repository and both filenames before opening the pull request:
+
+<Frame>
+  <img src="/images/integrations/dbt/write-back/bitbucket-sql-model.png" alt="SQL Runner writeback dialog naming an order summary model and previewing its SQL and YAML files in the Bitbucket repository" />
+</Frame>
+
+Bitbucket writeback creates the SQL and YAML files together in one commit. If either filename already exists, choose a different model name; writeback does not overwrite the existing model.
+
 The new model will be written to your dbt project in a `models/lightdash/` directory. The model will have the tag `created-by-lightdash` included in the model config.
 
 ### Getting your model to appear as a `Table` in Lightdash