Skip to content

docs: document download-only content-as-code scope #724

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
jesshitchcock merged 4 commits into from
Jun 9, 2026
Merged

docs: document download-only content-as-code scope #724

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2edb6e5
docs: document download-only content-as-code scope for editors
mintlify[bot] May 29, 2026
3033b95
docs: document manage:ContentAsCode@self scope for own-preview uploads
mintlify[bot] Jun 9, 2026
8e10c2e
docs: expand agentic development workflow for content-as-code scopes
mintlify[bot] Jun 9, 2026
28c38b7
docs: mention UI promote-content as alternative prod promotion path
mintlify[bot] Jun 9, 2026
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
33 changes: 33 additions & 0 deletions references/workspace/custom-roles.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,39 @@ Custom roles are assigned at the project level to provide granular access contro

## Scope reference

### Content-as-code scopes

Three scopes control access to [content as code](/guides/developer/dashboards-as-code), the CLI workflow for managing charts and dashboards as YAML files. They form a read → write → narrow-write ladder.

**Download content as code** (`view:ContentAsCode`) lets a user pull existing charts and dashboards as YAML via `lightdash download`. It does not allow pushing changes back. This is the common "let people pull templates" grant.

**Upload content as code to own previews** (`manage:ContentAsCode@self`) is a narrow upload right: users can run `lightdash upload` only against preview projects they created themselves. This is the intended day-to-day scope for non-Developer users in CI/CD-style workflows where they need to validate their own preview but shouldn't push to shared projects. Pair it with `view:ContentAsCode` so they can still pull from shared projects.

**Download and upload content as code** (`manage:ContentAsCode`) grants both download and upload across any project the role applies to. Users with this scope can run `lightdash upload` to overwrite charts and dashboards in the project. This implies `view:ContentAsCode` and the `@self` upload right.

Use **download-only** to let a user pull production YAML for local development, diffing, or inspection without giving them the ability to overwrite production content. Combine with a controlled promotion path (e.g., CI/CD running with a service account that holds the manage scope) so writes only land via the pipeline.

#### Restrict developers to preview uploads (agentic development workflow)

A common pattern for agentic development of dashboards and content as code is to let developers iterate freely on their own preview projects while preventing direct `lightdash upload` to production. Promotion to production then happens through a reviewed CI/CD pipeline instead of an individual's CLI, or through [promoting content](/guides/how-to-promote-content) in the UI.

To set this up:

1. **Clone the built-in Developer role** to create a custom role (for example, `Developer (no prod upload)`).
2. **Remove** the **Download and upload content as code** (`manage:ContentAsCode`) scope from the cloned role.
3. **Add** the **Download content as code** (`view:ContentAsCode`) and **Upload content as code to own previews** (`manage:ContentAsCode@self`) scopes.
4. **Assign the custom role to the user at the project level** on the production project.

<Warning>
Custom project roles can only narrow scopes the user would otherwise inherit. If the user is an **Organization Admin** or **Organization Developer**, they will inherit `manage:ContentAsCode` from their org role and the project-level custom role will not block them. For this pattern to work, the user's organization role must be **Viewer**, **Interactive Viewer**, or **Member**.
</Warning>

With this setup, the user can:

- Run `lightdash download` against the production project to pull YAML for local editing.
- Run `lightdash preview` and `lightdash upload` against their own preview projects to validate changes.
- Receive a `403` when attempting `lightdash upload` against the production project — production writes must go through the promotion pipeline.

### SQL-related scopes

Three scopes control different SQL-authoring features. They are independent — granting one does not grant the others.
Expand Down
6 changes: 4 additions & 2 deletions references/workspace/roles.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ Project Admins can invite users to their project and assign users or [groups](/r
| Manage project access and permissions | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Delete project | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Create a preview project | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Use dashboards as code (CLI) | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Download content as code (CLI) | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Upload content as code (CLI) | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Rename models, dimensions, and metrics (CLI and UI) | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |


Expand All @@ -54,7 +55,8 @@ Organization Admins can assign roles to organization members, which gives access
| Admin for **all** projects | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Invite users to organization | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Manage organization access and permissions | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Use dashboards as code (CLI) | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Download content as code (CLI) | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Upload content as code (CLI) | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |
| Rename models, dimensions, and metrics (CLI and UI) | <Icon icon="square-check" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> |


Expand Down
Loading