Skip to content
Merged
Changes from all commits
Commits
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
16 changes: 8 additions & 8 deletions guides/developer/dashboards-as-code.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,11 @@ There are two main approaches to working with dashboards as code. You can mix an
| **Setup complexity** | Minimal — just the CLI | Requires CI/CD and space permissions |
| **Best for** | Quick edits, AI-assisted changes, ad-hoc updates | Regulated environments, multi-instance deployments, teams that want strict change control |

## Disposable editing (recommended)
### Disposable editing (recommended)

When using dashboards as code with AI agents or CLI tools, we recommend treating the downloaded files as **temporary working files** rather than a permanent source of truth. This is the best starting point for most teams.

### The disposable workflow
#### The disposable workflow

1. **Download** the content you want to edit using `lightdash download`
2. **Make your changes** locally (manually or with AI assistance)
Expand All @@ -29,27 +29,27 @@ When using dashboards as code with AI agents or CLI tools, we recommend treating

This approach keeps the Lightdash application as your source of truth while still enabling powerful code-based editing workflows.

### Why disposable?
#### Why disposable?

Treating dashboards as code as disposable config files provides flexibility:

- **UI changes remain easy** — team members can continue making updates directly in the Lightdash UI without needing to sync a codebase
- **No repository maintenance** — you avoid the overhead of keeping code files synchronized with UI changes
- **Best of both worlds** — you get the power of code-based editing and AI assistance without the rigidity of a code-first workflow

## Git-managed dashboards
### Git-managed dashboards

An alternative approach where your **Git repository is the single source of truth** for charts and dashboards. All changes flow through version control, and the UI is read-only for managed content.

### When to use this workflow
#### When to use this workflow

- You want a full audit trail of every dashboard change via Git history
- You want to enforce review processes (pull requests, approvals) before changes reach production
- You're comfortable with all edits happening in code rather than the UI
- You want to validate dashboard changes in [preview environments](/guides/developer/preview-projects) before merging
- You're deploying the same content across multiple Lightdash instances

### Lock down the UI
#### Lock down the UI

For this workflow to succeed, you need to prevent ad-hoc UI edits from drifting out of sync with your repository. Use **space permissions** to enforce this:

Expand All @@ -58,7 +58,7 @@ For this workflow to succeed, you need to prevent ad-hoc UI edits from drifting

You don't have to manage everything this way. Organize code-managed content into specific spaces with restricted permissions, and leave other spaces open for UI editing.

### Making changes
#### Making changes

The typical workflow for editing Git-managed dashboards:

Expand All @@ -69,7 +69,7 @@ The typical workflow for editing Git-managed dashboards:
5. **Open a pull request** — once the changes look good in the preview, commit and open a PR for review
6. **Merge and deploy** — on merge to your main branch, a CI job runs `lightdash deploy` and `lightdash upload --force` to push changes to production

### CI/CD setup
#### CI/CD setup

To fully automate this workflow, set up two CI jobs:

Expand Down
Loading