Adding dbt cloud connection type (#233)

* adding dbt cloud connection type

* adding clarifcation points and link to previews

Author: oli-rmsy

get-started/setup-lightdash/connect-project.mdx

@@ -5,7 +5,7 @@ title: "Update your project connection"
 To setup your Lightdash connection you'll need to:
 
 1. [Connect to your data warehouse](/get-started/setup-lightdash/connect-project#1-connect-to-a-warehouse)
-2. [Connect to your dbt project](/get-started/setup-lightdash/connect-project#3-import-a-dbt-project)
+2. [Connect to your dbt project](/get-started/setup-lightdash/connect-project#2-import-a-dbt-project)
 
 <Tip>
   You can see a list of every time your project is compiled by visiting the [project compilation history](/references/project-compilation-history) page.
@@ -661,6 +661,18 @@ This controls what day is the start of the week in Lightdash. `Auto` sets it to
 
 Connecting Lightdash to a hosted dbt project means that you'll be able to keep your Lightdash instance in sync with the changes in your dbt project.
 
+The most common way to connect to dbt is to connect to a git repository where your dbt project is hosted. You can also connect directly using the CLI, or using the dbt Cloud connection type which leverages the dbt Cloud API.
+
+<Accordion title="I'm using dbt Cloud, should I connect using my git repository or through dbt Cloud?">
+
+Generally, **we recommend connecting via git repository for most users**, unless you specifically need to use features that are only available when connecting via dbt Cloud.
+
+For example, if you are using [cross project references](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) in dbt Cloud, you'll *need* to use that connection type, or Lightdash won't be able to compile your projects.
+
+If you connect via git repository, you need to make sure that your environment version in dbt Cloud is set to ['Compatible'](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks).
+
+</Accordion>
+
 To connect your dbt project, head to your project connection settings in Lightdash:
 
 <Frame>
@@ -685,6 +697,8 @@ Pick your repository type and follow the guide below:
 
   <Card title="Bitbucket" href="#bitbucket" />
 
+  <Card title="dbt Cloud" href="#dbt-cloud" />
+
   <Card title="CLI" href="#cli" />
 
 </CardGroup>
@@ -891,7 +905,34 @@ If you've [customized the domain for your Bitbucket server](https://confluence.a
 
 ***
 
-### CLI 
+### dbt Cloud
+
+The dbt Cloud connection type bypasses any git connection, instead directly accessing metadata from your dbt Cloud project using the dbt Cloud API.
+
+This means a number of features are **not** available, including:
+* [dbt write-back features](/references/dbt-write-back)
+* [Preview environments](https://docs.lightdash.com/references/preview-projects#lightdash-app) created in the UI from git branches
+* Automatic refreshes on new commits to your git repo - you'll need to manually trigger refreshes in Lightdash when you make changes to your dbt project.
+
+##### Service Token
+
+To connect Lightdash to your dbt Cloud project, you'll need to create a [dbt Cloud service token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) with the 'Metadata Only' permission.
+
+##### Environment ID
+
+This is the identifier for your dbt Cloud environment. You can find this in the URL when you're in your dbt Cloud environment. Lightdash will use this to identify which environment it should be built from, so commonly you'll point to your production environment here.
+
+##### Webhook for dbt
+
+This webhook is an optional extra for those using the dbt Cloud CI steps. If you set up a webhook that triggers when your dbt Cloud CI job completed, you can paste the webhook address and Lightdash will automatically spin up a preview for the given CI environment.
+
+##### Discovery API Endpoint
+
+The dbt specific endpoint for your dbt Cloud instance. You can find details on this in the [dbt Cloud API documentation](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#discovery-api-endpoints).
+
+***
+
+### CLI <a id="-cli" />
 
 The `CLI` connection type is the default type for projects that were created using the CLI via the `lightdash deploy --create` command.