From d70fb96bd53c003d3061f5fdd32ef7150d243ade Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 26 May 2026 09:23:41 +0000 Subject: [PATCH 1/4] docs: add overview of the three ways to sync dbt with Lightdash --- references/integrations/dbt-projects.mdx | 45 ++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/references/integrations/dbt-projects.mdx b/references/integrations/dbt-projects.mdx index 920c2f31..3a5d9288 100644 --- a/references/integrations/dbt-projects.mdx +++ b/references/integrations/dbt-projects.mdx @@ -12,6 +12,51 @@ description: "You can easily make changes in dbt and see them updated in your Li You can sync your dbt project code with Lightdash in a few different ways. We recommend everyone set up continuous deployment, but you can also refresh in the Lightdash app or deploy from the CLI. +### Ways to sync dbt to Lightdash + +There are three mechanisms to sync dbt with Lightdash. They aren't really alternatives — they're different triggers — but they do differ in **where the dbt code comes from**, **where compilation happens**, and **which `profiles.yml` / target wins**. + + + + - **Where code comes from:** the developer's local working copy (uncommitted changes included). + - **Where compile happens:** locally on the laptop. The CLI runs `dbt compile` under the hood, then ships the resulting `manifest.json` to Lightdash. + - **Which `profiles.yml`:** local one (`~/.dbt/profiles.yml` by default, or `--profiles-dir`). + - **Which target:** default in that `profiles.yml`, unless overridden with `--target`. + - **Trigger:** a developer runs the command. + - **Use case:** initial setup, debugging, and one-off "rebel" deploys. Not recommended ongoing — it bypasses PR review and can lead to production issues. + + + + - **Where code comes from:** Lightdash fetches it from the source configured in **Project Settings → dbt Connection** (GitHub, GitLab, Azure DevOps, Bitbucket, or dbt Cloud), at the branch specified there (typically `main`). + - **Where compile happens:** server-side, on Lightdash's infrastructure. + - **Which `profiles.yml`:** Lightdash synthesises one from the project's **UI Connection Settings** (warehouse type + credentials). + - **Which target:** the **Target name** field in **Project Settings → Connection Settings**. + - **Trigger:** a user clicks **Refresh dbt** in the UI. + - **Use case:** pulling the latest merged state into Lightdash without touching CI. Anyone with the right permissions can do it. + + + + - **Where code comes from:** the GitHub Action's checkout of the repo (so whatever branch the workflow runs against — usually `main`). + - **Where compile happens:** inside the GitHub Action runner. Same mechanics as the laptop CLI, just on a CI box. + - **Which `profiles.yml`:** whatever the action provides — either a committed `profiles.yml` in the repo (with `DBT_PROFILES_DIR` pointing at it) or a templated one generated at workflow runtime from GitHub Secrets. + - **Which target:** default in that `profiles.yml`, unless overridden with `--target`. + - **Trigger:** `on: push: branches: [main]` typically, or `workflow_dispatch` for manual runs. + - **Use case:** automated production deploys gated by PR merge. This is the recommended pattern. + + + +#### Side-by-side comparison + +| | CLI from laptop | UI "Refresh dbt" | GitHub Action | +| ------------------------ | ------------------------------------------ | ----------------------------------------- | -------------------------------------- | +| **dbt code source** | Local working copy | Lightdash fetches from git source | CI runner checkout of repo | +| **Compile location** | Laptop | Lightdash servers | CI runner | +| **`profiles.yml` source**| Local (`~/.dbt/`) | Synthesised from UI Connection Settings | Repo / CI secrets | +| **Target controlled by** | Default in local profile, or `--target` | UI Target name field | Default in CI profile, or `--target` | +| **PR review gate** | No | No | Yes (if `main`-only trigger) | +| **Who can trigger** | Anyone with the CLI + API key | Anyone with refresh permission | Anyone who can merge to `main` | +| **Recommended for** | Initial setup / debugging | Quick UI refresh after merge | Production deploys | + ### 1. Set up continuous deployment [Read how to do that and check out our example workflow files](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action). From 8b26646ff3330c62d2136499296402761212c5ed Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 26 May 2026 09:41:15 +0000 Subject: [PATCH 2/4] docs: expand dbt sync section to five mechanisms with decision matrix --- references/integrations/dbt-projects.mdx | 202 ++++++++++++++++++----- 1 file changed, 160 insertions(+), 42 deletions(-) diff --git a/references/integrations/dbt-projects.mdx b/references/integrations/dbt-projects.mdx index 3a5d9288..44e6a097 100644 --- a/references/integrations/dbt-projects.mdx +++ b/references/integrations/dbt-projects.mdx @@ -8,74 +8,188 @@ description: "You can easily make changes in dbt and see them updated in your Li Lightdash supports dbt v1.4.0 and above. If you are using an older version of dbt, you will need to upgrade to sync your project to Lightdash. -## Syncing your dbt project to Lightdash +## Syncing your dbt project to Lightdash -You can sync your dbt project code with Lightdash in a few different ways. We recommend everyone set up continuous deployment, but you can also refresh in the Lightdash app or deploy from the CLI. +There are five ways to sync changes from dbt into Lightdash. They differ in **where the code comes from**, **where compilation happens**, **which `profiles.yml` / target governs the result**, and **whether they respect the project's UI Connection Settings**. -### Ways to sync dbt to Lightdash +For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://github.com/lightdash/cli-actions) repo. -There are three mechanisms to sync dbt with Lightdash. They aren't really alternatives — they're different triggers — but they do differ in **where the dbt code comes from**, **where compilation happens**, and **which `profiles.yml` / target wins**. +### Sync mechanisms - - - **Where code comes from:** the developer's local working copy (uncommitted changes included). - - **Where compile happens:** locally on the laptop. The CLI runs `dbt compile` under the hood, then ships the resulting `manifest.json` to Lightdash. - - **Which `profiles.yml`:** local one (`~/.dbt/profiles.yml` by default, or `--profiles-dir`). - - **Which target:** default in that `profiles.yml`, unless overridden with `--target`. - - **Trigger:** a developer runs the command. - - **Use case:** initial setup, debugging, and one-off "rebel" deploys. Not recommended ongoing — it bypasses PR review and can lead to production issues. + + Compiles the dbt project locally and pushes the resulting `manifest.json` to Lightdash. + + | Property | Value | + | ------------------------------------- | --------------------------------------------------------------------------- | + | dbt code source | Local working copy (uncommitted changes included) | + | Compile location | Laptop | + | `profiles.yml` source | Local (`~/.dbt/profiles.yml` by default, or `--profiles-dir`) | + | Target | Default in that `profiles.yml`, overridden by `--target` | + | UI Connection Settings respected? | No | + | Auth | `lightdash login` session or `LIGHTDASH_API_KEY` env var | + | Prerequisites | Lightdash CLI installed; dbt installed; warehouse creds reachable locally | + | Remote git connection required? | No | + + **Use cases:** initial project setup, debugging, one-off manual deploys. + + **Trade-offs:** bypasses PR review; relies on per-developer `profiles.yml`; high footgun risk if a developer's prod target accidentally points at a non-prod warehouse. - - - **Where code comes from:** Lightdash fetches it from the source configured in **Project Settings → dbt Connection** (GitHub, GitLab, Azure DevOps, Bitbucket, or dbt Cloud), at the branch specified there (typically `main`). - - **Where compile happens:** server-side, on Lightdash's infrastructure. - - **Which `profiles.yml`:** Lightdash synthesises one from the project's **UI Connection Settings** (warehouse type + credentials). - - **Which target:** the **Target name** field in **Project Settings → Connection Settings**. - - **Trigger:** a user clicks **Refresh dbt** in the UI. - - **Use case:** pulling the latest merged state into Lightdash without touching CI. Anyone with the right permissions can do it. + + Same as #1, but runs inside a CI workflow with credentials stored as GitHub Secrets. + + | Property | Value | + | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | + | dbt code source | CI runner's checkout of the repo | + | Compile location | CI runner | + | `profiles.yml` source | Provided by the workflow — either committed as an `env_var()` template, or written to disk from a GitHub Secret at runtime | + | Target | Default in the CI `profiles.yml`, overridden by `--target` | + | UI Connection Settings respected? | No | + | Auth | `LIGHTDASH_API_KEY` from GitHub Secrets | + | Prerequisites | Lightdash CLI + dbt installed in the workflow; warehouse creds available to CI; valid `profiles.yml` produced at runtime | + | Remote git connection required? | No | + | Workflow template | [`deploy.yml`](https://github.com/lightdash/cli-actions) in `lightdash/cli-actions` | + + **Use cases:** automated production deploys gated by PR merge; PR preview workflows (`lightdash start-preview` + `lightdash validate`). + + **Trade-offs:** requires duplicating warehouse credentials into CI on top of what's already in Lightdash; needs dbt available in the runner. + + + Never commit a `profiles.yml` with plaintext credentials. Either use an `env_var()` template committed to the repo, or write the file to disk at runtime from a GitHub Secret. + - - - **Where code comes from:** the GitHub Action's checkout of the repo (so whatever branch the workflow runs against — usually `main`). - - **Where compile happens:** inside the GitHub Action runner. Same mechanics as the laptop CLI, just on a CI box. - - **Which `profiles.yml`:** whatever the action provides — either a committed `profiles.yml` in the repo (with `DBT_PROFILES_DIR` pointing at it) or a templated one generated at workflow runtime from GitHub Secrets. - - **Which target:** default in that `profiles.yml`, unless overridden with `--target`. - - **Trigger:** `on: push: branches: [main]` typically, or `workflow_dispatch` for manual runs. - - **Use case:** automated production deploys gated by PR merge. This is the recommended pattern. + + Lightdash fetches the dbt code from the configured remote, compiles it server-side, and updates the project. + + | Property | Value | + | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | + | dbt code source | Lightdash pulls from the remote git source configured in Project Settings (GitHub, GitLab, Azure DevOps, Bitbucket, dbt Cloud) | + | Compile location | Lightdash servers | + | `profiles.yml` source | Lightdash synthesises one from Project Settings → Connection Settings | + | Target | UI Project Settings → Connection Settings → Target name | + | UI Connection Settings respected? | Yes | + | Auth | Logged-in user in the UI | + | Prerequisites | Project must have a remote git source connected | + | Remote git connection required? | Yes | + + **Use cases:** ad-hoc refresh after a merge; quick UI-driven sync without leaving the browser. + + **Trade-offs:** manual; relies on a human remembering to click it. + + + + Calls the same endpoint as the "Refresh dbt" button, but programmatically from CI. Lightdash does the work server-side using the project's UI Connection Settings. + + | Property | Value | + | ------------------------------------- | ------------------------------------------------------------------------------------------- | + | dbt code source | Lightdash pulls from the remote git source (configured in Project Settings) | + | Compile location | Lightdash servers | + | `profiles.yml` source | Synthesised by Lightdash from UI Connection Settings | + | Target | UI Project Settings → Connection Settings → Target name | + | UI Connection Settings respected? | Yes | + | Auth | `LIGHTDASH_API_KEY` from GitHub Secrets | + | Prerequisites | Project must have a remote git source connected; Lightdash CLI installed in the workflow | + | Remote git connection required? | Yes | + | Workflow template | [`refresh.yml`](https://github.com/lightdash/cli-actions) in `lightdash/cli-actions` | + + **Use cases:** automated post-merge sync to production when the project is already git-connected. + + **Trade-offs:** can't push uncommitted changes (only what's in the connected branch); won't catch issues pre-merge — pair with a separate `lightdash validate` PR workflow if you want that. + + + + Same as #4, but bypasses the Lightdash CLI entirely — just a `curl` to the API. + + | Property | Value | + | ------------------------------------- | --------------------------------------------------------------------------- | + | dbt code source | Lightdash pulls from the remote git source (configured in Project Settings) | + | Compile location | Lightdash servers | + | `profiles.yml` source | Synthesised by Lightdash from UI Connection Settings | + | Target | UI Project Settings → Connection Settings → Target name | + | UI Connection Settings respected? | Yes | + | Auth | `LIGHTDASH_API_KEY` from GitHub Secrets | + | Prerequisites | Project must have a remote git source connected | + | Remote git connection required? | Yes | + | Lightdash CLI required? | No | + | Endpoint | `POST /api/v1/projects/{projectUuid}/refresh` | + + **Use cases:** the simplest possible automated refresh — no dependencies to install. Useful for teams who don't want a Node toolchain in CI. + + **Trade-offs:** same as #4. The refresh is async (returns a `jobUuid`); for stronger guarantees, poll `GET /api/v1/jobs/{jobUuid}` to confirm completion before exiting the workflow. -#### Side-by-side comparison +### Decision matrix + +| | #1 CLI laptop | #2 CLI in CI | #3 UI button | #4 `refresh` in CI | #5 refresh API in CI | +| ------------------------------------- | ------------------------------- | ---------------------------------- | ------------------ | ----------------------------- | ------------------------------ | +| Automated? | No | Yes | No | Yes | Yes | +| Pushes uncommitted local changes? | Yes | No | No | No | No | +| Needs dbt + warehouse creds in CI? | N/A | Yes | No | No | No | +| Needs Lightdash CLI installed? | Yes | Yes | No | Yes | No | +| Respects UI Target name? | No | No | Yes | Yes | Yes | +| Works without a remote git connection?| Yes | Yes | No | No | No | +| Catches breaking changes pre-merge? | With `--select` + `validate` | If used in a PR workflow | No | No | No | +| Best for | Initial setup, debugging | PR previews; CI deploys with no remote git connection | Ad-hoc UI refresh | Post-merge sync (recommended) | Post-merge sync, minimal-CI shops | + +### Recommended setups + +**Most teams** (Lightdash connected to GitHub, GitLab, Azure DevOps, Bitbucket, or dbt Cloud): + +- **PR workflow** → `lightdash start-preview` + `lightdash validate` (mechanism #2 with `start-preview`) +- **Post-merge to `main`** → `lightdash refresh` (#4) or the refresh API (#5) +- **Manual UI refresh** (#3) available for ad-hoc syncs + +**Teams without a remote git connection** (project loaded via local CLI only): -| | CLI from laptop | UI "Refresh dbt" | GitHub Action | -| ------------------------ | ------------------------------------------ | ----------------------------------------- | -------------------------------------- | -| **dbt code source** | Local working copy | Lightdash fetches from git source | CI runner checkout of repo | -| **Compile location** | Laptop | Lightdash servers | CI runner | -| **`profiles.yml` source**| Local (`~/.dbt/`) | Synthesised from UI Connection Settings | Repo / CI secrets | -| **Target controlled by** | Default in local profile, or `--target` | UI Target name field | Default in CI profile, or `--target` | -| **PR review gate** | No | No | Yes (if `main`-only trigger) | -| **Who can trigger** | Anyone with the CLI + API key | Anyone with refresh permission | Anyone who can merge to `main` | -| **Recommended for** | Initial setup / debugging | Quick UI refresh after merge | Production deploys | +- **Production sync** → `lightdash deploy` in GitHub Actions (#2) +- **Previews** → `lightdash start-preview` in GitHub Actions -### 1. Set up continuous deployment +**Teams just getting started:** -[Read how to do that and check out our example workflow files](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action). +- Local `lightdash deploy` (#1) for first-time setup, then graduate to one of the automated patterns above as soon as the project is stable. -### 2. Click "Refresh dbt" in Lightdash +### Things to know -The button can be found on the Query from tables page. + + **`lightdash deploy` does NOT use the UI "Target name" setting.** It uses the local `profiles.yml` default, or whatever `--target` overrides it with. Only mechanisms #3, #4, and #5 respect the UI Target name. + + + + **`lightdash refresh` requires a remote git connection.** It will fail with a `ParameterError` if the project's `dbtConnection.type` is `NONE`. + + + + **Refresh is async.** Both #4 and #5 return a `jobUuid` and the work continues server-side. If your CI needs to know the refresh succeeded, poll `GET /api/v1/jobs/{jobUuid}` before exiting the workflow. + + + + **Never commit `profiles.yml` with credentials.** For mechanism #2, use either a secret-written-to-file approach or an `env_var()` template — but never check in plaintext credentials. + + + + Mechanisms #4 and #5 are underused. Most existing GitHub Actions examples lead with `lightdash deploy`, which is the heaviest option in CI (requires dbt + warehouse credentials duplicated into the runner). The refresh-based patterns are simpler and often a better fit when the project is git-connected. + + +### How to trigger each sync + +#### Click "Refresh dbt" in Lightdash + +The button can be found on the Query from tables page. ![screenshot-refresh-dbt](/images/references/integrations/dbt-projects/dbt-refresh.png) -_If you're using a git connection (like GitHub, Gitlab or Bitbucket), you'll need to push + merge your changes to the branch that your Lightdash project is connected to before you press `Refresh dbt`._ +_If you're using a git connection (like GitHub, GitLab, or Bitbucket), you'll need to push + merge your changes to the branch that your Lightdash project is connected to before you press `Refresh dbt`._ -If you've made any changes to the underlying data (for example, adding a new column in your `model.sql` file or changing the SQL logic of a dimension), then you need to run: `dbt run -m yourmodel` before you click `Refresh dbt` in Lightdash. +If you've made any changes to the underlying data (for example, adding a new column in your `model.sql` file or changing the SQL logic of a dimension), then you need to run `dbt run -m yourmodel` before you click `Refresh dbt` in Lightdash. -### 3. Push code from the CLI +#### Push code from the CLI If you're using the [Lightdash CLI](/guides/cli/how-to-install-the-lightdash-cli), you can use `lightdash deploy` to deploy your changes to Lightdash. [Read more about how to use `lightdash deploy`](/guides/cli/how-to-use-lightdash-deploy). @@ -83,6 +197,10 @@ If you're using the [Lightdash CLI](/guides/cli/how-to-install-the-lightdash-cli We don't recommend using `lightdash deploy` from your local environment as the primary way you update Lightdash since small mistakes can lead to production issues. +#### Set up continuous deployment + +[Read how to do that and check out our example workflow files](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action). + ## dbt project settings For more information about dbt connection types (Github, Gitlab, Bitbucket, etc.) and the fields required for each type, [read the dbt project section in our connection guide](/get-started/setup-lightdash/connect-project#2-import-a-dbt-project). From c2a46adba0565e6007fd894379830c5e64de4633 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 26 May 2026 09:52:26 +0000 Subject: [PATCH 3/4] docs: make dbt sync decision matrix headers explicit with commands --- references/integrations/dbt-projects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/references/integrations/dbt-projects.mdx b/references/integrations/dbt-projects.mdx index 44e6a097..7b6ae923 100644 --- a/references/integrations/dbt-projects.mdx +++ b/references/integrations/dbt-projects.mdx @@ -123,7 +123,7 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g ### Decision matrix -| | #1 CLI laptop | #2 CLI in CI | #3 UI button | #4 `refresh` in CI | #5 refresh API in CI | +| | #1 `lightdash deploy` — local CLI | #2 `lightdash deploy` — GitHub Action | #3 "Refresh dbt" — UI button | #4 `lightdash refresh` — GitHub Action | #5 `POST /refresh` API — GitHub Action | | ------------------------------------- | ------------------------------- | ---------------------------------- | ------------------ | ----------------------------- | ------------------------------ | | Automated? | No | Yes | No | Yes | Yes | | Pushes uncommitted local changes? | Yes | No | No | No | No | From c73ba5e24c9b47b843887299bc0ac24b88564a29 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 26 May 2026 09:55:59 +0000 Subject: [PATCH 4/4] docs: generalize GitHub Action references to CI in dbt sync section --- references/integrations/dbt-projects.mdx | 34 ++++++++++++------------ 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/references/integrations/dbt-projects.mdx b/references/integrations/dbt-projects.mdx index 7b6ae923..cbedc673 100644 --- a/references/integrations/dbt-projects.mdx +++ b/references/integrations/dbt-projects.mdx @@ -36,27 +36,27 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g **Trade-offs:** bypasses PR review; relies on per-developer `profiles.yml`; high footgun risk if a developer's prod target accidentally points at a non-prod warehouse. - - Same as #1, but runs inside a CI workflow with credentials stored as GitHub Secrets. + + Same as #1, but runs inside a CI workflow (GitHub Actions, GitLab CI, Azure Pipelines, Bitbucket Pipelines, etc.) with credentials stored as CI secrets. | Property | Value | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | dbt code source | CI runner's checkout of the repo | | Compile location | CI runner | - | `profiles.yml` source | Provided by the workflow — either committed as an `env_var()` template, or written to disk from a GitHub Secret at runtime | + | `profiles.yml` source | Provided by the workflow — either committed as an `env_var()` template, or written to disk from a CI secret at runtime | | Target | Default in the CI `profiles.yml`, overridden by `--target` | | UI Connection Settings respected? | No | - | Auth | `LIGHTDASH_API_KEY` from GitHub Secrets | + | Auth | `LIGHTDASH_API_KEY` from CI secrets | | Prerequisites | Lightdash CLI + dbt installed in the workflow; warehouse creds available to CI; valid `profiles.yml` produced at runtime | | Remote git connection required? | No | - | Workflow template | [`deploy.yml`](https://github.com/lightdash/cli-actions) in `lightdash/cli-actions` | + | Workflow template | [`deploy.yml`](https://github.com/lightdash/cli-actions) in `lightdash/cli-actions` (GitHub Actions example) | **Use cases:** automated production deploys gated by PR merge; PR preview workflows (`lightdash start-preview` + `lightdash validate`). **Trade-offs:** requires duplicating warehouse credentials into CI on top of what's already in Lightdash; needs dbt available in the runner. - Never commit a `profiles.yml` with plaintext credentials. Either use an `env_var()` template committed to the repo, or write the file to disk at runtime from a GitHub Secret. + Never commit a `profiles.yml` with plaintext credentials. Either use an `env_var()` template committed to the repo, or write the file to disk at runtime from a CI secret. @@ -79,8 +79,8 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g **Trade-offs:** manual; relies on a human remembering to click it. - - Calls the same endpoint as the "Refresh dbt" button, but programmatically from CI. Lightdash does the work server-side using the project's UI Connection Settings. + + Calls the same endpoint as the "Refresh dbt" button, but programmatically from CI (GitHub Actions, GitLab CI, Azure Pipelines, Bitbucket Pipelines, etc.). Lightdash does the work server-side using the project's UI Connection Settings. | Property | Value | | ------------------------------------- | ------------------------------------------------------------------------------------------- | @@ -89,18 +89,18 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g | `profiles.yml` source | Synthesised by Lightdash from UI Connection Settings | | Target | UI Project Settings → Connection Settings → Target name | | UI Connection Settings respected? | Yes | - | Auth | `LIGHTDASH_API_KEY` from GitHub Secrets | + | Auth | `LIGHTDASH_API_KEY` from CI secrets | | Prerequisites | Project must have a remote git source connected; Lightdash CLI installed in the workflow | | Remote git connection required? | Yes | - | Workflow template | [`refresh.yml`](https://github.com/lightdash/cli-actions) in `lightdash/cli-actions` | + | Workflow template | [`refresh.yml`](https://github.com/lightdash/cli-actions) in `lightdash/cli-actions` (GitHub Actions example) | **Use cases:** automated post-merge sync to production when the project is already git-connected. **Trade-offs:** can't push uncommitted changes (only what's in the connected branch); won't catch issues pre-merge — pair with a separate `lightdash validate` PR workflow if you want that. - - Same as #4, but bypasses the Lightdash CLI entirely — just a `curl` to the API. + + Same as #4, but bypasses the Lightdash CLI entirely — just a `curl` to the API. Works from any CI system (GitHub Actions, GitLab CI, Azure Pipelines, Bitbucket Pipelines, etc.). | Property | Value | | ------------------------------------- | --------------------------------------------------------------------------- | @@ -109,7 +109,7 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g | `profiles.yml` source | Synthesised by Lightdash from UI Connection Settings | | Target | UI Project Settings → Connection Settings → Target name | | UI Connection Settings respected? | Yes | - | Auth | `LIGHTDASH_API_KEY` from GitHub Secrets | + | Auth | `LIGHTDASH_API_KEY` from CI secrets | | Prerequisites | Project must have a remote git source connected | | Remote git connection required? | Yes | | Lightdash CLI required? | No | @@ -123,7 +123,7 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g ### Decision matrix -| | #1 `lightdash deploy` — local CLI | #2 `lightdash deploy` — GitHub Action | #3 "Refresh dbt" — UI button | #4 `lightdash refresh` — GitHub Action | #5 `POST /refresh` API — GitHub Action | +| | #1 `lightdash deploy` — local CLI | #2 `lightdash deploy` — CI | #3 "Refresh dbt" — UI button | #4 `lightdash refresh` — CI | #5 `POST /refresh` API — CI | | ------------------------------------- | ------------------------------- | ---------------------------------- | ------------------ | ----------------------------- | ------------------------------ | | Automated? | No | Yes | No | Yes | Yes | | Pushes uncommitted local changes? | Yes | No | No | No | No | @@ -144,8 +144,8 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g **Teams without a remote git connection** (project loaded via local CLI only): -- **Production sync** → `lightdash deploy` in GitHub Actions (#2) -- **Previews** → `lightdash start-preview` in GitHub Actions +- **Production sync** → `lightdash deploy` in CI (#2) +- **Previews** → `lightdash start-preview` in CI **Teams just getting started:** @@ -170,7 +170,7 @@ For ready-to-use workflow templates, see the [`lightdash/cli-actions`](https://g - Mechanisms #4 and #5 are underused. Most existing GitHub Actions examples lead with `lightdash deploy`, which is the heaviest option in CI (requires dbt + warehouse credentials duplicated into the runner). The refresh-based patterns are simpler and often a better fit when the project is git-connected. + Mechanisms #4 and #5 are underused. Most existing CI examples lead with `lightdash deploy`, which is the heaviest option in CI (requires dbt + warehouse credentials duplicated into the runner). The refresh-based patterns are simpler and often a better fit when the project is git-connected. ### How to trigger each sync