Skip to content

docs: document data app promotion from preview to production #741

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Spissable merged 1 commit into from
Jun 2, 2026
Merged

docs: document data app promotion from preview to production #741

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions guides/data-apps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,26 @@ Personal apps stay tied to whoever created them until they're moved into a space
![Clean Shot 2026 04 29 At 18 39 56@2x](/images/CleanShot-2026-04-29-at-18.39.56@2x.png)
</Frame>

## Promoting an app

If you're building in a [preview project](/guides/developer/preview-projects), you can promote a data app into the preview's upstream (production) project once it's ready. This mirrors how chart and dashboard [promotion](/guides/how-to-promote-content) works: you iterate safely in preview, then push a snapshot to production.

To promote an app:

1. Open the app's **⋯** menu - either on the app card in a list, or in the chat header inside the app - and select **Promote**.
2. In the confirmation dialog, review whether the action will **create** a new production app or **update** the existing linked one, and which space it will land in.
3. Click **Promote**. When it finishes, you're taken to the promoted app in the production project.

The first promotion creates a new app in the upstream project and links the two together. Every later promotion of the same preview app appends a new version to that linked production app, so production keeps a clean history of what was promoted and when. The latest ready version in preview is what gets snapshotted - in-progress builds are skipped.

The app lands in a space that matches the source app's space by path. If no space with that path exists in the upstream project, Lightdash creates one. Personal apps (apps not in a space) are promoted as personal apps owned by the promoter.

To promote, you need:

- **Manage** access on the source data app in the preview project.
- **Create** permission for data apps in the upstream project.
- The preview project must have an upstream project configured under **Settings → Data ops**.

## Data context and the app model

Data apps don't ship with their own copy of your data. They run inside a sandboxed iframe with no direct access to the Lightdash API, so every query the app wants to run is proxied through the Lightdash UI hosting the iframe.
Expand Down
4 changes: 4 additions & 0 deletions guides/how-to-promote-content.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,3 +66,7 @@ If the dashboard or charts are in a space that doesn't exist in the upstream pro
</Frame>

Once the dashboard is promoted, you can click on the `success` banner to open a new tab into this dashboard in the `production project`.

## Promote data apps

You can also promote data apps from a preview project into their upstream project. See [Promoting an app](/guides/data-apps#promoting-an-app) in the data apps guide for details.
Loading