From 02160160afc246510f3ca4dd475ae6bcac554f64 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 1 Jun 2026 19:08:47 +0000
Subject: [PATCH] docs: note AI writeback offers preview-deploy workflow setup

---
 guides/ai-agents/ai-writeback.mdx | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/guides/ai-agents/ai-writeback.mdx b/guides/ai-agents/ai-writeback.mdx
index 986e274f..83a9382a 100644
--- a/guides/ai-agents/ai-writeback.mdx
+++ b/guides/ai-agents/ai-writeback.mdx
@@ -82,6 +82,26 @@ Make the orders model better.
 
 When the pull request is ready, the agent posts the URL in the thread. Open it, review the diff, and merge as you would any other pull request. After merging, refresh dbt in Lightdash (or let your CI/CD do it) so the change takes effect.
 
+## Offering to set up preview deploys
+
+While the writeback agent has your repository cloned, it also checks whether the repo already deploys [Lightdash preview projects](/guides/developer/preview-projects) on pull requests via GitHub Actions.
+
+If it doesn't find a preview-deploy workflow, the agent will — after handling your main request — offer to open a second pull request that adds the canonical workflow pair:
+
+- `.github/workflows/start-preview.yml` — runs `lightdash start-preview` on each pull request to create a preview project.
+- `.github/workflows/close-preview.yml` — runs `lightdash stop-preview` when the pull request closes.
+
+The agent only creates these files if you agree. Once the pull request is merged, you need to add four GitHub Actions repository secrets for the workflow to run:
+
+| Secret | What it is |
+| --- | --- |
+| `LIGHTDASH_URL` | The base URL of your Lightdash instance. The agent pre-fills this. |
+| `LIGHTDASH_PROJECT` | The UUID of the Lightdash project to base previews on. The agent pre-fills this. |
+| `LIGHTDASH_API_KEY` | A Lightdash [personal access token](/references/workspace/personal-tokens). You must add this yourself. |
+| `DBT_PROFILES` | The contents of a `profiles.yml` with your warehouse connection. You must add this yourself — Lightdash never stores your warehouse password. |
+
+Repos that already have a preview-deploy workflow are skipped, and the offer never blocks or delays your main writeback request. See [Preview projects](/guides/developer/preview-projects#pull-requests-github-actions) and [`lightdash preview`](/guides/cli/how-to-use-lightdash-preview#set-up-developer-previews-on-your-pull-requests) for the full manual setup.
+
 ## What happens if it can't run
 
 | Situation | Result |