> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-docs-wall-clock-timezone.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI writeback

> Ask an AI agent to edit dbt or native Lightdash YAML files and open a pull request

AI writeback lets you ask an AI agent in chat or Slack to edit the repository that backs your project and open a pull request with the change. It can update dbt models or [native Lightdash YAML models](/semantic-layer/yaml#ai-writeback-and-issues), including metrics, dimensions, and descriptions.

Use it for changes that need editing across project files. To promote an individual custom field, use the write-back action in the Explore view.

For changes that don't belong in the semantic layer project — for example, editing an app repo, a service, or a docs site — use the [AI coding agent](/agents/ai-coding-agent) instead.

## When to use it

Use AI writeback when the change belongs in your semantic layer project files:

* Rename a metric in a YAML file
* Add a metric or dimension to a model
* Edit field SQL, or a dbt model's SQL
* Update a description, label, or dbt `meta` block
* Fix a typo in a column definition

For other kinds of changes, the agent will pick a different tool:

| You want to…                                     | The agent uses…           |
| ------------------------------------------------ | ------------------------- |
| Ask a question about data                        | Query and discovery tools |
| Edit an existing chart or dashboard in Lightdash | `editContent`             |
| Change dbt or native Lightdash YAML source files | `editDbtProject`          |

## Prerequisites

* Use a supported repository connection: **GitHub**, **GitLab.com**, or **Bitbucket Cloud** for dbt; **GitHub** or **Bitbucket Cloud** for native Lightdash YAML. Azure DevOps, dbt Cloud, and CLI-only connections are not supported for AI writeback.
* Configure repository access so the agent can open requests:
  * **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.

For native projects, follow [Connect through GitHub or Bitbucket Cloud](/semantic-layer/yaml#connect-through-github) and select **Native Lightdash YAML** as the semantic layer format.

## How it works

When you ask the agent for a change that belongs in the repo, it calls a tool called `editDbtProject`. The tool:

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 validates the result. dbt projects use `lightdash compile`; native projects use [native YAML validation](/semantic-layer/yaml#ai-writeback-and-issues) without setting up dbt.
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.

If you're driving writeback from an external client via MCP rather than the in-product chat, see [Editing the dbt project](/agents/lightdash-mcp#editing-the-dbt-project) — the MCP flow returns a run id immediately and you poll `get_ai_writeback_status` for the pull request URL.

<Note>
  By default, GitHub commits are signed by the Lightdash GitHub App. If you've
  [linked your personal GitHub account](/workflow/pull-requests#pull-request-author),
  AI writeback pull requests are attributed to you instead (as long as your
  linked account can access the repository) — and the agent itself may prompt
  you in chat to link your account if you haven't yet.
  GitLab commits are pushed over OAuth and are unsigned.
</Note>

### Bitbucket Cloud behavior

Bitbucket AI writeback edits dbt or native Lightdash YAML files in the connected 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. 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.

**Good prompts**

```text theme={null}
In models/orders.yml, rename the metric `total_revenue` to `net_revenue`
and update its description to "Revenue after refunds and discounts."
```

```text theme={null}
Add a new metric `active_users_7d` to the users model. It should be a
count_distinct of user_id filtered to events in the last 7 days.
```

```text theme={null}
In the customers model, fix the typo in the `lifetime_value` dimension
description: change "lifteime" to "lifetime."
```

### Mentioning project files with `@`

In the agent chat input, type `@` to open the mention menu. Alongside chart and dashboard suggestions, the **Files** group lists source files in your project's repository. Pick a file and its path is inserted as a pill in your message.

Use file mentions to point the writeback agent at the exact file you want changed:

```text theme={null}
Update @models/orders.yml so the `total_revenue` metric is renamed to
`net_revenue`.
```

When the agent processes your message, it reads the mentioned file directly from the repository and uses it as the starting point for the change — reducing the chance of editing the wrong model or YAML block in a large project.

File mentions are available on **GitHub**-connected projects only and require the same source-code access as the rest of the writeback flow. Non-GitHub projects don't see the **Files** group in the mention menu.

**Less effective prompts**

```text theme={null}
Clean up our metrics.
```

```text theme={null}
Make the orders model better.
```

When the pull request is ready, the agent posts a card in the thread with everything you need to review and act on it without leaving Lightdash.

## Reviewing and acting on the pull request

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, 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** 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.

When you merge from the card, Lightdash recompiles the project automatically using its selected semantic layer format, so the merged change goes live without a manual refresh. If the change renamed or removed a field, the merge also kicks off the content-migration flow described in [Impact and safety checks](#impact-and-safety-checks).

<Note>
  Merging or closing a writeback PR from the card uses your project permissions
  on the connected repository. You need at least project **Developer** to act on
  PRs that don't target a protected branch — the same permission required to
  open a writeback PR in the first place. If the host refuses the merge (for
  example, branch protection blocks it or the head moved), the error is
  shown as a notification.
</Note>

## Impact and safety checks

For changes that could break existing content or change results, the agent does extra work around the pull request so you can review it with confidence.

**What the change would break.** When a change removes or renames a metric or dimension, saved charts, dashboards, dependent metrics, and scheduled deliveries may still reference the old field. After opening the pull request, the agent reports the impact in its reply — whether the change is breaking, how many items of each kind are affected, and a few of the most notable ones — or tells you it's safe when nothing references the field. This is advisory and never delays opening the PR; pure additions and description-only edits skip it.

**Repointing affected content after the merge.** When you merge a writeback PR that removed or renamed a field from the chat card, the merge asks the agent to plan a migration — you don't need to ask. The agent re-runs the impact analysis against the merged change, presents a plan in chat naming which charts and dashboards to repoint and to which replacement field, and once you confirm uses the content-editing tool to make the edits and reports back what it changed. If a removed field has no obvious replacement, the agent asks which field to point to rather than guessing. This flow needs [content editing](/agents/enable-content-tools) enabled on the agent; without it the impact is still reported, but repointing has to be done by someone with edit access. You can also ask the agent to plan the repoint before merging if you want to line up the changes first.

**That the numbers still hold.** When a change relies on results staying the same — consolidating two duplicate metrics, replacing one field with another, splitting a metric into parts, or refactoring a field's SQL — the agent proves it rather than asserting it. It either shows the guarantee from the model SQL, or runs the affected fields at a total and across a time dimension and confirms they match, before calling the change safe. If the numbers diverge, it tells you exactly what differs instead of shipping the change.

## Reading the project repository <a id="reading-the-dbt-repository" />

The agent can also read source files in your project repository to ground its answers and plan a writeback before opening a pull request. Use it to inspect a native model's `sql_from`, dimensions, or metrics, a dbt model's SQL and configuration, or the current contents of a file before asking for an edit.

For questions about what data exists, what a metric means, or whether two metrics overlap, the agent uses semantic-layer discovery tools. Repository access supplies the source definitions behind those fields.

### Requirements

* Repository reading is available for **GitHub** or **GitLab** connections with the matching Lightdash app installed. On GitLab, repository-wide code search isn't available, so the agent falls back to reading and searching within files it lists.
* The user asking the question needs the **view source code** permission on the project.
* In Slack, read access is only available when [AI Agents OAuth](/integrations/slack#ai-agents-configuration) is required, so the agent can evaluate permissions against the asking user.

### What the agent can see

* The agent starts in the configured project directory. Other repositories readable by your organization's Lightdash app installation (or your linked GitHub account) can also be browsed read-only on their default branch; secret and credential file paths are blocked.
* The agent can list directories, read files, and search for strings, but it cannot modify anything. To change a file, it still has to call `editDbtProject`.

Each repo command shows up as its own sub-step under a terminal icon, so you can see exactly what the agent looked at before answering or proposing a change.

## Automatic preview project

For pull requests opened against a **GitHub**-connected project, Lightdash builds a [preview project](/workflow/preview-projects) from the PR's branch as soon as the pull request is opened. You can use it to verify the agent's change against your data before merging — no GitHub Action or CI setup required in your repository.

When the preview is ready:

* The agent's reply in chat (or the writeback status on a review item) includes a **View preview** link to the preview project.
* A bot comment is posted on the pull request with the same preview URL.

The preview project uses the production project's connection and semantic layer format, with the branch overridden to the PR's head branch. Native projects compile their YAML directly; dbt projects use dbt. Lightdash builds the preview without requiring a preview-deploy GitHub Action in your repository.

If the preview can't be built — for example, the project isn't connected to GitHub, compilation fails on the PR branch, or the GitHub App can't reach the repo — the pull request is still opened and the agent reports the PR link without a preview. The writeback itself never fails because the preview failed.

## Iterating on an existing pull request

When you follow up on a change whose pull request is already open — either earlier in the same thread or one you pasted a link to — the agent commits onto that PR's branch instead of opening a new one, and refreshes its title and description to reflect the latest change.

* **Continue the current change.** A follow-up, fix, or refinement to a change you just asked for resumes its pull request automatically. You don't need to paste the link.
* **Ask for a separate change.** When your next request is unrelated to the open PR, the agent opens a new pull request for it rather than piling an unrelated commit onto the existing one, and tells you what went into which PR.
* **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, 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 theme={null}
Update https://github.com/my-org/analytics/pull/482 so the `net_revenue`
metric is rounded to 2 decimal places.
```

The pasted pull request must:

* Live in the same GitHub repository as the project's connection.
* Be **open** — merged or closed PRs are rejected.
* Have its branch in the same repository (PRs opened from forks are rejected).

If any of those checks fail, the agent stops and tells you why instead of silently opening a new pull request.

## What happens if it can't run

| Situation                                                             | Result                                                                                                                                               |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project has no supported repository connection                        | The agent explains which connection is required. See [Prerequisites](#prerequisites).                                                                |
| 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 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

* [AI coding agent](/agents/ai-coding-agent) — make changes in other connected repositories.
* [dbt write-back](/integrations/dbt/write-back) — write back individual custom metrics, dimensions, and SQL Runner queries from the Lightdash UI.
* [Lightdash YAML write-back](/semantic-layer/yaml#write-back-from-lightdash) — promote custom fields into native models.